Consolidate build system usage documentation into source control

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.

#

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

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.

#!/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"