Merge "Remove showcommands from docs" am: 25e4495d am: bd75f032

  An alternative to setting $TARGET_PRODUCT and $TARGET_BUILD_VARIANT,

  which you may see in build servers, is to execute:

    make PRODUCT-<product>-<variant>

    m PRODUCT-<product>-<variant>

  A target may be a file path. For example, out/host/linux-x86/bin/adb .

    files named Android.bp

      these files are defined in Blueprint syntax

  During a build, a few log files are generated in ${OUT} (or ${DIST_DIR}/logs

    for dist builds):

    verbose.log.gz

      every command run, along with its outputs. This is similar to the

      previous `m showcommands` option.

    error.log

      list of actions that failed during the build, and their outputs.

    soong.log

      verbose debug information from soong_ui

  For now, the full (extremely large) compiled list of targets can be found

    (after running the build once), split among these two files:

    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

  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

      I_AM_ANOTHER_SHELL_VAR=2 m 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

.c, .cpp, .h, .java, java libraries, etc., should all work without intervention

in the Android.mk file.</p>

<h3>Hiding command lines</h3>

<p>The default of the build system will be to hide the command lines being

executed for make steps.  It will be possible to override this by specifying

the showcommands pseudo-target, and possibly by setting an environment

variable.</p>

<h3>Wildcard source files</h3>

<p>Wildcarding source file will be discouraged.  It may be useful in some

scenarios.  The default <code>$(wildcard *)</code> will not work due to the

directory inside the current combo directory.  This is especially useful on the

simulator and emulator, where the persistent data remains present between 

builds.</li>

<li><b>showcommands</b> - <code>showcommands</code> is a modifier target

which causes the build system to show the actual command lines for the build

steps, instead of the brief descriptions.  Most people don't like seeing the

actual commands, because they're quite long and hard to read, but if you need

to for debugging purposes, you can add <code>showcommands</code> to the list

of targets you build.  For example <code>make showcommands</code> will build

the default android configuration, and <code>make runtime showcommands</code>

will build just the runtime, and targets that it depends on, while displaying

the full command lines.  Please note that there are a couple places where the

commands aren't shown here.  These are considered bugs, and should be fixed,

but they're often hard to track down.  Please let

<a href="mailto:android-build-team">android-build-team</a> know if you find

any.</li>

<li><b>LOCAL_MODULE</b> - Anything you specify as a <code>LOCAL_MODULE</code>

in an Android.mk is made into a pseudotarget.  For example, <code>make

runtime</code> might be shorthand for <code>make