Skip to content

Commit 7733862

Browse files
danwdanw
committed
Mark envsetup.sh vars as deprecated in makefiles
For the envsetup.sh variables that should not be used in makefiles (since they're not explicitly set up, and won't be available on the build servers), mark them as deprecated. Rework our documentation to have a landing page, and create a "Changes" section where we can record changes like these. At some point I may go and backfill some recent work. Test: build/soong/build_test.bash Change-Id: I54b9294ddf270245afdb58d17150db8098584e8a
1 parent adbaeb0 commit 7733862

File tree

6 files changed

+151
-2
lines changed

6 files changed

+151
-2
lines changed

Diff for: ‎Changes.md

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

Diff for: ‎README.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Android Make Build System
2+
3+
This is the Makefile-based portion of the Android Build System.
4+
5+
For documentation on how to run a build, see [Usage.txt](Usage.txt)
6+
7+
For a list of behavioral changes useful for Android.mk writers see
8+
[Changes.md](Changes.md)
9+
10+
For an outdated reference on Android.mk files, see
11+
[build-system.html](/core/build-system.html). Our Android.mk files look similar,
12+
but are entirely different from the Android.mk files used by the NDK build
13+
system. When searching for documentation elsewhere, ensure that it is for the
14+
platform build system -- most are not.
15+
16+
This Makefile-based system is in the process of being replaced with [Soong], a
17+
new build system written in Go. During the transition, all of these makefiles
18+
are read by [Kati], and generate a ninja file instead of being executed
19+
directly. That's combined with a ninja file read by Soong so that the build
20+
graph of the two systems can be combined and run as one.
21+
22+
[Kati]: https://github.com/google/kati
23+
[Soong]: https://android.googlesource.com/platform/build/soong/+/master

Diff for: ‎README.txt renamed to ‎Usage.txt

File renamed without changes.

Diff for: ‎core/config.mk

+18-1
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,24 @@ backslash := $(patsubst %a,%,$(backslash))
5959
.DELETE_ON_ERROR:
6060

6161
# Mark variables deprecated/obsolete
62-
$(KATI_deprecated_var PATH,Do not use PATH directly)
62+
CHANGES_URL := https://android.googlesource.com/platform/build/+/master/Changes.md
63+
$(KATI_deprecated_var PATH,Do not use PATH directly. See $(CHANGES_URL)#PATH)
64+
$(KATI_deprecated_var PYTHONPATH,Do not use PYTHONPATH directly. See $(CHANGES_URL)#PYTHONPATH)
65+
$(KATI_deprecated_var OUT,Use OUT_DIR instead. See $(CHANGES_URL)#OUT)
66+
$(KATI_deprecated_var ANDROID_HOST_OUT,Use HOST_OUT instead. See $(CHANGES_URL)#ANDROID_HOST_OUT)
67+
$(KATI_deprecated_var ANDROID_PRODUCT_OUT,Use PRODUCT_OUT instead. See $(CHANGES_URL)#ANDROID_PRODUCT_OUT)
68+
$(KATI_deprecated_var ANDROID_HOST_OUT_TESTCASES,Use HOST_OUT_TESTCASES instead. See $(CHANGES_URL)#ANDROID_HOST_OUT_TESTCASES)
69+
$(KATI_deprecated_var ANDROID_TARGET_OUT_TESTCASES,Use TARGET_OUT_TESTCASES instead. See $(CHANGES_URL)#ANDROID_TARGET_OUT_TESTCASES)
70+
$(KATI_deprecated_var ANDROID_BUILD_TOP,Use '.' instead. See $(CHANGES_URL)#ANDROID_BUILD_TOP)
71+
$(KATI_deprecated_var \
72+
ANDROID_TOOLCHAIN \
73+
ANDROID_TOOLCHAIN_2ND_ARCH \
74+
ANDROID_DEV_SCRIPTS \
75+
ANDROID_EMULATOR_PREBUILTS \
76+
ANDROID_PRE_BUILD_PATHS \
77+
,See $(CHANGES_URL)#other_envsetup_variables)
78+
79+
CHANGES_URL :=
6380

6481
# Used to force goals to build. Only use for conditionally defined goals.
6582
.PHONY: FORCE

Diff for: ‎help.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ lunch [<product>-<variant>] # Choose the device to target.
1515
m -j [<goals>] # Execute the configured build.
1616
1717
Usage of "m" imitates usage of the program "make".
18-
See '"${SCRIPT_DIR}"'/README.txt for more info about build usage and concepts.
18+
See '"${SCRIPT_DIR}"'/Usage.txt for more info about build usage and concepts.
1919
2020
Common goals are:
2121

Diff for: ‎navbar.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
* [Home](/README.md)
2+
* [Usage](/Usage.txt)
3+
* [Changes](/Changes.md)
4+
* [Outdated Reference](/core/build-system.html)

0 commit comments

Comments
 (0)