--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<!--
+ A lot of people read this document template. Please keep it clean:
+
+ - keep the document xhtml-compliant, as many people use validating editors
+ - check your edits for typos, spelling errors, and questionable grammar
+ - prefer css styles to formatting tags like <font>, <tt>, etc.
+ - keep it human-readable and human-editable in a plain text editor:
+ - strive to keep lines wrapped at 80 columns, unless a link prevents it
+ - use plenty of whitespace
+ - try to pretty-format (wrt nesting and indenting) any hairy html
+ - check your inline javascript for errors using the javascript console
+
+ Your readers will be very appreciative.
+-->
+
+<head>
+ <title>Android Build System</title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <link href="../android.css" type="text/css" rel="stylesheet" />
+
+<!-- commenting out so the xhtml validator doesn't whine about < and &&;
+ the browser should still find the script tag. -->
+<script language="JavaScript1.2" type="text/javascript">
+<!--
+function highlight(name) {
+ if (document.getElementsByTagName) {
+ tags = [ 'span', 'div', 'tr', 'td' ];
+ for (i in tags) {
+ elements = document.getElementsByTagName(tags[i]);
+ if (elements) {
+ for (j = 0; j < elements.length; j++) {
+ elementName = elements[j].getAttribute("class");
+ if (elementName == name) {
+ elements[j].style.backgroundColor = "#C0F0C0";
+ } else if (elementName && elementName.indexOf("rev") == 0) {
+ elements[j].style.backgroundColor = "#FFFFFF";
+ }
+ }
+ }
+ }
+ }
+}
+//-->
+ </script>
+ <!-- this style sheet is for the style of the toc -->
+ <link href="toc.css" type="text/css" rel="stylesheet" />
+
+ <style type="text/css">
+ .warning {
+ border: 1px solid red;
+ padding: 8px;
+ color: red;
+ }
+ pre.prettyprint {
+ margin-top: 0;
+ }
+ li {
+ margin-top: 8px;
+ }
+ </style>
+</head>
+
+<body onload="prettyPrint()">
+
+<h1><a name="My_Project_" />Android Build System</h1>
+
+<!-- Status is one of: Draft, Current, Needs Update, Obsolete -->
+<p style="text-align:center">
+ <strong>Status:</strong> <em>Draft </em>
+ <small>(as of May 18, 2006)</small>
+</p>
+
+<p><b>Contents</b></p>
+<!-- this div expands out to a list of contents based on the H2 and H3 headings.
+Believe it! -->
+ <div id="nav" class="nav-2-levels"></div>
+
+<h2>Objective</h2>
+<p>The primary goals of reworking the build system are (1) to make dependencies
+work more reliably, so that when files need to rebuilt, they are, and (2) to
+improve performance of the build system so that unnecessary modules are not
+rebuilt, and so doing a top-level build when little or nothing needs to be done
+for a build takes as little time as possible.</p>
+
+<h2>Principles and Use Cases and Policy</h2>
+<p>Given the above objective, these are the overall principles and use cases
+that we will support. This is not an exhaustive list.</p>
+<h3>Multiple Targets</h3>
+<p>It needs to be possible to build the Android platform for multiple targets.
+This means:</p>
+<ul>
+ <li>The build system will support building tools for the host platform,
+ both ones that are used in the build process itself, and developer tools
+ like the simulator.</li>
+ <li>The build system will need to be able to build tools on Linux
+ (definitely Goobuntu and maybe Grhat), MacOS, and to some degree on
+ Windows.</li>
+ <li>The build system will need to be able to build the OS on Linux, and in
+ the short-term, MacOS. Note that this is a conscious decision to stop
+ building the OS on Windows. We are going to rely on the emulator there
+ and not attempt to use the simulator. This is a requirement change now
+ that the emulator story is looking brighter.</li>
+</ul>
+<h3>Non-Recursive Make</h3>
+<p>To achieve the objectives, the build system will be rewritten to use make
+non-recursively. For more background on this, read <a href="http://aegis.sourceforge.net/auug97.pdf">Recursive Make Considered Harmful</a>. For those that don't
+want PDF, here is the
+<a href="http://72.14.203.104/search?q=cache:HwuX7YF2uBIJ:aegis.sourceforge.net/auug97.pdf&hl=en&gl=us&ct=clnk&cd=2&client=firefox">Google translated version</a>.
+<h3>Rapid Compile-Test Cycles</h3>
+<p>When developing a component, for example a C++ shared library, it must be
+possible to easily rebuild just that component, and not have to wait more than a
+couple seconds for dependency checks, and not have to wait for unneeded
+components to be built.</p>
+<h3>Both Environment and Config File Based Settings</h3>
+<p>To set the target, and other options, some people on the team like to have a
+configuration file in a directory so they do not have an environment setup
+script to run, and others want an environment setup script to run so they can
+run builds in different terminals on the same tree, or switch back and forth
+in one terminal. We will support both.</p>
+<h3>Object File Directory / make clean</h3>
+<p>Object files and other intermediate files will be generated into a directory
+that is separate from the source tree. The goal is to have make clean be
+"rm -rf <obj>" in the tree root directory. The primary goals of
+this are to simplify searching the source tree, and to make "make clean" more
+reliable.</p>
+
+<h3>SDK</h3>
+<p>The SDK will be a tarball that will allow non-OS-developers to write apps.
+The apps will actually be built by first building the SDK, and then building
+the apps against that SDK. This will hopefully (1) make writing apps easier
+for us, because we won't have to rebuild the OS as much, and we can use the
+standard java-app development tools, and (2) allow us to dog-food the SDK, to
+help ensure its quality. Cedric has suggested (and I agree) that apps built
+from the SDK should be built with ant. Stay tuned for more details as we
+figure out exactly how this will work.</p>
+
+<h3>Dependecies</h3>
+<p>Dependencies should all be automatic. Unless there is a custom tool involved
+(e.g. the webkit has several), the dependencies for shared and static libraries,
+.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
+current directory being set to the root of the build tree.<p>
+
+<h3>Multiple targets in one directory</h3>
+<p>It will be possible to generate more than one target from a given
+subdirectory. For example, libutils generates a shared library for the target
+and a static library for the host.</p>
+
+<h3>Makefile fragments for modules</h3>
+<p><b>Android.mk</b> is the standard name for the makefile fragments that
+control the building of a given module. Only the top directory should
+have a file named "Makefile".</p>
+
+<h3>Use shared libraries</h3>
+<p>Currently, the simulator is not built to use shared libraries. This should
+be fixed, and now is a good time to do it. This implies getting shared
+libraries to work on Mac OS.</p>
+
+
+<h2>Nice to Have</h2>
+
+<p>These things would be nice to have, and this is a good place to record them,
+however these are not promises.</p>
+
+<h3>Simultaneous Builds</h3>
+<p>The hope is to be able to do two builds for different combos in the same
+tree at the same time, but this is a stretch goal, not a requirement.
+Doing two builds in the same tree, not at the same time must work. (update:
+it's looking like we'll get the two builds at the same time working)</p>
+
+<h3>Deleting headers (or other dependecies)</h3>
+<p>Problems can arise if you delete a header file that is referenced in
+".d" files. The easy way to deal with this is "make clean". There
+should be a better way to handle it. (from fadden)</p>
+<p>One way of solving this is introducing a dependency on the directory. The
+problem is that this can create extra dependecies and slow down the build.
+It's a tradeoff.</p>
+
+<h3>Multiple builds</h3>
+<p>General way to perform builds across the set of known platforms. This
+would make it easy to perform multiple platform builds when testing a
+change, and allow a wide-scale "make clean". Right now the buildspec.mk
+or environment variables need to be updated before each build. (from fadden)</p>
+
+<h3>Aftermarket Locales and Carrier</h3>
+<p>We will eventually need to add support for creating locales and carrier
+customizations to the SDK, but that will not be addressed right now.</p>
+
+
+<h2><a id="usage"/>Usage</h2>
+<p>You've read (or scrolled past) all of the motivations for this build system,
+and you want to know how to use it. This is the place.</p>
+
+<h3>Your first build</h3>
+<p>The <a href="../building.html">Building</a> document describes how do do
+builds.</p>
+
+<h3>build/envsetup.sh functions</h3>
+If you source the file build/envsetup.sh into your bash environment,
+<code>. build/envsetup.sh</code>you'll get a few helpful shell functions:
+
+<ul>
+<li><b>printconfig</b> - Prints the current configuration as set by the
+lunch and choosecombo commands.</li>
+<li><b>m</b> - Runs <code>make</code> from the top of the tree. This is
+useful because you can run make from within subdirectories. If you have the
+<code>TOP</code> environment variable set, it uses that. If you don't, it looks
+up the tree from the current directory, trying to find the top of the tree.</li>
+<li><b>croot</b> - <code>cd</code> to the top of the tree.</li>
+<li><b>sgrep</b> - grep for the regex you provide in all .c, .cpp, .h, .java,
+and .xml files below the current directory.</li>
+</ul>
+
+<h3>Build flavors/types</h3>
+<p>
+When building for a particular product, it's often useful to have minor
+variations on what is ultimately the final release build. These are the
+currently-defined "flavors" or "types" (we need to settle on a real name
+for these).
+</p>
+
+<table border=1>
+<tr>
+ <td>
+ <code>eng<code>
+ </td>
+ <td>
+ This is the default flavor. A plain "<code>make</code>" is the
+ same as "<code>make eng</code>". <code>droid</code> is an alias
+ for <code>eng</code>.
+ <ul>
+ <li>Installs modules tagged with: <code>eng</code>, <code>debug</code>,
+ <code>user</code>, and/or <code>development</code>.
+ <li>Installs non-APK modules that have no tags specified.
+ <li>Installs APKs according to the product definition files, in
+ addition to tagged APKs.
+ <li><code>ro.secure=0</code>
+ <li><code>ro.debuggable=1</code>
+ <li><code>ro.kernel.android.checkjni=1</code>
+ <li><code>adb</code> is enabled by default.
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>user<code>
+ </td>
+ <td>
+ "<code>make user</code>"
+ <p>
+ This is the flavor intended to be the final release bits.
+ <ul>
+ <li>Installs modules tagged with <code>user</code>.
+ <li>Installs non-APK modules that have no tags specified.
+ <li>Installs APKs according to the product definition files; tags
+ are ignored for APK modules.
+ <li><code>ro.secure=1</code>
+ <li><code>ro.debuggable=0</code>
+ <li><code>adb</code> is disabled by default.
+ </td>
+</tr>
+<tr>
+ <td>
+ <code>userdebug<code>
+ </td>
+ <td>
+ "<code>make userdebug</code>"
+ <p>
+ The same as <code>user</code>, except:
+ <ul>
+ <li>Also installs modules tagged with <code>debug</code>.
+ <li><code>ro.debuggable=1</code>
+ <li><code>adb</code> is enabled by default.
+ </td>
+</tr>
+</table>
+
+<p>
+If you build one flavor and then want to build another, you should run
+"<code>make installclean</code>" between the two makes to guarantee that
+you don't pick up files installed by the previous flavor. "<code>make
+clean</code>" will also suffice, but it takes a lot longer.
+</p>
+
+
+<h3>More pseudotargets</h3>
+<p>Sometimes you want to just build one thing. The following pseudotargets are
+there for your convenience:</p>
+
+<ul>
+<li><b>droid</b> - <code>make droid</code> is the normal build. This target
+is here because the default target has to have a name.</li>
+<li><b>all</b> - <code>make all</code> builds everything <code>make
+droid</code> does, plus everything whose <code>LOCAL_MODULE_TAGS</code> do not
+include the "droid" tag. The build server runs this to make sure
+that everything that is in the tree and has an Android.mk builds.</li>
+<li><b>clean-$(LOCAL_MODULE)</b> and <b>clean-$(LOCAL_PACKAGE_NAME)</b> -
+Let you selectively clean one target. For example, you can type
+<code>make clean-libutils</code> and it will delete libutils.so and all of the
+intermediate files, or you can type <code>make clean-Home</code> and it will
+clean just the Home app.</li>
+<li><b>clean</b> - <code>make clean</code> deletes all of the output and
+intermediate files for this configuration. This is the same as <code>rm -rf
+out/<configuration>/</code></li>
+<li><b>clobber</b> - <code>make clobber</code> deletes all of the output
+and intermediate files for all configurations. This is the same as
+<code>rm -rf out/</code>.</li>
+<li><b>dataclean</b> - <code>make dataclean</code> deletes contents of the data
+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
+out/linux-x86-debug/system/bin/runtime</code> (which would work), and
+<code>make libkjs</code> might be shorthand for <code>make
+out/linux-x86-debug/system/lib/libkjs.so</code> (which would also work).</li>
+<li><b>targets</b> - <code>make targets</code> will print a list of all of
+the LOCAL_MODULE names you can make.</li>
+</ul>
+
+<h3><a name="templates"/>How to add another component to the build - Android.mk templates</h3>
+<p>You have a new library, a new app, or a new executable. For each of the
+common types of modules, there is a corresponding file in the templates
+directory. It will usually be enough to copy one of these, and fill in your
+own values. Some of the more esoteric values are not included in the
+templates, but are instead just documented here, as is the documentation
+on using custom tools to generate files.</p>
+<p>Mostly, you can just look for the TODO comments in the templates and do
+what it says. Please remember to delete the TODO comments when you're done
+to keep the files clean. The templates have minimal documentation in them,
+because they're going to be copied, and when that gets stale, the copies just
+won't get updated. So read on...</p>
+
+<h4>Apps</h4>
+<p>Use the <code>templates/apps</code> file.</p>
+<p>This template is pretty self-explanitory. See the variables below for more
+details.</p>
+
+<h4>Java Libraries</h4>
+<p>Use the <code>templates/java_library</code> file.</p>
+<p>The interesting thing here is the value of LOCAL_MODULE, which becomes
+the name of the jar file. (Actually right now, we're not making jar files yet,
+just directories of .class files, but the directory is named according to
+what you put in LOCAL_MODULE). This name will be what goes in the
+LOCAL_JAVA_LIBRARIES variable in modules that depend on your java library.</p>
+
+<h4>C/C++ Executables</h4>
+<p>Use the <code>templates/executable</code> file, or the
+<code>templates/executable_host</code> file.</p>
+<p>This template has a couple extra options that you usually don't need.
+Please delete the ones you don't need, and remove the TODO comments. It makes
+the rest of them easier to read, and you can always refer back to the templates
+if you need them again later.</p>
+<p>By default, on the target these are built into /system/bin, and on the
+host, they're built into <combo>/host/bin. These can be overridden by setting
+<code>LOCAL_MODULE_PATH</code>. See
+<a href="#moving-targets">Putting targets elsewhere</a>
+for more.</p>
+
+<h4>Shared Libraries</h4>
+<p>Use the <code>templates/shared_library</code> file, or the
+<code>templates/shared_library_host</code> file.</p>
+<p>Remember that on the target, we use shared libraries, and on the host,
+we use static libraries, since executable size isn't as big an issue, and it
+simplifies distribution in the SDK.</p>
+
+<h4>Static Libraries</h4>
+<p>Use the <code>templates/static_library</code> file, or the
+<code>templates/static_library_host</code> file.</p>
+<p>Remember that on the target, we use shared libraries, and on the host,
+we use static libraries, since executable size isn't as big an issue, and it
+simplifies distribution in the SDK.</p>
+
+<h4><a name="custom-tools"/>Using Custom Tools</h4>
+<p>If you have a tool that generates source files for you, it's possible
+to have the build system get the dependencies correct for it. Here are
+a couple of examples. <code>$@</code> is the make built-in variable for
+"the current target." The <font color=red>red</font> parts are the parts you'll
+need to change.</p>
+
+<p>You need to put this after you have declared <code>LOCAL_PATH</code> and
+<code>LOCAL_MODULE</code>, because the <code>$(local-intermediates-dir)</code>
+and <code>$(local-host-intermediates-dir)</code> macros use these variables
+to determine where to put the files.
+
+<h5>Example 1</h5>
+<p>Here, there is one generated file, called
+chartables.c, which doesn't depend on anything. And is built by the tool
+built to $(HOST_OUT_EXECUTABLES)/dftables. Note on the second to last line
+that a dependency is created on the tool.</p>
+<pre>
+intermediates:= $(local-intermediates-dir)
+GEN := $(intermediates)/<font color=red>chartables.c</font>
+$(GEN): PRIVATE_CUSTOM_TOOL = <font color=red>$(HOST_OUT_EXECUTABLES)/dftables $@</font>
+$(GEN): <font color=red>$(HOST_OUT_EXECUTABLES)/dftables</font>
+ $(transform-generated-source)
+LOCAL_GENERATED_SOURCES += $(GEN)
+</pre>
+
+<h5>Example 2</h5>
+<p>Here as a hypothetical example, we use use cat as if it were to transform
+a file. Pretend that it does something useful. Note how we use a
+target-specific variable called PRIVATE_INPUT_FILE to store the name of the
+input file.</p>
+<pre>
+intermediates:= $(local-intermediates-dir)
+GEN := $(intermediates)/<font color=red>file.c</font>
+$(GEN): PRIVATE_INPUT_FILE := $(LOCAL_PATH)/<font color=red>input.file</font>
+$(GEN): PRIVATE_CUSTOM_TOOL = <font color=red>cat $(PRIVATE_INPUT_FILE) > $@</font>
+$(GEN): <font color=red>$(LOCAL_PATH)/file.c</font>
+ $(transform-generated-source)
+LOCAL_GENERATED_SOURCES += $(GEN)
+</pre>
+
+<h5>Example 3</h5>
+<p>If you have several files that are all similar in
+name, and use the same tool, you can combine them. (here the *.lut.h files are
+the generated ones, and the *.cpp files are the input files)</p>
+<pre>
+intermediates:= $(local-intermediates-dir)
+GEN := $(addprefix $(intermediates)<font color=red>/kjs/, \
+ array_object.lut.h \
+ bool_object.lut.h \</font>
+ )
+$(GEN): PRIVATE_CUSTOM_TOOL = <font color=red>perl libs/WebKitLib/WebKit/JavaScriptCore/kjs/create_hash_table $< -i > $@</font>
+$(GEN): $(intermediates)/<font color=red>%.lut.h</font> : $(LOCAL_PATH)/<font color=red>%.cpp</font>
+ $(transform-generated-source)
+LOCAL_GENERATED_SOURCES += $(GEN)
+</pre>
+
+<h3><a name="platform-specific"/>Platform specific conditionals</h3>
+<p>Sometimes you need to set flags specifically for different platforms. Here
+is a list of which values the different build-system defined variables will be
+set to and some examples.</p>
+<p>For a device build, <code>TARGET_OS</code> is <code>linux</code> (we're using
+linux!), and <code>TARGET_ARCH</code> is <code>arm</code>.</p>
+<p>For a simulator build, <code>TARGET_OS</code> and <code>TARGET_ARCH</code>
+are set to the same as <code>HOST_OS</code> and <code>HOST_ARCH</code> are
+on your platform. <code>TARGET_PRODUCT</code> is the name of the target
+hardware/product you are building for. The value <code>sim</code> is used
+for the simulator. We haven't thought through the full extent of customization
+that will happen here, but likely there will be additional UI configurations
+specified here as well.</p>
+<table cellspacing=25>
+<tr>
+ <td valign=top align=center>
+ <b>HOST_OS</b><br/>
+ linux<br/>
+ darwin<br/>
+ (cygwin)
+ </td>
+ <td valign=top align=center>
+ <b>HOST_ARCH</b><br/>
+ x86
+ </td>
+ <td valign=top align=center>
+ <b>HOST_BUILD_TYPE</b><br/>
+ release<br/>
+ debug
+ </td>
+</tr>
+<tr>
+ <td valign=top align=center>
+ <b>TARGET_OS</b><br/>
+ linux<br/>
+ darwin<br/>
+ (cygwin)
+ </td>
+ <td valign=top align=center>
+ <b>TARGET_ARCH</b><br/>
+ arm<br/>
+ x86
+ </td>
+ <td valign=top align=center>
+ <b>TARGET_BUILD_TYPE</b><br/>
+ release<br/>
+ debug
+ </td>
+ <td valign=top align=center>
+ <b>TARGET_PRODUCT</b><br/>
+ sim<br/>
+ dream<br/>
+ sooner
+ </td>
+</tr>
+</table>
+
+<h4>TARGET_SIMULATOR</h4>
+<p>If we're building the simulator, as opposed to the arm or emulator builds,
+<code>TARGET_SIMULATOR</code> will be set to <code>true</code>.
+
+<h4>Some Examples</h4>
+<pre>ifeq ($(TARGET_SIMULATOR),true)
+LOCAL_CFLAGS += -DSIMULATOR
+endif
+
+ifeq ($(TARGET_BUILD_TYPE),release)
+LOCAL_CFLAGS += -DNDEBUG=1
+endif
+
+# from libutils
+ifeq ($(TARGET_OS),linux)
+# Use the futex based mutex and condition variable
+# implementation from android-arm because it's shared mem safe
+LOCAL_SRC_FILES += futex_synchro.c
+LOCAL_LDLIBS += -lrt -ldl
+endif
+
+</pre>
+
+
+<h3><a name="moving-modules"/>Putting modules elsewhere</h3>
+<p>If you have modules that normally go somewhere, and you need to have them
+build somewhere else, read this. One use of this is putting files on
+the root filesystem instead of where they normally go in /system. Add these
+lines to your Android.mk:</p>
+<pre>
+LOCAL_MODULE_PATH := $(TARGET_ROOT_OUT_SBIN)
+LOCAL_UNSTRIPPED_PATH := $(TARGET_ROOT_OUT_SBIN_UNSTRIPPED)
+</pre>
+<p>For executables and libraries, you need to also specify a
+<code>LOCAL_UNSTRIPPED_PATH</code> location, because on target builds, we keep
+the unstripped executables so GDB can find the symbols.</code>
+<p>Look in <code>config/envsetup.make</code> for all of the variables defining
+places to build things.</p>
+<p>FYI: If you're installing an executable to /sbin, you probably also want to
+set <code>LOCAL_FORCE_STATIC_EXCUTABLE := true</code> in your Android.mk, which
+will force the linker to only accept static libraries.</p>
+
+
+<h3>Android.mk variables</h3>
+<p>These are the variables that you'll commonly see in Android.mk files, listed
+alphabetically.</p>
+<p>But first, a note on variable naming:
+<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. Please note that there
+ are a couple of these laying around the tree that aren't prefixed with
+ PRIVATE_. It is safe, and they will be fixed as they are discovered.
+ Sorry for the confusion.</li>
+ <li><b>INTERNAL_</b> - These variables are critical to functioning of
+ the build system, so you shouldn't create variables named like this, and
+ you probably shouldn't be messing with these variables in your makefiles.
+ </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>
+</p>
+
+<h4>LOCAL_ASSET_FILES</h4>
+<p>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></p>
+<p>This will probably change when we switch to ant for the apps' build
+system.</p>
+
+<h4>LOCAL_CC</h4>
+<p>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.</p>
+
+<h4>LOCAL_CXX</h4>
+<p>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.</p>
+
+<h4>LOCAL_CFLAGS</h4>
+<p>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></p>
+
+<h4>LOCAL_CPPFLAGS</h4>
+<p>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>.
+
+<h4>LOCAL_CPP_EXTENSION</h4>
+<p>If your C++ files end in something other than "<code>.cpp</code>",
+you can specify the custom extension here. For example:</p>
+<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.
+
+<h4>LOCAL_NO_DEFAULT_COMPILER_FLAGS</h4>
+<p>Normally, the compile line for C and C++ files includes global include
+paths and global cflags. If <code>LOCAL_NO_DEFAULT_COMPILER_FLAGS</code>
+is non-empty, none of the default includes or flags will be used when compiling
+C and C++ files in this module.
+<code>LOCAL_C_INCLUDES</code>, <code>LOCAL_CFLAGS</code>, and
+<code>LOCAL_CPPFLAGS</code> will still be used in this case, as will
+any <code>DEBUG_CFLAGS</code> that are defined for the module.
+
+<h4>LOCAL_COPY_HEADERS</h4>
+<p class=warning>This will be going away.</p>
+<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>
+
+<h4>LOCAL_COPY_HEADERS_TO</h4>
+<p class=warning>This will be going away.</p>
+<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>
+
+<h4>LOCAL_C_INCLUDES</h4>
+<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>
+<p>There are some components that are doing this wrong, and should be cleaned
+up.</p>
+
+<h4>LOCAL_MODULE_TAGS</h4>
+<p>Set <code>LOCAL_MODULE_TAGS</code> to any number of whitespace-separated
+tags. If the tag list is empty or contains <code>droid</code>, the module
+will get installed as part of a <code>make droid</code>. Otherwise, it will
+only get installed by running <code>make <your-module></code>
+or with the <code>make all</code> pseudotarget.</p>
+
+<h4>LOCAL_REQUIRED_MODULES</h4>
+<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.
+
+<h4>LOCAL_FORCE_STATIC_EXECUTABLE</h4>
+<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>
+
+<h4>LOCAL_GENERATED_SOURCES</h4>
+<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>
+
+<h4>LOCAL_JAVA_LIBRARIES</h4>
+<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>
+
+<h4>LOCAL_LDFLAGS</h4>
+<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>
+
+<h4>LOCAL_LDLIBS</h4>
+<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>
+
+<h4>LOCAL_NO_MANIFEST</h4>
+<p>If your package doesn't have a manifest (AndroidManifest.xml), then
+set <code>LOCAL_NO_MANIFEST:=true</code>. The common resources package
+does this.</p>
+
+<h4>LOCAL_PACKAGE_NAME</h4>
+<p><code>LOCAL_PACKAGE_NAME</code> is the name of an app. For example,
+Dialer, Contacts, etc. This will probably change or go away when we switch
+to an ant-based build system for the apps.</p>
+
+<h4>LOCAL_PATH</h4>
+<p>The directory your Android.mk file is in. You can set it by putting the
+following as the first line in your Android.mk:</p>
+<p><code>LOCAL_PATH := $(my-dir)</code></p>
+<p>The <code>my-dir</code> macro uses the
+<code><a href="http://www.gnu.org/software/make/manual/make.html#MAKEFILE_005fLIST-Variable">MAKEFILE_LIST</a></code>
+variable, so you must call it before you include any other makefiles. Also,
+consider that any subdirectories you inlcude might reset LOCAL_PATH, so do your
+own stuff before you include them. This also means that if you try to write
+several <code>include</code> lines that reference <code>LOCAL_PATH</code>,
+it won't work, because those included makefiles might reset LOCAL_PATH.
+
+<h4>LOCAL_POST_PROCESS_COMMAND</h4>
+<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>
+
+<h4>LOCAL_PREBUILT_EXECUTABLES</h4>
+<p>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.</p>
+
+<h4>LOCAL_PREBUILT_LIBS</h4>
+<p>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.</p>
+
+<h4>LOCAL_SHARED_LIBRARIES</h4>
+<p>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></p>
+
+<h4>LOCAL_SRC_FILES</h4>
+<p>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></p>
+
+<h4>LOCAL_STATIC_LIBRARIES</h4>
+<p>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></p>
+
+<h4>LOCAL_MODULE</h4>
+<p><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>. We're planning on switching to ant for the apps,
+so this might become moot.</p>
+
+<h4>LOCAL_MODULE_PATH</h4>
+<p>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.</p>
+
+<h4>LOCAL_UNSTRIPPED_PATH</h4>
+<p>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.</p>
+
+<h4>LOCAL_WHOLE_STATIC_LIBRARIES</h4>
+<p>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></p>
+
+<h4>LOCAL_YACCFLAGS</h4>
+<p>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></p>
+
+
+
+<h2>Implementation Details</h2>
+
+<p>You should never have to touch anything in the config directory unless
+you're adding a new platform, new tools, or adding new features to the
+build system. In general, please consult with the build system owner(s)
+(<a href="mailto:android-build-team">android-build-team</a>) before you go
+mucking around in here. That said, here are some notes on what's going on
+under the hood.</p>
+
+<h3>Environment Setup / buildspec.mk Versioning</h3>
+<p>In order to make easier for people when the build system changes, when
+it is necessary to make changes to buildspec.mk or to rerun the environment
+setup scripts, they contain a version number in the variable
+BUILD_ENV_SEQUENCE_NUMBER. If this variable does not match what the build
+system expects, it fails printing an error message explaining what happened.
+If you make a change that requires an update, you need to update two places
+so this message will be printed.
+<ul>
+ <li>In config/envsetup.make, increment the
+ CORRECT_BUILD_ENV_SEQUENCE_NUMBER definition.</li>
+ <li>In buildspec.mk.default, update the BUILD_ENV_SEQUENCE_DUMBER
+ definition to match the one in config/envsetup.make</li>
+</ul>
+The scripts automatically get the value from the build system, so they will
+trigger the warning as well.
+</p>
+
+<h3>Additional makefile variables</h3>
+<p>You probably shouldn't use these variables. Please consult
+<a href="mailto:android-build-team">android-build-team</a> before using them.
+These are mostly there for workarounds for other issues, or things that aren't
+completely done right.</p>
+
+<h4>LOCAL_ADDITIONAL_DEPENDENCIES</h4>
+<p>If your module needs to depend on anything else that
+isn't actually built in to it, you can add those make targets to
+<code>LOCAL_ADDITIONAL_DEPENDENCIES</code>. Usually this is a workaround
+for some other dependency that isn't created automatically.</p>
+
+<h4>LOCAL_BUILT_MODULE</h4>
+<p>When a module is built, the module is created in an intermediate
+directory then copied to its final location. LOCAL_BUILT_MODULE is
+the full path to the intermediate file. See LOCAL_INSTALLED_MODULE
+for the path to the final installed location of the module.</p>
+
+<h4>LOCAL_HOST</h4>
+<p>Set by the host_xxx.make includes to tell base_rules.make and the other
+includes that we're building for the host. Kenneth did this as part of
+openbinder, and I would like to clean it up so the rules, includes and
+definitions aren't duplicated for host and target.</p>
+
+<h4>LOCAL_INSTALLED_MODULE</h4>
+<p>The fully qualified path name of the final location of the module.
+See LOCAL_BUILT_MODULE for the location of the intermediate file that
+the make rules should actually be constructing.</p>
+
+<h4>LOCAL_REPLACE_VARS</h4>
+<p>Used in some stuff remaining from the openbinder for building scripts
+with particular values set,</p>
+
+<h4>LOCAL_SCRIPTS</h4>
+<p>Used in some stuff remaining from the openbinder build system that we
+might find handy some day.</p>
+
+<h4>LOCAL_MODULE_CLASS</h4>
+<p>Which kind of module this is. This variable is used to construct other
+variable names used to locate the modules. See base_rules.make and
+envsetup.make.</p>
+
+<h4>LOCAL_MODULE_NAME</h4>
+<p>Set to the leaf name of the LOCAL_BUILT_MODULE. I'm not sure,
+but it looks like it's just used in the WHO_AM_I variable to identify
+in the pretty printing what's being built.</p>
+
+<h4>LOCAL_MODULE_SUFFIX</h4>
+<p>The suffix that will be appended to <code>LOCAL_MODULE</code> to form
+<code>LOCAL_MODULE_NAME</code>. For example, .so, .a, .dylib.</p>
+
+<h4>LOCAL_STRIP_MODULE</h4>
+<p>Calculated in base_rules.make to determine if this module should actually
+be stripped or not, based on whether <code>LOCAL_STRIPPABLE_MODULE</code>
+is set, and whether the combo is configured to ever strip modules. With
+Iliyan's stripping tool, this might change.</p>
+
+<h4>LOCAL_STRIPPABLE_MODULE</h4>
+<p>Set by the include makefiles if that type of module is strippable.
+Executables and shared libraries are.</p>
+
+<h4>LOCAL_SYSTEM_SHARED_LIBRARIES</h4>
+<p>Used while building the base libraries: libc, libm, libdl. Usually
+it should be set to "none," as it is in $(CLEAR_VARS). When building
+these libraries, it's set to the ones they link against. For example,
+libc, libstdc++ and libdl don't link against anything, and libm links against
+libc. Normally, when the value is none, these libraries are automatically
+linked in to executables and libraries, so you don't need to specify them
+manually.</p>
+
+
+</body>
+</html>
OSDN Git Service
