Merge "Consolidate build system usage documentation into source control"

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.
+

core/help.mk

@@ -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."

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.

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"