Lines Matching +full:- +full:p
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <!--
9 - keep the document xhtml-compliant, as many people use validating editors
10 - check your edits for typos, spelling errors, and questionable grammar
11 - prefer css styles to formatting tags like <font>, <tt>, etc.
12 - keep it human-readable and human-editable in a plain text editor:
13 - strive to keep lines wrapped at 80 columns, unless a link prevents it
14 - use plenty of whitespace
15 - try to pretty-format (wrt nesting and indenting) any hairy html
16 - check your inline javascript for errors using the javascript console
19 -->
24 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
28 <!-- commenting out so the xhtml validator doesn't whine about < and &&;
29 the browser should still find the script tag. -->
31 <!--
50 //-->
52 <!-- this style sheet is for the style of the toc -->
62 margin-top: 0;
65 margin-top: 8px;
74 <!-- Status is one of: Draft, Current, Needs Update, Obsolete -->
75 <p style="text-align:center">
78 </p>
80 <p><b>Contents</b></p>
81 <!-- this div expands out to a list of contents based on the H2 and H3 headings.
82 Believe it! -->
83 <div id="nav" class="nav-2-levels"></div>
86 <p>The primary goals of reworking the build system are (1) to make dependencies
89 rebuilt, and so doing a top-level build when little or nothing needs to be done
90 for a build takes as little time as possible.</p>
93 <p>Given the above objective, these are the overall principles and use cases
94 that we will support. This is not an exhaustive list.</p>
96 <p>It needs to be possible to build the Android platform for multiple targets.
97 This means:</p>
106 the short-term, MacOS. Note that this is a conscious decision to stop
111 <h3>Non-Recursive Make</h3>
112 <p>To achieve the objectives, the build system will be rewritten to use make
113 non-recursively. For more background on this, read <a href="http://aegis.sourceforge.net/auug97.pd…
116 <h3>Rapid Compile-Test Cycles</h3>
117 <p>When developing a component, for example a C++ shared library, it must be
120 components to be built.</p>
122 <p>To set the target, and other options, some people on the team like to have a
126 in one terminal. We will support both.</p>
128 <p>Object files and other intermediate files will be generated into a directory
130 "rm -rf <obj>" in the tree root directory. The primary goals of
132 reliable.</p>
135 <p>The SDK will be a tarball that will allow non-OS-developers to write apps.
139 standard java-app development tools, and (2) allow us to dog-food the SDK, to
142 figure out exactly how this will work.</p>
145 <p>Dependencies should all be automatic. Unless there is a custom tool involved
148 in the Android.mk file.</p>
151 <p>Wildcarding source file will be discouraged. It may be useful in some
153 current directory being set to the root of the build tree.<p>
156 <p>It will be possible to generate more than one target from a given
158 and a static library for the host.</p>
161 <p><b>Android.mk</b> is the standard name for the makefile fragments that
163 have a file named "Makefile".</p>
166 <p>Currently, the simulator is not built to use shared libraries. This should
168 libraries to work on Mac OS.</p>
173 <p>These things would be nice to have, and this is a good place to record them,
174 however these are not promises.</p>
177 <p>The hope is to be able to do two builds for different combos in the same
180 it's looking like we'll get the two builds at the same time working)</p>
183 <p>Problems can arise if you delete a header file that is referenced in
185 should be a better way to handle it. (from fadden)</p>
186 <p>One way of solving this is introducing a dependency on the directory. The
188 It's a tradeoff.</p>
191 <p>General way to perform builds across the set of known platforms. This
193 change, and allow a wide-scale "make clean". Right now the buildspec.mk
194 or environment variables need to be updated before each build. (from fadden)</p>
197 <p>We will eventually need to add support for creating locales and carrier
198 customizations to the SDK, but that will not be addressed right now.</p>
202 <p>You've read (or scrolled past) all of the motivations for this build system,
203 and you want to know how to use it. This is the place.</p>
206 <p>The <a href="../building.html">Building</a> document describes how do do
207 builds.</p>
214 <li><b>printconfig</b> - Prints the current configuration as set by the
216 <li><b>m</b> - Runs <code>make</code> from the top of the tree. This is
220 <li><b>croot</b> - <code>cd</code> to the top of the tree.</li>
221 <li><b>sgrep</b> - grep for the regex you provide in all .c, .cpp, .h, .java,
226 <p>
229 currently-defined "flavors" or "types" (we need to settle on a real name
231 </p>
245 <li>Installs non-APK modules that have no tags specified.
260 <p>
264 <li>Installs non-APK modules that have no tags specified.
279 <p>
289 <p>
294 </p>
298 <p>Sometimes you want to just build one thing. The following pseudotargets are
299 there for your convenience:</p>
302 <li><b>droid</b> - <code>make droid</code> is the normal build. This target
304 <li><b>all</b> - <code>make all</code> builds everything <code>make
308 <li><b>clean-$(LOCAL_MODULE)</b> and <b>clean-$(LOCAL_PACKAGE_NAME)</b> -
310 <code>make clean-libutils</code> and it will delete libutils.so and all of the
311 intermediate files, or you can type <code>make clean-Home</code> and it will
313 <li><b>clean</b> - <code>make clean</code> deletes all of the output and
314 intermediate files for this configuration. This is the same as <code>rm -rf
316 <li><b>clobber</b> - <code>make clobber</code> deletes all of the output
318 <code>rm -rf out/</code>.</li>
319 <li><b>dataclean</b> - <code>make dataclean</code> deletes contents of the data
323 <li><b>LOCAL_MODULE</b> - Anything you specify as a <code>LOCAL_MODULE</code>
326 out/linux-x86-debug/system/bin/runtime</code> (which would work), and
328 out/linux-x86-debug/system/lib/libkjs.so</code> (which would also work).</li>
329 <li><b>targets</b> - <code>make targets</code> will print a list of all of
333 <h3><a name="templates"/>How to add another component to the build - Android.mk templates</h3>
334 <p>You have a new library, a new app, or a new executable. For each of the
339 on using custom tools to generate files.</p>
340 <p>Mostly, you can just look for the TODO comments in the templates and do
344 won't get updated. So read on...</p>
347 <p>Use the <code>templates/apps</code> file.</p>
348 <p>This template is pretty self-explanitory. See the variables below for more
349 details.</p>
352 <p>Use the <code>templates/java_library</code> file.</p>
353 <p>The interesting thing here is the value of LOCAL_MODULE, which becomes
357 LOCAL_JAVA_LIBRARIES variable in modules that depend on your java library.</p>
360 <p>Use the <code>templates/executable</code> file, or the
361 <code>templates/executable_host</code> file.</p>
362 <p>This template has a couple extra options that you usually don't need.
365 if you need them again later.</p>
366 <p>By default, on the target these are built into /system/bin, and on the
369 <a href="#moving-targets">Putting targets elsewhere</a>
370 for more.</p>
373 <p>Use the <code>templates/shared_library</code> file, or the
374 <code>templates/shared_library_host</code> file.</p>
375 <p>Remember that on the target, we use shared libraries, and on the host,
377 simplifies distribution in the SDK.</p>
380 <p>Use the <code>templates/static_library</code> file, or the
381 <code>templates/static_library_host</code> file.</p>
382 <p>Remember that on the target, we use shared libraries, and on the host,
384 simplifies distribution in the SDK.</p>
386 <h4><a name="custom-tools"/>Using Custom Tools</h4>
387 <p>If you have a tool that generates source files for you, it's possible
389 a couple of examples. <code>$@</code> is the make built-in variable for
391 need to change.</p>
393 <p>You need to put this after you have declared <code>LOCAL_PATH</code> and
394 <code>LOCAL_MODULE</code>, because the <code>$(local-generated-sources-dir)</code>
395 and <code>$(local-host-generated-sources-dir)</code> macros use these variables
399 <p>Here, there is one generated file, called
402 that a dependency is created on the tool.</p>
404 intermediates:= $(local-generated-sources-dir)
408 $(transform-generated-source)
413 <p>Here as a hypothetical example, we use use cat as if it were to transform
415 target-specific variable called PRIVATE_INPUT_FILE to store the name of the
416 input file.</p>
418 intermediates:= $(local-generated-sources-dir)
423 $(transform-generated-source)
428 <p>If you have several files that are all similar in
430 the generated ones, and the *.cpp files are the input files)</p>
432 intermediates:= $(local-generated-sources-dir)
437 …= <font color=red>perl libs/WebKitLib/WebKit/JavaScriptCore/kjs/create_hash_table $< -i > $@</font>
439 $(transform-generated-source)
443 <h3><a name="unbundled-build"/>Unbundled build</h3>
444 <p>Unbundled build has several meanings by the context.
445 Let me explain the meaning by the flags related to "unbundled build"</p>
447 <p>The source tree might not have the full platform sources. It is always set if
448 <code>TARGET_BUILD_APPS</code> or <code>TARGET_BUILD_UNBUNDLED_IMAGE</code> is set.</p>
450 <p>It is an internal flag. If it is set, prebuilt SDKs are used, even if a module's
453 and use them as usual.</p>
455 <p>It is an internal flag as well. If it is set, dexpreopt is disabled.
457 because dexpreopt tightly depends on the platform.</p>
459 <p>Build the apps that can be distributed outside the platform, so it turns on
462 <code>UNBUNDLED_BUILD_SDKS_FROM_SOURCE</code> is set.</p>
464 <p>It is similar to <code>TARGET_BUILD_APPS</code>, but its target is an unbundled partition
468 <code>UNBUNDLED_BUILD_SDKS_FROM_SOURCE</code> is set.</p>
470 <h3><a name="platform-specific"/>Platform specific conditionals</h3>
471 <p>Sometimes you need to set flags specifically for different platforms. Here
472 is a list of which values the different build-system defined variables will be
473 set to and some examples.</p>
508 <p>There are also special variables to use instead of conditionals. Many of the
510 to with _{arch} _{32|64}, and for the host, _{os}.</p>
514 LOCAL_CFLAGS += -DNDEBUG=1
517 LOCAL_CFLAGS_arm += -DTARGET_IS_ARM
519 LOCAL_CFLAGS_64 += -DBIG_POINTER
523 # implementation from android-arm because it's shared mem safe
525 LOCAL_LDLIBS_linux += -lrt -ldl
530 <h3><a name="moving-modules"/>Putting modules elsewhere</h3>
531 <p>If you have modules that normally go somewhere, and you need to have them
532 build somewhere else, read this.</p>
533 <p>If you have modules that need to go in a subdirectory of their normal
536 example:</p>
540 <p>If you have modules that need to go in an entirely different location, for
542 Android.mk:</p>
547 <p>For executables and libraries, you need to specify a
552 <code>LOCAL_MODULE_RELATIVE_PATH</code>.</p>
553 <p>Look in <code>core/envsetup.mk</code> for all of the variables defining
554 places to build things.</p>
558 <p>These are the variables that you'll commonly see in Android.mk files, listed
559 alphabetically.</p>
560 <p>But first, a note on variable naming:
562 <li><b>LOCAL_</b> - These variables are set per-module. They are cleared
566 <li><b>PRIVATE_</b> - These variables are make-target-specific variables. That
571 describes more about target-specific variables. Please note that there
575 <li><b>INTERNAL_</b> - These variables are critical to functioning of
579 <li><b>HOST_</b> and <b>TARGET_</b> - These contain the directories
583 <li><b>HOST_CROSS_</b> - These contain the directories and definitions that
584 are specific to cross-building host binaries. The common case is building
588 <li><b>BUILD_</b> and <b>CLEAR_VARS</b> - These contain the names of
589 well-defined template makefiles to include. Some examples are CLEAR_VARS
591 <li>Any other name is fair-game for you to use in your Android.mk. However,
592 remember that this is a non-recursive build system, so it is possible that
596 </p>
599 <p>Set this to a list of modules built with <code>BUILD_HOST_JAVA_LIBRARY</code>
600 to have their jars passed to javac with -processorpath for use as annotation
601 processors.</p>
604 <p>Set this to a list of classes to be passed to javac as -processor arguments.
607 does not autodetect them and requires listing them manually.</p>
610 <p>In Android.mk files that <code>include $(BUILD_PACKAGE)</code> set this
611 to the set of files you want built into your app. Usually:</p>
612 <p><code>LOCAL_ASSET_FILES += $(call find-subdir-assets)</code></p>
613 <p>This will probably change when we switch to ant for the apps' build
614 system.</p>
617 <p>If you want to use a different C compiler for this module, set LOCAL_CC
619 compiler is used.</p>
622 <p>If you want to use a different C++ compiler for this module, set LOCAL_CXX
624 compiler is used.</p>
627 <p>If you have additional flags to pass into the C or C++ compiler, add
628 them here. For example:</p>
629 <p><code>LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1</code></p>
632 <p>If you have additional flags to pass into <i>only</i> the C++ compiler, add
633 them here. For example:</p>
634 <p><code>LOCAL_CPPFLAGS += -ffriend-injection</code></p>
640 <p>If your C++ files end in something other than "<code>.cpp</code>",
641 you can specify the custom extension here. For example:</p>
642 <p><code>LOCAL_CPP_EXTENSION := .cc</code></p>
647 <p>Normally, the compile line for C and C++ files includes global include
649 is non-empty, none of the default includes or flags will be used when compiling
656 <p class=warning>This will be going away.</p>
657 <p>The set of files to copy to the install include tree. You must also
658 supply <code>LOCAL_COPY_HEADERS_TO</code>.</p>
659 <p>This is going away because copying headers messes up the error messages, and
663 headers.</p>
666 <p class=warning>This will be going away.</p>
667 <p>The directory within "include" to copy the headers listed in
668 <code>LOCAL_COPY_HEADERS</code> to.</p>
669 <p>This is going away because copying headers messes up the error messages, and
673 headers.</p>
676 <p>Additional directories to instruct the C/C++ compilers to look for header
679 want in the include paths. For example:</p>
680 <p><code>
681 LOCAL_C_INCLUDES += extlibs/zlib-1.2.3<br/>
683 </code></p>
684 <p>You should not add subdirectories of include to
687 example:</p>
688 <p><code>#include <utils/KeyedVector.h></code><br/>
689 not <code><s>#include <KeyedVector.h></s></code></p>
690 <p>There are some components that are doing this wrong, and should be cleaned
691 up.</p>
694 <p>Set <code>LOCAL_MODULE_TAGS</code> to any number of whitespace-separated
697 only get installed by running <code>make <your-module></code>
698 or with the <code>make all</code> pseudotarget.</p>
701 <p>Set <code>LOCAL_REQUIRED_MODULES</code> to any number of whitespace-separated
708 <p>If your executable should be linked statically, set
710 list of libraries that we have in static form (currently only libc).</p>
713 <p>Files that you add to <code>LOCAL_GENERATED_SOURCES</code> will be
715 See the <a href="#custom-tools">Custom Tools</a> template makefile for an
716 example.</p>
719 <p>If you have additional flags to pass into the javac compiler, add
720 them here. For example:</p>
721 <p><code>LOCAL_JAVACFLAGS += -Xlint:deprecation</code></p>
724 <p>If you have additional flags to pass into the error prone compiler, add
725 them here. For example:</p>
726 <p><code>LOCAL_ERROR_PRONE_FLAGS += -Xep:ClassCanBeStatic:ERROR</code></p>
729 <p>When linking Java apps and libraries, <code>LOCAL_JAVA_LIBRARIES</code>
732 In most cases, it will look like this:</p>
733 <p><code>LOCAL_JAVA_LIBRARIES := core framework</code></p>
734 <p>Note that setting <code>LOCAL_JAVA_LIBRARIES</code> is not necessary
737 will be included automatically.</p>
740 <p>You can pass additional flags to the linker by setting
742 very important to ld, so test whatever you do on all platforms.</p>
745 <p><code>LOCAL_LDLIBS</code> allows you to specify additional libraries
747 the libraries you want in -lxxx format; they're passed directly to the
752 doing something sneaky. Some examples:</p>
753 <p><code>LOCAL_LDLIBS += -lcurses -lpthread<br/>
754 LOCAL_LDLIBS += -Wl,-z,origin
755 </code></p>
758 <p>If your package doesn't have a manifest (AndroidManifest.xml), then
760 does this.</p>
763 <p><code>LOCAL_PACKAGE_NAME</code> is the name of an app. For example,
765 to an ant-based build system for the apps.</p>
768 <p>As of January 2018, you almost certainly don't need this option, so please
770 experimental and may go away in future.</p>
771 <p>
778 </p>
781 <p>The directory your Android.mk file is in. You can set it by putting the
782 following as the first line in your Android.mk:</p>
783 <p><code>LOCAL_PATH := $(my-dir)</code></p>
784 <p>The <code>my-dir</code> macro uses the
785 <code><a href="http://www.gnu.org/software/make/manual/make.html#MAKEFILE_005fLIST-Variable">MAKEFI…
793 <p>For host executables, you can specify a command to run on the module
795 to get variables right because of early or late variable evaluation:</p>
796 <p><code>module := $(HOST_OUT_EXECUTABLES)/$(LOCAL_MODULE)<br/>
797 LOCAL_POST_PROCESS_COMMAND := /Developer/Tools/Rez -d __DARWIN__ -t APPL\<br/>
798 -d __WXMAC__ -o $(module) Carbon.r
799 </code></p>
802 <p>When including $(BUILD_MULTI_PREBUILT) or $(BUILD_HOST_PREBUILT), set these
804 right bin directory.</p>
807 <p>When including $(BUILD_MULTI_PREBUILT) or $(BUILD_HOST_PREBUILT), set these
809 right lib directory.</p>
812 <p>These are the libraries you directly link against. You don't need to
813 pass transitively included libraries. Specify the name without the suffix:</p>
814 <p><code>LOCAL_SHARED_LIBRARIES := \<br/>
820 </code></p>
823 <p>The build system looks at <code>LOCAL_SRC_FILES</code> to know what source
824 files to compile -- .cpp .c .y .l .java. For lex and yacc files, it knows
827 them with the directory name:</p>
828 <p><code>LOCAL_SRC_FILES := \<br/>
831 </code></p>
834 <p>These are the static libraries that you want to include in your module.
837 <p><code>LOCAL_STATIC_LIBRARIES := \<br/>
840 </code></p>
843 <p><code>LOCAL_MODULE</code> is the name of what's supposed to be generated
845 is "libkjs" (the build system adds the appropriate suffix -- .so .dylib .dll).
848 so this might become moot.</p>
851 <p>Instructs the build system to put the module somewhere other than what's
855 to.</p>
856 <p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</p>
859 <p>Instructs the build system to put the module in a subdirectory under the
862 the relative path.</p>
863 <p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</p>
866 <p>This specifies which OSes are supported by this host module. It is not used
871 Some examples:</p>
872 <p><code>LOCAL_MODULE_HOST_OS := linux<br/>
873 LOCAL_MODULE_HOST_OS := darwin linux windows</code></p>
876 <p>Instructs the build system to put the unstripped version of the module
880 <code>LOCAL_UNSTRIPPED_PATH</code>, an error will occur.</p>
881 <p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</p>
884 <p>These are the static libraries that you want to include in your module without allowing
887 <p><code>LOCAL_WHOLE_STATIC_LIBRARIES := \<br/>
889 </code></p>
892 <p>Any flags to pass to invocations of yacc for your module. A known limitation
894 module. This can be fixed. If you ever need it to be, just ask.</p>
895 <p><code>LOCAL_YACCFLAGS := -p kjsyy</code></p>
901 <p>You should never have to touch anything in the config directory unless
904 (<a href="mailto:android-build-team">android-build-team</a>) before you go
906 under the hood.</p>
909 <p>In order to make easier for people when the build system changes, when
924 </p>
927 <p>You probably shouldn't use these variables. Please consult
928 <a href="mailto:android-build-team">android-build-team</a> before using them.
930 completely done right.</p>
933 <p>If your module needs to depend on anything else that
936 for some other dependency that isn't created automatically.</p>
939 <p class=warning>This should not be used, since multiple binaries are now
940 created from a single module defintiion.</p>
941 <p>When a module is built, the module is created in an intermediate
944 for the path to the final installed location of the module.</p>
947 <p>Set by the host_xxx.mk includes to tell base_rules.mk and the other
948 includes that we're building for the host.</p>
951 <p class=warning>This should not be used, since multiple binaries are now
952 created from a single module defintiion.</p>
953 <p>The fully qualified path name of the final location of the module.
955 the make rules should actually be constructing.</p>
958 <p>Which kind of module this is. This variable is used to construct other
960 envsetup.mk.</p>
963 <p>The suffix that will be appended to <code>LOCAL_MODULE</code> to form
964 <code>LOCAL_MODULE_NAME</code>. For example, .so, .a, .dylib.</p>
967 <p>If set to true (the default), the binary will be stripped and a debug
971 Any other value will prevent stripping.</p>
974 <p>Used while building the base libraries: libc, libm, libdl. Usually
980 manually.</p>