1# Build System Changes for Android.mk Writers
2
3## Deprecating / obsoleting envsetup.sh variables in Makefiles
4
5It is not required to source envsetup.sh before running a build. Many scripts,
6including a majority of our automated build systems, do not do so. Make will
7transparently make every environment variable available as a make variable.
8This means that relying on environment variables only set up in envsetup.sh will
9produce different output for local users and scripted users.
10
11Many of these variables also include absolute path names, which we'd like to
12keep out of the generated files, so that you don't need to do a full rebuild if
13you move the source tree.
14
15To fix this, we're marking the variables that are set in envsetup.sh as
16deprecated in the makefiles. This will trigger a warning every time one is read
17(or written) inside Kati. Once all the warnings have been removed for a
18particular variable, we'll switch it to obsolete, and any references will become
19errors.
20
21### envsetup.sh variables with make equivalents
22
23| instead of                                                   | use                  |
24|--------------------------------------------------------------|----------------------|
25| OUT {#OUT}                                                   | OUT_DIR              |
26| ANDROID_HOST_OUT {#ANDROID_HOST_OUT}                         | HOST_OUT             |
27| ANDROID_PRODUCT_OUT {#ANDROID_PRODUCT_OUT}                   | PRODUCT_OUT          |
28| ANDROID_HOST_OUT_TESTCASES {#ANDROID_HOST_OUT_TESTCASES}     | HOST_OUT_TESTCASES   |
29| ANDROID_TARGET_OUT_TESTCASES {#ANDROID_TARGET_OUT_TESTCASES} | TARGET_OUT_TESTCASES |
30
31All of the make variables may be relative paths from the current directory, or
32absolute paths if the output directory was specified as an absolute path. If you
33need an absolute variable, convert it to absolute during a rule, so that it's
34not expanded into the generated ninja file:
35
36``` make
37$(PRODUCT_OUT)/gen.img: my/src/path/gen.sh
38	export PRODUCT_OUT=$$(cd $(PRODUCT_OUT); pwd); cd my/src/path; ./gen.sh -o $${PRODUCT_OUT}/gen.img
39```
40
41### ANDROID_BUILD_TOP  {#ANDROID_BUILD_TOP}
42
43In Android.mk files, you can always assume that the current directory is the
44root of the source tree, so this can just be replaced with '.' (which is what
45$TOP is hardcoded to), or removed entirely. If you need an absolute path, see
46the instructions above.
47
48### Stop using PATH directly  {#PATH}
49
50This isn't only set by envsetup.sh, but it is modified by it. Due to that it's
51rather easy for this to change between different shells, and it's not ideal to
52reread the makefiles every time this changes.
53
54In most cases, you shouldn't need to touch PATH at all. When you need to have a
55rule reference a particular binary that's part of the source tree or outputs,
56it's preferrable to just use the path to the file itself (since you should
57already be adding that as a dependency).
58
59Depending on the rule, passing the file path itself may not be feasible due to
60layers of unchangable scripts/binaries. In that case, be sure to add the
61dependency, but modify the PATH within the rule itself:
62
63``` make
64$(TARGET): myscript my/path/binary
65	PATH=my/path:$$PATH myscript -o $@
66```
67
68### Stop using PYTHONPATH directly  {#PYTHONPATH}
69
70Like PATH, this isn't only set by envsetup.sh, but it is modified by it. Due to
71that it's rather easy for this to change between different shells, and it's not
72ideal to reread the makefiles every time.
73
74The best solution here is to start switching to Soong's python building support,
75which packages the python interpreter, libraries, and script all into one file
76that no longer needs PYTHONPATH. See fontchain_lint for examples of this:
77
78* [external/fonttools/Lib/fontTools/Android.bp] for python_library_host
79* [frameworks/base/Android.bp] for python_binary_host
80* [frameworks/base/data/fonts/Android.mk] to execute the python binary
81
82If you still need to use PYTHONPATH, do so within the rule itself, just like
83path:
84
85``` make
86$(TARGET): myscript.py $(sort $(shell find my/python/lib -name '*.py'))
87	PYTHONPATH=my/python/lib:$$PYTHONPATH myscript.py -o $@
88```
89### Stop using PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE directly {#PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE}
90
91Specify Framework Compatibility Matrix Version in device manifest by adding a `target-level`
92attribute to the root element `<manifest>`. If `PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE`
93is 26 or 27, you can add `"target-level"="1"` to your device manifest instead.
94
95### Stop using USE_CLANG_PLATFORM_BUILD {#USE_CLANG_PLATFORM_BUILD}
96
97Clang is the default and only supported Android compiler, so there is no reason
98for this option to exist.
99
100### Other envsetup.sh variables  {#other_envsetup_variables}
101
102* ANDROID_TOOLCHAIN
103* ANDROID_TOOLCHAIN_2ND_ARCH
104* ANDROID_DEV_SCRIPTS
105* ANDROID_EMULATOR_PREBUILTS
106* ANDROID_PRE_BUILD_PATHS
107
108These are all exported from envsetup.sh, but don't have clear equivalents within
109the makefile system. If you need one of them, you'll have to set up your own
110version.
111
112
113[build/soong/Changes.md]: https://android.googlesource.com/platform/build/soong/+/master/Changes.md
114[external/fonttools/Lib/fontTools/Android.bp]: https://android.googlesource.com/platform/external/fonttools/+/master/Lib/fontTools/Android.bp
115[frameworks/base/Android.bp]: https://android.googlesource.com/platform/frameworks/base/+/master/Android.bp
116[frameworks/base/data/fonts/Android.mk]: https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/Android.mk
117