1# Build System Changes for Android.mk Writers 2 3## Dexpreopt starts enforcing `<uses-library>` checks (for Java modules) 4 5In order to construct correct class loader context for dexpreopt, build system 6needs to know about the shared library dependencies of Java modules listed in 7the `<uses-library>` tags in the manifest. Since the build system does not have 8access to the manifest contents, that information must be present in the build 9files. In simple cases Soong is able to infer it from its knowledge of Java SDK 10libraries and the `libs` property in Android.bp, but in more complex cases it is 11necessary to add the missing information in Android.bp/Android.mk manually. 12 13To specify a list of libraries for a given modules, use: 14 15* Android.bp properties: `uses_libs`, `optional_uses_libs` 16* Android.mk variables: `LOCAL_USES_LIBRARIES`, `LOCAL_OPTIONAL_USES_LIBRARIES` 17 18If a library is in `libs`, it usually should *not* be added to the above 19properties, and Soong should be able to infer the `<uses-library>` tag. But 20sometimes a library also needs additional information in its 21Android.bp/Android.mk file (e.g. when it is a `java_library` rather than a 22`java_sdk_library`, or when the library name is different from its module name, 23or when the module is defined in Android.mk rather than Android.bp). In such 24cases it is possible to tell the build system that the library provides a 25`<uses-library>` with a given name (however, this is discouraged and will be 26deprecated in the future, and it is recommended to fix the underlying problem): 27 28* Android.bp property: `provides_uses_lib` 29* Android.mk variable: `LOCAL_PROVIDES_USES_LIBRARY` 30 31It is possible to disable the check on a per-module basis. When doing that it is 32also recommended to disable dexpreopt, as disabling a failed check will result 33in incorrect class loader context recorded in the .odex file, which will cause 34class loader context mismatch and dexopt at first boot. 35 36* Android.bp property: `enforce_uses_lib` 37* Android.mk variable: `LOCAL_ENFORCE_USES_LIBRARIES` 38 39Finally, it is possible to globally disable the check: 40 41* For a given product: `PRODUCT_BROKEN_VERIFY_USES_LIBRARIES := true` 42* On the command line: `RELAX_USES_LIBRARY_CHECK=true` 43 44The environment variable overrides the product variable, so it is possible to 45disable the check for a product, but quickly re-enable it for a local build. 46 47## `LOCAL_REQUIRED_MODULES` requires listed modules to exist {#BUILD_BROKEN_MISSING_REQUIRED_MODULES} 48 49Modules listed in `LOCAL_REQUIRED_MODULES`, `LOCAL_HOST_REQUIRED_MODULES` and 50`LOCAL_TARGET_REQUIRED_MODULES` need to exist unless `ALLOW_MISSING_DEPENDENCIES` 51is set. 52 53To temporarily relax missing required modules check, use: 54 55`BUILD_BROKEN_MISSING_REQUIRED_MODULES := true` 56 57## Changes in system properties settings 58 59### Product variables 60 61System properties for each of the partition is supposed to be set via following 62product config variables. 63 64For system partition, 65 66* `PRODUCT_SYSTEM_PROPERTIES` 67* `PRODUCT_SYSTEM_DEFAULT_PROPERTIES` is highly discouraged. Will be deprecated. 68 69For vendor partition, 70 71* `PRODUCT_VENDOR_PROPERTIES` 72* `PRODUCT_PROPERTY_OVERRIDES` is highly discouraged. Will be deprecated. 73* `PRODUCT_DEFAULT_PROPERTY_OVERRIDES` is also discouraged. Will be deprecated. 74 75For odm partition, 76 77* `PRODUCT_ODM_PROPERTIES` 78 79For system_ext partition, 80 81* `PRODUCT_SYSTEM_EXT_PROPERTIES` 82 83For product partition, 84 85* `PRODUCT_PRODUCT_PROPERTIES` 86 87### Duplication is not allowed within a partition 88 89For each partition, having multiple sysprop assignments for the same name is 90prohibited. For example, the following will now trigger an error: 91 92`PRODUCT_VENDOR_PROPERTIES += foo=true foo=false` 93 94Having duplication across partitions are still allowed. So, the following is 95not an error: 96 97`PRODUCT_VENDOR_PROPERTIES += foo=true` 98`PRODUCT_SYSTEM_PROPERTIES += foo=false` 99 100In that case, the final value is determined at runtime. The precedence is 101 102* product 103* odm 104* vendor 105* system_ext 106* system 107 108So, `foo` becomes `true` because vendor has higher priority than system. 109 110To temporarily turn the build-time restriction off, use 111 112`BUILD_BROKEN_DUP_SYSPROP := true` 113 114### Optional assignments 115 116System properties can now be set as optional using the new syntax: 117 118`name ?= value` 119 120Then the system property named `name` gets the value `value` only when there 121is no other non-optional assignments having the same name. For example, the 122following is allowed and `foo` gets `true` 123 124`PRODUCT_VENDOR_PROPERTIES += foo=true foo?=false` 125 126Note that the order between the optional and the non-optional assignments 127doesn't matter. The following gives the same result as above. 128 129`PRODUCT_VENDOR_PROPERTIES += foo?=false foo=true` 130 131Optional assignments can be duplicated and in that case their order matters. 132Specifically, the last one eclipses others. 133 134`PRODUCT_VENDOR_PROPERTIES += foo?=apple foo?=banana foo?=mango` 135 136With above, `foo` becomes `mango` since its the last one. 137 138Note that this behavior is different from the previous behavior of preferring 139the first one. To go back to the original behavior for compatability reason, 140use: 141 142`BUILD_BROKEN_DUP_SYSPROP := true` 143 144## ELF prebuilts in `PRODUCT_COPY_FILES` {#BUILD_BROKEN_ELF_PREBUILT_PRODUCT_COPY_FILES} 145 146ELF prebuilts in `PRODUCT_COPY_FILES` that are installed into these paths are an 147error: 148 149* `<partition>/bin/*` 150* `<partition>/lib/*` 151* `<partition>/lib64/*` 152 153Define prebuilt modules and add them to `PRODUCT_PACKAGES` instead. 154To temporarily relax this check and restore the behavior prior to this change, 155set `BUILD_BROKEN_ELF_PREBUILT_PRODUCT_COPY_FILES := true` in `BoardConfig.mk`. 156 157## COPY_HEADERS usage now produces warnings {#copy_headers} 158 159We've considered `BUILD_COPY_HEADERS`/`LOCAL_COPY_HEADERS` to be deprecated for 160a long time, and the places where it's been able to be used have shrinked over 161the last several releases. Equivalent functionality is not available in Soong. 162 163See the [build/soong/docs/best_practices.md#headers] for more information about 164how best to handle headers in Android. 165 166## `m4` is not available on `$PATH` 167 168There is a prebuilt of it available in prebuilts/build-tools, and a make 169variable `M4` that contains the path. 170 171Beyond the direct usage, whenever you use bison or flex directly, they call m4 172behind the scene, so you must set the M4 environment variable (and depend upon 173it for incremental build correctness): 174 175``` 176$(intermediates)/foo.c: .KATI_IMPLICIT_OUTPUTS := $(intermediates)/foo.h 177$(intermediates)/foo.c: $(LOCAL_PATH)/foo.y $(M4) $(BISON) $(BISON_DATA) 178 M4=$(M4) $(BISON) ... 179``` 180 181## Rules executed within limited environment 182 183With `ALLOW_NINJA_ENV=false` (soon to be the default), ninja, and all the 184rules/actions executed within it will only have access to a limited number of 185environment variables. Ninja does not track when environment variables change 186in order to trigger rebuilds, so changing behavior based on arbitrary variables 187is not safe with incremental builds. 188 189Kati and Soong can safely use environment variables, so the expectation is that 190you'd embed any environment variables that you need to use within the command 191line generated by those tools. See the [export section](#export_keyword) below 192for examples. 193 194For a temporary workaround, you can set `ALLOW_NINJA_ENV=true` in your 195environment to restore the previous behavior, or set 196`BUILD_BROKEN_NINJA_USES_ENV_VAR := <var> <var2> ...` in your `BoardConfig.mk` 197to allow specific variables to be passed through until you've fixed the rules. 198 199## LOCAL_C_INCLUDES outside the source/output trees are an error {#BUILD_BROKEN_OUTSIDE_INCLUDE_DIRS} 200 201Include directories are expected to be within the source tree (or in the output 202directory, generated during the build). This has been checked in some form 203since Oreo, but now has better checks. 204 205There's now a `BUILD_BROKEN_OUTSIDE_INCLUDE_DIRS` variable, that when set, will 206turn these errors into warnings temporarily. I don't expect this to last more 207than a release, since they're fairly easy to clean up. 208 209Neither of these cases are supported by Soong, and will produce errors when 210converting your module. 211 212### Absolute paths 213 214This has been checked since Oreo. The common reason to hit this is because a 215makefile is calculating a path, and ran abspath/realpath/etc. This is a problem 216because it makes your build non-reproducible. It's very unlikely that your 217source path is the same on every machine. 218 219### Using `../` to leave the source/output directories 220 221This is the new check that has been added. In every case I've found, this has 222been a mistake in the Android.mk -- assuming that `LOCAL_C_INCLUDES` (which is 223relative to the top of the source tree) acts like `LOCAL_SRC_FILES` (which is 224relative to `LOCAL_PATH`). 225 226Since this usually isn't a valid path, you can almost always just remove the 227offending line. 228 229 230## `BOARD_HAL_STATIC_LIBRARIES` and `LOCAL_HAL_STATIC_LIBRARIES` are obsolete {#BOARD_HAL_STATIC_LIBRARIES} 231 232Define proper HIDL / Stable AIDL HAL instead. 233 234* For libhealthd, use health HAL. See instructions for implementing 235 health HAL: 236 237 * [hardware/interfaces/health/2.1/README.md] for health 2.1 HAL (recommended) 238 * [hardware/interfaces/health/1.0/README.md] for health 1.0 HAL 239 240* For libdumpstate, use at least Dumpstate HAL 1.0. 241 242## PRODUCT_STATIC_BOOT_CONTROL_HAL is obsolete {#PRODUCT_STATIC_BOOT_CONTROL_HAL} 243 244`PRODUCT_STATIC_BOOT_CONTROL_HAL` was the workaround to allow sideloading with 245statically linked boot control HAL, before shared library HALs were supported 246under recovery. Android Q has added such support (HALs will be loaded in 247passthrough mode), and the workarounds are being removed. Targets should build 248and install the recovery variant of boot control HAL modules into recovery 249image, similar to the ones installed for normal boot. See the change to 250crosshatch for example of this: 251 252* [device/google/crosshatch/bootctrl/Android.bp] for `bootctrl.sdm845` building 253 rules 254* [device/google/crosshatch/device.mk] for installing `bootctrl.sdm845.recovery` 255 and `android.hardware.boot@1.0-impl.recovery` into recovery image 256 257[device/google/crosshatch/bootctrl/Android.bp]: https://android.googlesource.com/device/google/crosshatch/+/master/bootctrl/Android.bp 258[device/google/crosshatch/device.mk]: https://android.googlesource.com/device/google/crosshatch/+/master/device.mk 259 260## Deprecation of `BUILD_*` module types 261 262See [build/make/Deprecation.md](Deprecation.md) for the current status. 263 264## `PRODUCT_HOST_PACKAGES` split from `PRODUCT_PACKAGES` {#PRODUCT_HOST_PACKAGES} 265 266Previously, adding a module to `PRODUCT_PACKAGES` that supported both the host 267and the target (`host_supported` in Android.bp; two modules with the same name 268in Android.mk) would cause both to be built and installed. In many cases you 269only want either the host or target versions to be built/installed by default, 270and would be over-building with both. So `PRODUCT_PACKAGES` will be changing to 271just affect target modules, while `PRODUCT_HOST_PACKAGES` is being added for 272host modules. 273 274Functional differences between `PRODUCT_PACKAGES` and `PRODUCT_HOST_PACKAGES`: 275 276* `PRODUCT_HOST_PACKAGES` does not have `_ENG`/`_DEBUG` variants, as that's a 277 property of the target, not the host. 278* `PRODUCT_HOST_PACKAGES` does not support `LOCAL_MODULE_OVERRIDES`. 279* `PRODUCT_HOST_PACKAGES` requires listed modules to exist, and be host 280 modules. (Unless `ALLOW_MISSING_DEPENDENCIES` is set) 281 282This is still an active migration, so currently it still uses 283`PRODUCT_PACKAGES` to make installation decisions, but verifies that if we used 284`PRODUCT_HOST_PACKAGES`, it would trigger installation for all of the same host 285packages. This check ignores shared libraries, as those are not normally 286necessary in `PRODUCT_*PACKAGES`, and tended to be over-built (especially the 28732-bit variants). 288 289Future changes will switch installation decisions to `PRODUCT_HOST_PACKAGES` 290for host modules, error when there's a host-only module in `PRODUCT_PACKAGES`, 291and do some further cleanup where `LOCAL_REQUIRED_MODULES` are still merged 292between host and target modules with the same name. 293 294## `*.c.arm` / `*.cpp.arm` deprecation {#file_arm} 295 296In Android.mk files, you used to be able to change LOCAL_ARM_MODE for each 297source file by appending `.arm` to the end of the filename in 298`LOCAL_SRC_FILES`. 299 300Soong does not support this uncommonly used behavior, instead expecting those 301files to be split out into a separate static library that chooses `arm` over 302`thumb` for the entire library. This must now also be done in Android.mk files. 303 304## Windows cross-compiles no longer supported in Android.mk 305 306Modules that build for Windows (our only `HOST_CROSS` OS currently) must now be 307defined in `Android.bp` files. 308 309## `LOCAL_MODULE_TAGS := eng debug` are obsolete {#LOCAL_MODULE_TAGS} 310 311`LOCAL_MODULE_TAGS` value `eng` and `debug` are now obsolete. They allowed 312modules to specify that they should always be installed on `-eng`, or `-eng` 313and `-userdebug` builds. This conflicted with the ability for products to 314specify which modules should be installed, effectively making it impossible to 315build a stripped down product configuration that did not include those modules. 316 317For the equivalent functionality, specify the modules in `PRODUCT_PACKAGES_ENG` 318or `PRODUCT_PACKAGES_DEBUG` in the appropriate product makefiles. 319 320Core android packages like `su` got added to the list in 321`build/make/target/product/base_system.mk`, but for device-specific modules 322there are often better base product makefiles to use instead. 323 324## `USER` deprecation {#USER} 325 326`USER` will soon be `nobody` in many cases due to the addition of a sandbox 327around the Android build. Most of the time you shouldn't need to know the 328identity of the user running the build, but if you do, it's available in the 329make variable `BUILD_USERNAME` for now. 330 331Similarly, the `hostname` tool will also be returning a more consistent value 332of `android-build`. The real value is available as `BUILD_HOSTNAME`. 333 334## `BUILD_NUMBER` removal from Android.mk {#BUILD_NUMBER} 335 336`BUILD_NUMBER` should not be used directly in Android.mk files, as it would 337trigger them to be re-read every time the `BUILD_NUMBER` changes (which it does 338on every build server build). If possible, just remove the use so that your 339builds are more reproducible. If you do need it, use `BUILD_NUMBER_FROM_FILE`: 340 341``` make 342$(LOCAL_BUILT_MODULE): 343 mytool --build_number $(BUILD_NUMBER_FROM_FILE) -o $@ 344``` 345 346That will expand out to a subshell that will read the current `BUILD_NUMBER` 347whenever it's run. It will not re-run your command if the build number has 348changed, so incremental builds will have the build number from the last time 349the particular output was rebuilt. 350 351## `DIST_DIR`, `dist_goal`, and `dist-for-goals` {#dist} 352 353`DIST_DIR` and `dist_goal` are no longer available when reading Android.mk 354files (or other build tasks). Always use `dist-for-goals` instead, which takes 355a PHONY goal, and a list of files to copy to `$DIST_DIR`. Whenever `dist` is 356specified, and the goal would be built (either explicitly on the command line, 357or as a dependency of something on the command line), that file will be copied 358into `$DIST_DIR`. For example, 359 360``` make 361$(call dist-for-goals,foo,bar/baz) 362``` 363 364will copy `bar/baz` into `$DIST_DIR/baz` when `m foo dist` is run. 365 366#### Renames during copy 367 368Instead of specifying just a file, a destination name can be specified, 369including subdirectories: 370 371``` make 372$(call dist-for-goals,foo,bar/baz:logs/foo.log) 373``` 374 375will copy `bar/baz` into `$DIST_DIR/logs/foo.log` when `m foo dist` is run. 376 377## `.PHONY` rule enforcement {#phony_targets} 378 379There are several new warnings/errors meant to ensure the proper use of 380`.PHONY` targets in order to improve the speed and reliability of incremental 381builds. 382 383`.PHONY`-marked targets are often used as shortcuts to provide "friendly" names 384for real files to be built, but any target marked with `.PHONY` is also always 385considered dirty, needing to be rebuilt every build. This isn't a problem for 386aliases or one-off user-requested operations, but if real builds steps depend 387on a `.PHONY` target, it can get quite expensive for what should be a tiny 388build. 389 390``` make 391...mk:42: warning: PHONY target "out/.../foo" looks like a real file (contains a "/") 392``` 393 394Between this warning and the next, we're requiring that `.PHONY` targets do not 395have "/" in them, and real file targets do have a "/". This makes it more 396obvious when reading makefiles what is happening, and will help the build 397system differentiate these in the future too. 398 399``` make 400...mk:42: warning: writing to readonly directory: "kernel-modules" 401``` 402 403This warning will show up for one of two reasons: 404 4051. The target isn't intended to be a real file, and should be marked with 406 `.PHONY`. This would be the case for this example. 4072. The target is a real file, but it's outside the output directories. All 408 outputs from the build system should be within the output directory, 409 otherwise `m clean` is unable to clean the build, and future builds may not 410 work properly. 411 412``` make 413...mk:42: warning: real file "out/.../foo" depends on PHONY target "buildbins" 414``` 415 416If the first target isn't intended to be a real file, then it should be marked 417with `.PHONY`, which will satisfy this warning. This isn't the case for this 418example, as we require `.PHONY` targets not to have '/' in them. 419 420If the second (PHONY) target is a real file, it may unnecessarily be marked 421with `.PHONY`. 422 423### `.PHONY` and calling other build systems 424 425One common pattern (mostly outside AOSP) that we've seen hit these warning is 426when building with external build systems (firmware, bootloader, kernel, etc). 427Those are often marked as `.PHONY` because the Android build system doesn't 428have enough dependencies to know when to run the other build system again 429during an incremental build. 430 431We recommend to build these outside of Android, and deliver prebuilts into the 432Android tree instead of decreasing the speed and reliability of the incremental 433Android build. 434 435In cases where that's not desired, to preserve the speed of Android 436incrementals, over-specifying dependencies is likely a better option than 437marking it with `.PHONY`: 438 439``` make 440out/target/.../zImage: $(sort $(shell find -L $(KERNEL_SRCDIR))) 441 ... 442``` 443 444For reliability, many of these other build systems do not guarantee the same 445level of incremental build assurances as the Android Build is attempting to do 446-- without custom checks, Make doesn't rebuild objects when CFLAGS change, etc. 447In order to fix this, our recommendation is to do clean builds for each of 448these external build systems every time anything they rely on changes. For 449relatively smaller builds (like the kernel), this may be reasonable as long as 450you're not trying to actively debug the kernel. 451 452## `export` and `unexport` deprecation {#export_keyword} 453 454The `export` and `unexport` keywords are obsolete, and will throw errors when 455used. 456 457Device specific configuration should not be able to affect common core build 458steps -- we're looking at triggering build steps to be invalidated if the set 459of environment variables they can access changes. If device specific 460configuration is allowed to change those, switching devices with the same 461output directory could become significantly more expensive than it already can 462be. 463 464If used during Android.mk files, and later tasks, it is increasingly likely 465that they are being used incorrectly. Attempting to change the environment for 466a single build step, and instead setting it for hundreds of thousands. 467 468It is not recommended to just move the environment variable setting outside of 469the build (in vendorsetup.sh, or some other configuration script or wrapper). 470We expect to limit the environment variables that the build respects in the 471future, others will be cleared. (There will be methods to get custom variables 472into the build, just not to every build step) 473 474Instead, write the export commands into the rule command lines themselves: 475 476``` make 477$(intermediates)/generated_output.img: 478 rm -rf $@ 479 export MY_ENV_A="$(MY_A)"; make ... 480``` 481 482If you want to set many environment variables, and/or use them many times, 483write them out to a script and source the script: 484 485``` make 486envsh := $(intermediates)/env.sh 487$(envsh): 488 rm -rf $@ 489 echo 'export MY_ENV_A="$(MY_A)"' >$@ 490 echo 'export MY_ENV_B="$(MY_B)"' >>$@ 491 492$(intermediates)/generated_output.img: PRIVATE_ENV := $(envsh) 493$(intermediates)/generated_output.img: $(envsh) a/b/c/package.sh 494 rm -rf $@ 495 source $(PRIVATE_ENV); make ... 496 source $(PRIVATE_ENV); a/b/c/package.sh ... 497``` 498 499## Implicit make rules are obsolete {#implicit_rules} 500 501Implicit rules look something like the following: 502 503``` make 504$(TARGET_OUT_SHARED_LIBRARIES)/%_vendor.so: $(TARGET_OUT_SHARED_LIBRARIES)/%.so 505 ... 506 507%.o : %.foo 508 ... 509``` 510 511These can have wide ranging effects across unrelated modules, so they're now obsolete. Instead, use static pattern rules, which are similar, but explicitly match the specified outputs: 512 513``` make 514libs := $(foreach lib,libfoo libbar,$(TARGET_OUT_SHARED_LIBRARIES)/$(lib)_vendor.so) 515$(libs): %_vendor.so: %.so 516 ... 517 518files := $(wildcard $(LOCAL_PATH)/*.foo) 519gen := $(patsubst $(LOCAL_PATH)/%.foo,$(intermediates)/%.o,$(files)) 520$(gen): %.o : %.foo 521 ... 522``` 523 524## Removing '/' from Valid Module Names {#name_slash} 525 526The build system uses module names in path names in many places. Having an 527extra '/' or '../' being inserted can cause problems -- and not just build 528breaks, but stranger invalid behavior. 529 530In every case we've seen, the fix is relatively simple: move the directory into 531`LOCAL_MODULE_RELATIVE_PATH` (or `LOCAL_MODULE_PATH` if you're still using it). 532If this causes multiple modules to be named the same, use unique module names 533and `LOCAL_MODULE_STEM` to change the installed file name: 534 535``` make 536include $(CLEAR_VARS) 537LOCAL_MODULE := ver1/code.bin 538LOCAL_MODULE_PATH := $(TARGET_OUT_ETC)/firmware 539... 540include $(BUILD_PREBUILT) 541 542include $(CLEAR_VARS) 543LOCAL_MODULE := ver2/code.bin 544LOCAL_MODULE_PATH := $(TARGET_OUT_ETC)/firmware 545... 546include $(BUILD_PREBUILT) 547``` 548 549Can be rewritten as: 550 551``` 552include $(CLEAR_VARS) 553LOCAL_MODULE := ver1_code.bin 554LOCAL_MODULE_STEM := code.bin 555LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/firmware/ver1 556... 557include $(BUILD_PREBUILT) 558 559include $(CLEAR_VARS) 560LOCAL_MODULE := ver2_code.bin 561LOCAL_MODULE_STEM := code.bin 562LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/firmware/ver2 563... 564include $(BUILD_PREBUILT) 565``` 566 567You just need to make sure that any other references (`PRODUCT_PACKAGES`, 568`LOCAL_REQUIRED_MODULES`, etc) are converted to the new names. 569 570## Valid Module Names {#name} 571 572We've adopted lexical requirements very similar to [Bazel's 573requirements](https://docs.bazel.build/versions/master/build-ref.html#name) for 574target names. Valid characters are `a-z`, `A-Z`, `0-9`, and the special 575characters `_.+-=,@~`. This currently applies to `LOCAL_PACKAGE_NAME`, 576`LOCAL_MODULE`, and `LOCAL_MODULE_SUFFIX`, and `LOCAL_MODULE_STEM*`. 577 578Many other characters already caused problems if you used them, so we don't 579expect this to have a large effect. 580 581## PATH Tools {#PATH_Tools} 582 583The build has started restricting the external host tools usable inside the 584build. This will help ensure that build results are reproducible across 585different machines, and catch mistakes before they become larger issues. 586 587To start with, this includes replacing the $PATH with our own directory of 588tools, mirroring that of the host PATH. The only difference so far is the 589removal of the host GCC tools. Anything that is not explicitly in the 590configuration as allowed will continue functioning, but will generate a log 591message. This is expected to become more restrictive over time. 592 593The configuration is located in build/soong/ui/build/paths/config.go, and 594contains all the common tools in use in many builds. Anything not in that list 595will currently print a warning in the `$OUT_DIR/soong.log` file, including the 596command and arguments used, and the process tree in order to help locate the 597usage. 598 599In order to fix any issues brought up by these checks, the best way to fix them 600is to use tools checked into the tree -- either as prebuilts, or building them 601as host tools during the build. 602 603As a temporary measure, you can set `TEMPORARY_DISABLE_PATH_RESTRICTIONS=true` 604in your environment to temporarily turn off the error checks and allow any tool 605to be used (with logging). Beware that GCC didn't work well with the interposer 606used for logging, so this may not help in all cases. 607 608## Deprecating / obsoleting envsetup.sh variables in Makefiles 609 610It is not required to source envsetup.sh before running a build. Many scripts, 611including a majority of our automated build systems, do not do so. Make will 612transparently make every environment variable available as a make variable. 613This means that relying on environment variables only set up in envsetup.sh will 614produce different output for local users and scripted users. 615 616Many of these variables also include absolute path names, which we'd like to 617keep out of the generated files, so that you don't need to do a full rebuild if 618you move the source tree. 619 620To fix this, we're marking the variables that are set in envsetup.sh as 621deprecated in the makefiles. This will trigger a warning every time one is read 622(or written) inside Kati. Once all the warnings have been removed for a 623particular variable, we'll switch it to obsolete, and any references will become 624errors. 625 626### envsetup.sh variables with make equivalents 627 628| instead of | use | 629|--------------------------------------------------------------|----------------------| 630| OUT {#OUT} | PRODUCT_OUT | 631| ANDROID_HOST_OUT {#ANDROID_HOST_OUT} | HOST_OUT | 632| ANDROID_PRODUCT_OUT {#ANDROID_PRODUCT_OUT} | PRODUCT_OUT | 633| ANDROID_HOST_OUT_TESTCASES {#ANDROID_HOST_OUT_TESTCASES} | HOST_OUT_TESTCASES | 634| ANDROID_TARGET_OUT_TESTCASES {#ANDROID_TARGET_OUT_TESTCASES} | TARGET_OUT_TESTCASES | 635 636All of the make variables may be relative paths from the current directory, or 637absolute paths if the output directory was specified as an absolute path. If you 638need an absolute variable, convert it to absolute during a rule, so that it's 639not expanded into the generated ninja file: 640 641``` make 642$(PRODUCT_OUT)/gen.img: my/src/path/gen.sh 643 export PRODUCT_OUT=$$(cd $(PRODUCT_OUT); pwd); cd my/src/path; ./gen.sh -o $${PRODUCT_OUT}/gen.img 644``` 645 646### ANDROID_BUILD_TOP {#ANDROID_BUILD_TOP} 647 648In Android.mk files, you can always assume that the current directory is the 649root of the source tree, so this can just be replaced with '.' (which is what 650$TOP is hardcoded to), or removed entirely. If you need an absolute path, see 651the instructions above. 652 653### Stop using PATH directly {#PATH} 654 655This isn't only set by envsetup.sh, but it is modified by it. Due to that it's 656rather easy for this to change between different shells, and it's not ideal to 657reread the makefiles every time this changes. 658 659In most cases, you shouldn't need to touch PATH at all. When you need to have a 660rule reference a particular binary that's part of the source tree or outputs, 661it's preferrable to just use the path to the file itself (since you should 662already be adding that as a dependency). 663 664Depending on the rule, passing the file path itself may not be feasible due to 665layers of unchangable scripts/binaries. In that case, be sure to add the 666dependency, but modify the PATH within the rule itself: 667 668``` make 669$(TARGET): myscript my/path/binary 670 PATH=my/path:$$PATH myscript -o $@ 671``` 672 673### Stop using PYTHONPATH directly {#PYTHONPATH} 674 675Like PATH, this isn't only set by envsetup.sh, but it is modified by it. Due to 676that it's rather easy for this to change between different shells, and it's not 677ideal to reread the makefiles every time. 678 679The best solution here is to start switching to Soong's python building support, 680which packages the python interpreter, libraries, and script all into one file 681that no longer needs PYTHONPATH. See fontchain_lint for examples of this: 682 683* [external/fonttools/Lib/fontTools/Android.bp] for python_library_host 684* [frameworks/base/Android.bp] for python_binary_host 685* [frameworks/base/data/fonts/Android.mk] to execute the python binary 686 687If you still need to use PYTHONPATH, do so within the rule itself, just like 688path: 689 690``` make 691$(TARGET): myscript.py $(sort $(shell find my/python/lib -name '*.py')) 692 PYTHONPATH=my/python/lib:$$PYTHONPATH myscript.py -o $@ 693``` 694### Stop using PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE directly {#PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE} 695 696Specify Framework Compatibility Matrix Version in device manifest by adding a `target-level` 697attribute to the root element `<manifest>`. If `PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE` 698is 26 or 27, you can add `"target-level"="1"` to your device manifest instead. 699 700### Stop using USE_CLANG_PLATFORM_BUILD {#USE_CLANG_PLATFORM_BUILD} 701 702Clang is the default and only supported Android compiler, so there is no reason 703for this option to exist. 704 705### Other envsetup.sh variables {#other_envsetup_variables} 706 707* ANDROID_TOOLCHAIN 708* ANDROID_TOOLCHAIN_2ND_ARCH 709* ANDROID_DEV_SCRIPTS 710* ANDROID_EMULATOR_PREBUILTS 711* ANDROID_PRE_BUILD_PATHS 712 713These are all exported from envsetup.sh, but don't have clear equivalents within 714the makefile system. If you need one of them, you'll have to set up your own 715version. 716 717 718[build/soong/Changes.md]: https://android.googlesource.com/platform/build/soong/+/master/Changes.md 719[build/soong/docs/best_practices.md#headers]: https://android.googlesource.com/platform/build/soong/+/master/docs/best_practices.md#headers 720[external/fonttools/Lib/fontTools/Android.bp]: https://android.googlesource.com/platform/external/fonttools/+/master/Lib/fontTools/Android.bp 721[frameworks/base/Android.bp]: https://android.googlesource.com/platform/frameworks/base/+/master/Android.bp 722[frameworks/base/data/fonts/Android.mk]: https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/Android.mk 723[hardware/interfaces/health/1.0/README.md]: https://android.googlesource.com/platform/hardware/interfaces/+/master/health/1.0/README.md 724[hardware/interfaces/health/2.1/README.md]: https://android.googlesource.com/platform/hardware/interfaces/+/master/health/2.1/README.md 725