Consolidate build system usage documentation into source control
Bug: 62201421
Test: make help
Change-Id: I7a7c917f767590657761396dd0545224ff98f27b
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..004210b
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,85 @@
+Android build system usage:
+
+m [-j] [<targets>] [<variable>=<value>...]
+
+
+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 [<product>-<variant>] # Selects the device and variant to target.
+ # Invoke the configured build.
+ m [<options>] [<targets>] [<variable>=<value>...]
+
+ <product> 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`.
+ <variant> 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 <options>, <targets>, and <variable>=<value> 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-<product>-<variant>
+
+
+ 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-<product>*.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 <N> Run <N> 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 <product> to build # as described above
+ TARGET_BUILD_VARIANT The <variant> 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 c034e79..0000000
--- 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 ae65832..55167c0 100644
--- a/envsetup.sh
+++ b/envsetup.sh
@@ -1,7 +1,13 @@
function hmm() {
cat <<EOF
+
+Run "m help" for help with the build system itself.
+
Invoke ". build/envsetup.sh" from your shell to add the following functions to your environment:
- lunch: lunch <product_name>-<build_variant>
+ Selects <product_name> as the product to build, and <build_variant> as the variant to
+ build, and stores those selections in the environment to be read by subsequent
+ invocations of 'm' etc.
- tapas: tapas [<App1> <App2> ...] [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 0000000..c031dcc
--- /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 [<product>-<variant>] # Choose the device to target.
+m -j [<goals>] # 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"