aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDan Willemsen2017-11-08 18:39:18 -0600
committerDan Willemsen2017-11-28 16:19:50 -0600
commit773386251d2460576916a305cd1762581bff1a0b (patch)
treeaef62ae6b4ce53680610c218e72483319d0cd9a9 /Usage.txt
parentadbaeb0c1db1d3fdb00d937f3a6057e20b1877df (diff)
downloadplatform-build-773386251d2460576916a305cd1762581bff1a0b.tar.gz
platform-build-773386251d2460576916a305cd1762581bff1a0b.tar.xz
platform-build-773386251d2460576916a305cd1762581bff1a0b.zip
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
Diffstat (limited to 'Usage.txt')
-rw-r--r--Usage.txt85
1 files changed, 85 insertions, 0 deletions
diff --git a/Usage.txt b/Usage.txt
new file mode 100644
index 000000000..004210b47
--- /dev/null
+++ b/Usage.txt
@@ -0,0 +1,85 @@
1Android build system usage:
2
3m [-j] [<targets>] [<variable>=<value>...]
4
5
6Ways to specify what to build:
7 The common way to specify what to build is to set that information in the
8 environment via:
9
10 # Set up the shell environment.
11 source build/envsetup.sh # Run "hmm" after sourcing for more info
12 # Select the device and variant to target. If no argument is given, it
13 # will list choices and prompt.
14 lunch [<product>-<variant>] # Selects the device and variant to target.
15 # Invoke the configured build.
16 m [<options>] [<targets>] [<variable>=<value>...]
17
18 <product> is the device that the created image is intended to be run on.
19 This is saved in the shell environment as $TARGET_PRODUCT by `lunch`.
20 <variant> is one of "user", "userdebug", or "eng", and controls the
21 amount of debugging to be added into the generated image.
22 This gets saved in the shell environment as $TARGET_BUILD_VARIANT by
23 `lunch`.
24
25 Each of <options>, <targets>, and <variable>=<value> is optional.
26 If no targets are specified, the build system will build the images
27 for the configured product and variant.
28
29 An alternative to setting $TARGET_PRODUCT and $TARGET_BUILD_VARIANT,
30 which you may see in build servers, is to execute:
31
32 make PRODUCT-<product>-<variant>
33
34
35 A target may be a file path. For example, out/host/linux-x86/bin/adb .
36 Note that when giving a relative file path as a target, that path is
37 interpreted relative to the root of the source tree (rather than relative
38 to the current working directory).
39
40 A target may also be any other target defined within a Makefile. Run
41 `m help` to view the names of some common targets.
42
43 To view the modules and targets defined in a particular directory, look for:
44 files named *.mk (most commonly Android.mk)
45 these files are defined in Make syntax
46 files named Android.bp
47 these files are defined in Blueprint syntax
48
49 For now, the full (extremely large) compiled list of targets can be found
50 (after running the build once), split among these two files:
51
52 ${OUT}/build-<product>*.ninja
53 ${OUT}/soong/build.ninja
54
55 If you find yourself interacting with these files, you are encouraged to
56 provide a more convenient tool for browsing targets, and to mention the
57 tool here.
58
59Targets that adjust an existing build:
60 showcommands Display the individual commands run to implement
61 the build
62 dist Copy into ${DIST_DIR} the portion of the build
63 that must be distributed
64
65Flags
66 -j <N> Run <N> processes at once
67 -j Autodetect the number of processes to run at once,
68 and run that many
69
70Variables
71 Variables can either be set in the surrounding shell environment or can be
72 passed as command-line arguments. For example:
73 export I_AM_A_SHELL_VAR=1
74 I_AM_ANOTHER_SHELL_VAR=2 make droid I_AM_A_MAKE_VAR=3
75 Here are some common variables and their meanings:
76 TARGET_PRODUCT The <product> to build # as described above
77 TARGET_BUILD_VARIANT The <variant> to build # as described above
78 DIST_DIR The directory in which to place the distribution
79 artifacts.
80 OUT_DIR The directory in which to place non-distribution
81 artifacts.
82
83 There is not yet known a convenient method by which to discover the full
84 list of supported variables. Please mention it here when there is.
85