From c6dfc4e95a4c09fad1bf53091b658dacb504a76c Mon Sep 17 00:00:00 2001 From: Jeff Gaston Date: Tue, 30 May 2017 17:12:37 -0700 Subject: [PATCH] Consolidate build system usage documentation into source control Bug: 62201421 Test: make help Change-Id: I7a7c917f767590657761396dd0545224ff98f27b --- README.txt | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++ core/help.mk | 35 ---------------------- envsetup.sh | 6 ++++ help.sh | 53 ++++++++++++++++++++++++++++++++ 4 files changed, 144 insertions(+), 35 deletions(-) create mode 100644 README.txt delete mode 100644 core/help.mk create mode 100755 help.sh diff --git a/README.txt b/README.txt new file mode 100644 index 000000000..004210b47 --- /dev/null +++ b/README.txt @@ -0,0 +1,85 @@ +Android build system usage: + +m [-j] [] [=...] + + +Ways to specify what to build: + The common way to specify what to build is to set that information in the + environment via: + + # Set up the shell environment. + source build/envsetup.sh # Run "hmm" after sourcing for more info + # Select the device and variant to target. If no argument is given, it + # will list choices and prompt. + lunch [-] # Selects the device and variant to target. + # Invoke the configured build. + m [] [] [=...] + + is the device that the created image is intended to be run on. + This is saved in the shell environment as $TARGET_PRODUCT by `lunch`. + is one of "user", "userdebug", or "eng", and controls the + amount of debugging to be added into the generated image. + This gets saved in the shell environment as $TARGET_BUILD_VARIANT by + `lunch`. + + Each of , , and = is optional. + If no targets are specified, the build system will build the images + for the configured product and variant. + + An alternative to setting $TARGET_PRODUCT and $TARGET_BUILD_VARIANT, + which you may see in build servers, is to execute: + + make PRODUCT-- + + + A target may be a file path. For example, out/host/linux-x86/bin/adb . + Note that when giving a relative file path as a target, that path is + interpreted relative to the root of the source tree (rather than relative + to the current working directory). + + A target may also be any other target defined within a Makefile. Run + `m help` to view the names of some common targets. + + To view the modules and targets defined in a particular directory, look for: + files named *.mk (most commonly Android.mk) + these files are defined in Make syntax + files named Android.bp + these files are defined in Blueprint syntax + + For now, the full (extremely large) compiled list of targets can be found + (after running the build once), split among these two files: + + ${OUT}/build-*.ninja + ${OUT}/soong/build.ninja + + If you find yourself interacting with these files, you are encouraged to + provide a more convenient tool for browsing targets, and to mention the + tool here. + +Targets that adjust an existing build: + showcommands Display the individual commands run to implement + the build + dist Copy into ${DIST_DIR} the portion of the build + that must be distributed + +Flags + -j Run processes at once + -j Autodetect the number of processes to run at once, + and run that many + +Variables + Variables can either be set in the surrounding shell environment or can be + passed as command-line arguments. For example: + export I_AM_A_SHELL_VAR=1 + I_AM_ANOTHER_SHELL_VAR=2 make droid I_AM_A_MAKE_VAR=3 + Here are some common variables and their meanings: + TARGET_PRODUCT The to build # as described above + TARGET_BUILD_VARIANT The to build # as described above + DIST_DIR The directory in which to place the distribution + artifacts. + OUT_DIR The directory in which to place non-distribution + artifacts. + + There is not yet known a convenient method by which to discover the full + list of supported variables. Please mention it here when there is. + diff --git a/core/help.mk b/core/help.mk deleted file mode 100644 index c034e7911..000000000 --- a/core/help.mk +++ /dev/null @@ -1,35 +0,0 @@ -# -# Copyright (C) 2010 The Android Open Source Project -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# - -.PHONY: help -help: - @echo - @echo "Common make targets:" - @echo "----------------------------------------------------------------------------------" - @echo "droid Default target" - @echo "clean (aka clobber) equivalent to rm -rf out/" - @echo "snod Quickly rebuild the system image from built packages" - @echo "vnod Quickly rebuild the vendor image from built packages" - @echo "offline-sdk-docs Generate the HTML for the developer SDK docs" - @echo "doc-comment-check-docs Check HTML doc links & validity, without generating HTML" - @echo "libandroid_runtime All the JNI framework stuff" - @echo "framework All the java framework stuff" - @echo "services The system server (Java) and friends" - @echo "help You're reading it right now" - -.PHONY: out -out: - @echo "I'm sure you're nice and all, but no thanks." diff --git a/envsetup.sh b/envsetup.sh index ae65832a8..55167c023 100644 --- a/envsetup.sh +++ b/envsetup.sh @@ -1,7 +1,13 @@ function hmm() { cat <- + Selects as the product to build, and as the variant to + build, and stores those selections in the environment to be read by subsequent + invocations of 'm' etc. - tapas: tapas [ ...] [arm|x86|mips|armv5|arm64|x86_64|mips64] [eng|userdebug|user] - croot: Changes directory to the top of the tree. - m: Makes from the top of the tree. diff --git a/help.sh b/help.sh new file mode 100755 index 000000000..c031dcc7e --- /dev/null +++ b/help.sh @@ -0,0 +1,53 @@ +#!/bin/bash + +# locate some directories +cd "$(dirname $0)" +SCRIPT_DIR="${PWD}" +cd ../.. +TOP="${PWD}" + +message='The basic Android build process is: + +cd '"${TOP}"' +source build/envsetup.sh # Add "lunch" (and other utilities and variables) + # to the shell environment. +lunch [-] # Choose the device to target. +m -j [] # Execute the configured build. + +Usage of "m" imitates usage of the program "make". +See '"${SCRIPT_DIR}"'/README.txt for more info about build usage and concepts. + +Common goals are: + + clean (aka clobber) equivalent to rm -rf out/ + checkbuild Build every module defined in the source tree + droid Default target + nothing Do not build anything, just parse and validate the build structure + + java Build all the java code in the source tree + native Build all the native code in the source tree + + host Build all the host code (not to be run on a device) in the source tree + target Build all the target code (to be run on the device) in the source tree + + (java|native)-(host|target) + (host|target)-(java|native) + Build the intersection of the two given arguments + + snod Quickly rebuild the system image from built packages + Stands for "System, NO Dependencies" + vnod Quickly rebuild the vendor image from built packages + Stands for "Vendor, NO Dependencies" + + +So, for example, you could run: + +cd '"${TOP}"' +source build/envsetup.sh +lunch aosp_arm-userdebug +m -j java + +to build all of the java code for the userdebug variant of the aosp_arm device. +' + +echo "$message"