Adding a slightly reorganized version of skyler's revamped s.a.c.
Change-Id: I19439883c25d887fa4409b33a70c235af3a78eaf
diff --git a/src/porting/build_cookbook.md b/src/porting/build_cookbook.md
new file mode 100755
index 0000000..bda3768
--- /dev/null
+++ b/src/porting/build_cookbook.md
@@ -0,0 +1,536 @@
+# Build Cookbook #
+
+<p>The Android Build Cookbook offers code snippets to help you quickly implement some common build tasks. For additional instruction, please see the other build documents in this section.</p>
+<h3><a name="simpleAPK"></a>Building a simple APK</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+</pre>
+<h3><a name="APKJar"></a>Building a APK that depends on a static .jar file</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # List of static libraries to include in the package
+ LOCAL_STATIC_JAVA_LIBRARIES := static-library
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+</pre>
+<h3><a name="APKPlatform"></a>Building a APK that should be signed with the platform key</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ LOCAL_CERTIFICATE := platform
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+</pre>
+<h3><a name="APKVendor"></a>Building a APK that should be signed with a specific vendor key</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Name of the APK to build
+ LOCAL_PACKAGE_NAME := LocalPackage
+
+ LOCAL_CERTIFICATE := vendor/example/certs/app
+
+ # Tell it to build an APK
+ include $(BUILD_PACKAGE)
+</pre>
+<h3><a name="prebuiltAPK"></a>Adding a prebuilt APK</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Module name should match apk name to be installed.
+ LOCAL_MODULE := LocalModuleName
+ LOCAL_SRC_FILES := $(LOCAL_MODULE).apk
+ LOCAL_MODULE_CLASS := APPS
+ LOCAL_MODULE_SUFFIX := $(COMMON_ANDROID_PACKAGE_SUFFIX)
+
+ include $(BUILD_PREBUILT)
+</pre>
+<h3><a name="staticJava"></a>Adding a Static Java Library</h3>
+<pre>
+ LOCAL_PATH := $(call my-dir)
+ include $(CLEAR_VARS)
+
+ # Build all java files in the java subdirectory
+ LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+ # Any libraries that this library depends on
+ LOCAL_JAVA_LIBRARIES := android.test.runner
+
+ # The name of the jar file to create
+ LOCAL_MODULE := sample
+
+ # Build a static jar file.
+ include $(BUILD_STATIC_JAVA_LIBRARY)
+</pre>
+<h3><a name="mkVars"></a>Android.mk Variables</h3>
+
+<p>These are the variables that you'll commonly see in Android.mk files, listed
+alphabetically. First, a note on the variable naming: </p>
+
+<ul>
+ <li><b>LOCAL_</b> - These variables are set per-module. They are cleared
+ by the <code>include $(CLEAR_VARS)</code> line, so you can rely on them
+ being empty after including that file. Most of the variables you'll use
+ in most modules are LOCAL_ variables.</li>
+ <li><b>PRIVATE_</b> - These variables are make-target-specific variables. That
+ means they're only usable within the commands for that module. It also
+ means that they're unlikely to change behind your back from modules that
+ are included after yours. This
+ <a href="http://www.gnu.org/software/make/manual/make.html#Target_002dspecific">link to the make documentation</a>
+ describes more about target-specific variables.
+ </li>
+ <li><b>HOST_</b> and <b>TARGET_</b> - These contain the directories
+ and definitions that are specific to either the host or the target builds.
+ Do not set variables that start with HOST_ or TARGET_ in your makefiles.
+ </li>
+ <li><b>BUILD_</b> and <b>CLEAR_VARS</b> - These contain the names of
+ well-defined template makefiles to include. Some examples are CLEAR_VARS
+ and BUILD_HOST_PACKAGE.</li>
+ <li>Any other name is fair-game for you to use in your Android.mk. However,
+ remember that this is a non-recursive build system, so it is possible that
+ your variable will be changed by another Android.mk included later, and be
+ different when the commands for your rule / module are executed.</li>
+</ul>
+
+<table border=1 cellpadding=2 cellspacing=0>
+ <tbody><tr>
+ <th scope="col">Parameter</th>
+ <th scope="col">Description</th>
+ </tr>
+<tr>
+<td valign="top">LOCAL_AAPT_FLAGS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ACP_UNAVAILABLE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ADDITIONAL_JAVA_DIR</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_AIDL_INCLUDES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ALLOW_UNDEFINED_SYMBOLS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ARM_MODE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ASFLAGS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ASSET_DIR</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_ASSET_FILES</td>
+<td valign="top">In Android.mk files that <code>include $(BUILD_PACKAGE)</code> set this
+to the set of files you want built into your app. Usually:</p>
+<p><code>LOCAL_ASSET_FILES += $(call find-subdir-assets)</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_BUILT_MODULE_STEM</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_C_INCLUDES</td>
+<td valign="top"><p>Additional directories to instruct the C/C++ compilers to look for header
+files in. These paths are rooted at the top of the tree. Use
+<code>LOCAL_PATH</code> if you have subdirectories of your own that you
+want in the include paths. For example:</p>
+<p><code>
+LOCAL_C_INCLUDES += extlibs/zlib-1.2.3<br/>
+LOCAL_C_INCLUDES += $(LOCAL_PATH)/src
+</code></p>
+<p>You should not add subdirectories of include to
+<code>LOCAL_C_INCLUDES</code>, instead you should reference those files
+in the <code>#include</code> statement with their subdirectories. For
+example:</p>
+<p><code>#include <utils/KeyedVector.h></code><br/>
+not <code><s>#include <KeyedVector.h></s></code></p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CC</td>
+<td valign="top">If you want to use a different C compiler for this module, set LOCAL_CC
+to the path to the compiler. If LOCAL_CC is blank, the appropriate default
+compiler is used.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CERTIFICATE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CFLAGS</td>
+<td valign="top">If you have additional flags to pass into the C or C++ compiler, add
+them here. For example:</p>
+<p><code>LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CLASSPATH</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_COMPRESS_MODULE_SYMBOLS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_COPY_HEADERS</td>
+<td valign="top"><p>The set of files to copy to the install include tree. You must also
+supply <code>LOCAL_COPY_HEADERS_TO</code>.</p>
+<p>This is going away because copying headers messes up the error messages, and
+may lead to people editing those headers instead of the correct ones. It also
+makes it easier to do bad layering in the system, which we want to avoid. We
+also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any
+headers.</p></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_COPY_HEADERS_TO</td>
+<td valign="top"><p>The directory within "include" to copy the headers listed in
+<code>LOCAL_COPY_HEADERS</code> to.</p>
+<p>This is going away because copying headers messes up the error messages, and
+may lead to people editing those headers instead of the correct ones. It also
+makes it easier to do bad layering in the system, which we want to avoid. We
+also aren't doing a C/C++ SDK, so there is no ultimate requirement to copy any
+headers.</p></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CPP_EXTENSION</td>
+<td valign="top">If your C++ files end in something other than "<code>.cpp</code>",
+you can specify the custom extension here. For example:
+<p><code>LOCAL_CPP_EXTENSION := .cc</code></p>
+Note that all C++ files for a given module must have the same
+extension; it is not currently possible to mix different extensions.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CPPFLAGS</td>
+<td valign="top">If you have additional flags to pass into <i>only</i> the C++ compiler, add
+them here. For example:</p>
+<p><code>LOCAL_CPPFLAGS += -ffriend-injection</code></p>
+<code>LOCAL_CPPFLAGS</code> is guaranteed to be after <code>LOCAL_CFLAGS</code>
+on the compile line, so you can use it to override flags listed in
+<code>LOCAL_CFLAGS</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_CXX</td>
+<td valign="top">If you want to use a different C++ compiler for this module, set LOCAL_CXX
+to the path to the compiler. If LOCAL_CXX is blank, the appropriate default
+compiler is used.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_DX_FLAGS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_EXPORT_PACKAGE_RESOURCES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_FORCE_STATIC_EXECUTABLE</td>
+<td valign="top"><p>If your executable should be linked statically, set
+<code>LOCAL_FORCE_STATIC_EXECUTABLE:=true</code>. There is a very short
+list of libraries that we have in static form (currently only libc). This is
+really only used for executables in /sbin on the root filesystem.</p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_GENERATED_SOURCES</td>
+<td valign="top"><p>Files that you add to <code>LOCAL_GENERATED_SOURCES</code> will be
+automatically generated and then linked in when your module is built.
+See the <a href="#custom-tools">Custom Tools</a> template makefile for an
+example.</p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_INSTRUMENTATION_FOR</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_INSTRUMENTATION_FOR_PACKAGE_NAME</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_INTERMEDIATE_SOURCES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_INTERMEDIATE_TARGETS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_IS_HOST_MODULE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JAR_MANIFEST</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JARJAR_RULES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JAVA_LIBRARIES</td>
+<td valign="top"><p>When linking Java apps and libraries, <code>LOCAL_JAVA_LIBRARIES</code>
+specifies which sets of java classes to include. Currently there are
+two of these: <code>core</code> and <code>framework</code>.
+In most cases, it will look like this:</p>
+<p><code>LOCAL_JAVA_LIBRARIES := core framework</code></p>
+<p>Note that setting <code>LOCAL_JAVA_LIBRARIES</code> is not necessary
+(and is not allowed) when building an APK with
+"<code>include $(BUILD_PACKAGE)</code>". The appropriate libraries
+will be included automatically.</p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JAVA_RESOURCE_DIRS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JAVA_RESOURCE_FILES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_JNI_SHARED_LIBRARIES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_LDFLAGS</td>
+<td valign="top"><p>You can pass additional flags to the linker by setting
+<code>LOCAL_LDFLAGS</code>. Keep in mind that the order of parameters is
+very important to ld, so test whatever you do on all platforms.</p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_LDLIBS</td>
+<td valign="top"><p><code>LOCAL_LDLIBS</code> allows you to specify additional libraries
+that are not part of the build for your executable or library. Specify
+the libraries you want in -lxxx format; they're passed directly to the
+link line. However, keep in mind that there will be no dependency generated
+for these libraries. It's most useful in simulator builds where you want
+to use a library preinstalled on the host. The linker (ld) is a particularly
+fussy beast, so it's sometimes necessary to pass other flags here if you're
+doing something sneaky. Some examples:</p>
+<p><code>LOCAL_LDLIBS += -lcurses -lpthread<br/>
+LOCAL_LDLIBS += -Wl,-z,origin
+</code></p> </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_MODULE</td>
+<td valign="top"><code>LOCAL_MODULE</code> is the name of what's supposed to be generated
+from your Android.mk. For exmample, for libkjs, the <code>LOCAL_MODULE</code>
+is "libkjs" (the build system adds the appropriate suffix -- .so .dylib .dll).
+For app modules, use <code>LOCAL_PACKAGE_NAME</code> instead of
+<code>LOCAL_MODULE</code>. </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_MODULE_PATH</td>
+<td valign="top">Instructs the build system to put the module somewhere other than what's
+normal for its type. If you override this, make sure you also set
+<code>LOCAL_UNSTRIPPED_PATH</code> if it's an executable or a shared library
+so the unstripped binary has somewhere to go. An error will occur if you forget
+to.</p>
+<p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_MODULE_STEM</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_MODULE_TAGS</td>
+<td valign="top"><p>Set <code>LOCAL_MODULE_TAGS</code> to any number of whitespace-separated
+tags. <p>This variable controls what build flavors the package gets included in. For example:</p>
+<ul type="disc">
+ <li><code>user</code>: include this in user/userdebug builds</li>
+ <li><code>eng</code>: include this in eng builds</li>
+ <li><code>tests</code>: the target is a testing target and makes it available for tests</li>
+ <li><code>optional</code>: don't include this</li>
+</ul></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_NO_DEFAULT_COMPILER_FLAGS</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_NO_EMMA_COMPILE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_NO_EMMA_INSTRUMENT</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_NO_STANDARD_LIBRARIES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_OVERRIDES_PACKAGES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PACKAGE_NAME</td>
+<td valign="top"><code>LOCAL_PACKAGE_NAME</code> is the name of an app. For example,
+Dialer, Contacts, etc. </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_POST_PROCESS_COMMAND</td>
+<td valign="top"><p>For host executables, you can specify a command to run on the module
+after it's been linked. You might have to go through some contortions
+to get variables right because of early or late variable evaluation:</p>
+<p><code>module := $(HOST_OUT_EXECUTABLES)/$(LOCAL_MODULE)<br/>
+LOCAL_POST_PROCESS_COMMAND := /Developer/Tools/Rez -d __DARWIN__ -t APPL\<br/>
+ -d __WXMAC__ -o $(module) Carbon.r
+</code></p>
+ </td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PREBUILT_EXECUTABLES</td>
+<td valign="top">When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to
+executables that you want copied. They're located automatically into the
+right bin directory.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PREBUILT_JAVA_LIBRARIES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PREBUILT_LIBS</td>
+<td valign="top">When including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to
+libraries that you want copied. They're located automatically into the
+right lib directory.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PREBUILT_OBJ_FILES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PREBUILT_STATIC_JAVA_LIBRARIES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_PRELINK_MODULE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_REQUIRED_MODULES</td>
+<td valign="top"><p>Set <code>LOCAL_REQUIRED_MODULES</code> to any number of whitespace-separated
+module names, like "libblah" or "Email". If this module is installed, all
+of the modules that it requires will be installed as well. This can be
+used to, e.g., ensure that necessary shared libraries or providers are
+installed when a given app is installed.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_RESOURCE_DIR</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_SDK_VERSION</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_SHARED_LIBRARIES</td>
+<td valign="top">These are the libraries you directly link against. You don't need to
+pass transitively included libraries. Specify the name without the suffix:</p>
+<p><code>LOCAL_SHARED_LIBRARIES := \<br/>
+ libutils \<br/>
+ libui \<br/>
+ libaudio \<br/>
+ libexpat \<br/>
+ libsgl
+</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_SRC_FILES</td>
+<td valign="top">The build system looks at <code>LOCAL_SRC_FILES</code> to know what source
+files to compile -- .cpp .c .y .l .java. For lex and yacc files, it knows
+how to correctly do the intermediate .h and .c/.cpp files automatically. If
+the files are in a subdirectory of the one containing the Android.mk, prefix
+them with the directory name:</p>
+<p><code>LOCAL_SRC_FILES := \<br/>
+ file1.cpp \<br/>
+ dir/file2.cpp
+</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_STATIC_JAVA_LIBRARIES</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_STATIC_LIBRARIES</td>
+<td valign="top">These are the static libraries that you want to include in your module.
+Mostly, we use shared libraries, but there are a couple of places, like
+executables in sbin and host executables where we use static libraries instead.
+<p><code>LOCAL_STATIC_LIBRARIES := \<br/>
+ libutils \<br/>
+ libtinyxml
+</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_UNINSTALLABLE_MODULE</td>
+<td valign="top"></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_UNSTRIPPED_PATH</td>
+<td valign="top">Instructs the build system to put the unstripped version of the module
+somewhere other than what's normal for its type. Usually, you override this
+because you overrode <code>LOCAL_MODULE_PATH</code> for an executable or a
+shared library. If you overrode <code>LOCAL_MODULE_PATH</code>, but not
+<code>LOCAL_UNSTRIPPED_PATH</code>, an error will occur.</p>
+<p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</td>
+</tr>
+<tr>
+<td valign="top">LOCAL_WHOLE_STATIC_LIBRARIES</td>
+<td valign="top">These are the static libraries that you want to include in your module without allowing
+the linker to remove dead code from them. This is mostly useful if you want to add a static library
+to a shared library and have the static library's content exposed from the shared library.
+<p><code>LOCAL_WHOLE_STATIC_LIBRARIES := \<br/>
+ libsqlite3_android<br/>
+</code></td>
+</tr>
+<tr>
+<td valign="top">LOCAL_YACCFLAGS</td>
+<td valign="top">Any flags to pass to invocations of yacc for your module. A known limitation
+here is that the flags will be the same for all invocations of YACC for your
+module. This can be fixed. If you ever need it to be, just ask.</p>
+<p><code>LOCAL_YACCFLAGS := -p kjsyy</code></td>
+</tr>
+<tr>
+<td valign="top">OVERRIDE_BUILT_MODULE_PATH</td>
+<td valign="top"></td>
+</tr>
+
+</table>