From c91e5f15bab34364e67b578bfa49ea5a46d1e604 Mon Sep 17 00:00:00 2001 From: Reena Lee Date: Tue, 2 Jun 2009 15:00:28 -0700 Subject: [PATCH] AI 149502: - Adding sensors to PDK TOC - Added initial table of Product Definition file parameters - Added initial table of Android.mk LOCAL_* parameters Automated import of CL 149502 --- pdk/docs/guide/build_cookbook.jd | 448 ++++++++++++++++++++++++++++++++++++- pdk/docs/guide/build_new_device.jd | 188 ++++++++++++++++ pdk/docs/guide/build_system.jd | 35 --- pdk/docs/guide/pdk_toc.cs | 1 + 4 files changed, 628 insertions(+), 44 deletions(-) diff --git a/pdk/docs/guide/build_cookbook.jd b/pdk/docs/guide/build_cookbook.jd index ad5f8b89..b9d9f7cf 100755 --- a/pdk/docs/guide/build_cookbook.jd +++ b/pdk/docs/guide/build_cookbook.jd @@ -10,7 +10,6 @@ pdk.version= Building a APK that should be signed with a specific vendor key
Adding a prebuilt APK
Adding a Static Java Library
- Using LOCAL_MODULE_TAGS

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.

@@ -107,12 +106,443 @@ pdk.version= # Build a static jar file. include $(BUILD_STATIC_JAVA_LIBRARY) -

Random other build tidbits

-

LOCAL_MODULE_TAGS

-

This variable controls what build flavors the package gets included in. For example:

-
    -
  • user - means include this in user/userdebug builds
    • -
  • eng - means include this in eng builds
    • -
  • tests - means the target is a testing target and makes it available for tests
    • -
  • optional - don't include this
    • +

    Android.mk Variables

    + +

    These are the variables that you'll commonly see in Android.mk files, listed +alphabetically. First, a note on the variable naming:

    + +
      +
    • LOCAL_ - These variables are set per-module. They are cleared + by the include $(CLEAR_VARS) 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.
      • +
    • PRIVATE_ - 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 + link to the make documentation + describes more about target-specific variables. +
      • +
    • HOST_ and TARGET_ - 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. +
      • +
    • BUILD_ and CLEAR_VARS - These contain the names of + well-defined template makefiles to include. Some examples are CLEAR_VARS + and BUILD_HOST_PACKAGE.
      • +
    • 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.
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterDescription
    LOCAL_AAPT_FLAGS
    LOCAL_ACP_UNAVAILABLE
    LOCAL_ADDITIONAL_JAVA_DIR
    LOCAL_AIDL_INCLUDES
    LOCAL_ALLOW_UNDEFINED_SYMBOLS
    LOCAL_ARM_MODE
    LOCAL_ASFLAGS
    LOCAL_ASSET_DIR
    LOCAL_ASSET_FILESIn Android.mk files that include $(BUILD_PACKAGE) set this +to the set of files you want built into your app. Usually:

    +

    LOCAL_ASSET_FILES += $(call find-subdir-assets)

    LOCAL_BUILT_MODULE_STEM
    LOCAL_C_INCLUDES

    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 +LOCAL_PATH if you have subdirectories of your own that you +want in the include paths. For example:

    +

    +LOCAL_C_INCLUDES += extlibs/zlib-1.2.3
    +LOCAL_C_INCLUDES += $(LOCAL_PATH)/src +

    +

    You should not add subdirectories of include to +LOCAL_C_INCLUDES, instead you should reference those files +in the #include statement with their subdirectories. For +example:

    +

    #include <utils/KeyedVector.h>
    +not #include <KeyedVector.h>

    LOCAL_CCIf 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.
    LOCAL_CERTIFICATE
    LOCAL_CFLAGSIf you have additional flags to pass into the C or C++ compiler, add +them here. For example:

    +

    LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1

    LOCAL_CLASSPATH
    LOCAL_COMPRESS_MODULE_SYMBOLS
    LOCAL_COPY_HEADERS

    The set of files to copy to the install include tree. You must also +supply LOCAL_COPY_HEADERS_TO.

    +

    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.

    LOCAL_COPY_HEADERS_TO

    The directory within "include" to copy the headers listed in +LOCAL_COPY_HEADERS to.

    +

    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.

    LOCAL_CPP_EXTENSIONIf your C++ files end in something other than ".cpp", +you can specify the custom extension here. For example: +

    LOCAL_CPP_EXTENSION := .cc

    +Note that all C++ files for a given module must have the same +extension; it is not currently possible to mix different extensions.
    LOCAL_CPPFLAGSIf you have additional flags to pass into only the C++ compiler, add +them here. For example:

    +

    LOCAL_CPPFLAGS += -ffriend-injection

    +LOCAL_CPPFLAGS is guaranteed to be after LOCAL_CFLAGS +on the compile line, so you can use it to override flags listed in +LOCAL_CFLAGS
    LOCAL_CXXIf 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.
    LOCAL_DX_FLAGS
    LOCAL_EXPORT_PACKAGE_RESOURCES
    LOCAL_FORCE_STATIC_EXECUTABLE

    If your executable should be linked statically, set +LOCAL_FORCE_STATIC_EXECUTABLE:=true. 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.

    LOCAL_GENERATED_SOURCES

    Files that you add to LOCAL_GENERATED_SOURCES will be +automatically generated and then linked in when your module is built. +See the Custom Tools template makefile for an +example.

    LOCAL_INSTRUMENTATION_FOR
    LOCAL_INSTRUMENTATION_FOR_PACKAGE_NAME
    LOCAL_INTERMEDIATE_SOURCES
    LOCAL_INTERMEDIATE_TARGETS
    LOCAL_IS_HOST_MODULE
    LOCAL_JAR_MANIFEST
    LOCAL_JARJAR_RULES
    LOCAL_JAVA_LIBRARIES

    When linking Java apps and libraries, LOCAL_JAVA_LIBRARIES +specifies which sets of java classes to include. Currently there are +two of these: core and framework. +In most cases, it will look like this:

    +

    LOCAL_JAVA_LIBRARIES := core framework

    +

    Note that setting LOCAL_JAVA_LIBRARIES is not necessary +(and is not allowed) when building an APK with +"include $(BUILD_PACKAGE)". The appropriate libraries +will be included automatically.

    LOCAL_JAVA_RESOURCE_DIRS
    LOCAL_JAVA_RESOURCE_FILES
    LOCAL_JNI_SHARED_LIBRARIES
    LOCAL_LDFLAGS

    You can pass additional flags to the linker by setting +LOCAL_LDFLAGS. Keep in mind that the order of parameters is +very important to ld, so test whatever you do on all platforms.

    LOCAL_LDLIBS

    LOCAL_LDLIBS 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:

    +

    LOCAL_LDLIBS += -lcurses -lpthread
    +LOCAL_LDLIBS += -Wl,-z,origin +

    LOCAL_MODULELOCAL_MODULE is the name of what's supposed to be generated +from your Android.mk. For exmample, for libkjs, the LOCAL_MODULE +is "libkjs" (the build system adds the appropriate suffix -- .so .dylib .dll). +For app modules, use LOCAL_PACKAGE_NAME instead of +LOCAL_MODULE.
    LOCAL_MODULE_PATHInstructs 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 +LOCAL_UNSTRIPPED_PATH 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.

    +

    See Putting modules elsewhere for more.

    LOCAL_MODULE_STEM
    LOCAL_MODULE_TAGS

    Set LOCAL_MODULE_TAGS to any number of whitespace-separated +tags.

    This variable controls what build flavors the package gets included in. For example:

    +
      +
    • user: include this in user/userdebug builds
      • +
    • eng: include this in eng builds
      • +
    • tests: the target is a testing target and makes it available for tests
      • +
    • optional: don't include this
      • +
    LOCAL_NO_DEFAULT_COMPILER_FLAGS
    LOCAL_NO_EMMA_COMPILE
    LOCAL_NO_EMMA_INSTRUMENT
    LOCAL_NO_STANDARD_LIBRARIES
    LOCAL_OVERRIDES_PACKAGES
    LOCAL_PACKAGE_NAMELOCAL_PACKAGE_NAME is the name of an app. For example, +Dialer, Contacts, etc.
    LOCAL_POST_PROCESS_COMMAND

    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:

    +

    module := $(HOST_OUT_EXECUTABLES)/$(LOCAL_MODULE)
    +LOCAL_POST_PROCESS_COMMAND := /Developer/Tools/Rez -d __DARWIN__ -t APPL\
    +       -d __WXMAC__ -o $(module) Carbon.r +

    +
    LOCAL_PREBUILT_EXECUTABLESWhen including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to +executables that you want copied. They're located automatically into the +right bin directory.
    LOCAL_PREBUILT_JAVA_LIBRARIES
    LOCAL_PREBUILT_LIBSWhen including $(BUILD_PREBUILT) or $(BUILD_HOST_PREBUILT), set these to +libraries that you want copied. They're located automatically into the +right lib directory.
    LOCAL_PREBUILT_OBJ_FILES
    LOCAL_PREBUILT_STATIC_JAVA_LIBRARIES
    LOCAL_PRELINK_MODULE
    LOCAL_REQUIRED_MODULES

    Set LOCAL_REQUIRED_MODULES 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.

    LOCAL_RESOURCE_DIR
    LOCAL_SDK_VERSION
    LOCAL_SHARED_LIBRARIESThese are the libraries you directly link against. You don't need to +pass transitively included libraries. Specify the name without the suffix:

    +

    LOCAL_SHARED_LIBRARIES := \
    +     libutils \
    +     libui \
    +     libaudio \
    +     libexpat \
    +     libsgl +

    LOCAL_SRC_FILESThe build system looks at LOCAL_SRC_FILES 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:

    +

    LOCAL_SRC_FILES := \
    +     file1.cpp \
    +     dir/file2.cpp +

    LOCAL_STATIC_JAVA_LIBRARIES
    LOCAL_STATIC_LIBRARIESThese 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. +

    LOCAL_STATIC_LIBRARIES := \
    +     libutils \
    +     libtinyxml +

    LOCAL_UNINSTALLABLE_MODULE
    LOCAL_UNSTRIPPED_PATHInstructs 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 LOCAL_MODULE_PATH for an executable or a +shared library. If you overrode LOCAL_MODULE_PATH, but not +LOCAL_UNSTRIPPED_PATH, an error will occur.

    +

    See Putting modules elsewhere for more.

    LOCAL_WHOLE_STATIC_LIBRARIESThese 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. +

    LOCAL_WHOLE_STATIC_LIBRARIES := \
    +     libsqlite3_android
    +

    LOCAL_YACCFLAGSAny 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.

    +

    LOCAL_YACCFLAGS := -p kjsyy

    OVERRIDE_BUILT_MODULE_PATH
    \ No newline at end of file diff --git a/pdk/docs/guide/build_new_device.jd b/pdk/docs/guide/build_new_device.jd index e320ff3f..d914ebee 100755 --- a/pdk/docs/guide/build_new_device.jd +++ b/pdk/docs/guide/build_new_device.jd @@ -126,3 +126,191 @@ pdk.version=1.0

+ +

Product Definition Files

+ +

Product-specific variables are defined in product definition files. A product definition file can inherit from other product definition files, thus reducing the need to copy and simplifying maintenance.

+

Variables maintained in a product definition files include:

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescriptionExample
PRODUCT_NAMEEnd-user-visible name for the overall product. Appears in the "About the phone" info.
PRODUCT_MODELEnd-user-visible name for the end product
PRODUCT_LOCALESA space-separated list of two-letter language code, two-letter country code pairs that describe several settings for the user, such as the UI language and time, date and currency formatting. The first locale listed in PRODUCT_LOCALES is is used if the locale has never been set before.en_GB de_DE es_ES fr_CA
PRODUCT_PACKAGESLists the APKs to install.Calendar Contacts
PRODUCT_DEVICEName of the industrial designdream
PRODUCT_MANUFACTURERName of the manufactureracme
PRODUCT_BRANDThe brand (e.g., carrier) the software is customized for, if any
PRODUCT_PROPERTY_OVERRIDESList of property assignments in the format "key=value"
PRODUCT_COPY_FILESList of words like source_path:destination_path. The file at the source path should be copied to the destination path when building this product. The rules for the copy steps are defined in config/Makefile
PRODUCT_OTA_PUBLIC_KEYSList of OTA public keys for the product
PRODUCT_POLICYIndicate which policy this product should use
PRODUCT_PACKAGE_OVERLAYSIndicate whether to use default resources or add any product specific overlaysvendor/acme/overlay
PRODUCT_CONTRIBUTORS_FILEHTML file containing the contributors to the project.
PRODUCT_TAGSlist of space-separated words for a given product
PRODUCT_SDK_ADDON_NAME
PRODUCT_SDK_ADDON_COPY_FILES
PRODUCT_SDK_ADDON_COPY_MODULES
PRODUCT_SDK_ADDON_DOC_MODULE
+ +

+

The snippet below illustrates a typical product definition file.

+
+$(call inherit-product, build/target/product/generic.mk)
+
+#Overrides
+PRODUCT_NAME := MyDevice
+PRODUCT_MANUFACTURER := acme
+PRODUCT_BRAND := acme_us
+PRODUCT_LOCALES := en_GB es_ES fr_FR
+PRODUCT_PACKAGE_OVERLAYS := vendor/acme/overlay
+
+
+ +

Build Variants

+ +

+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 build variants: +

+ + + + + + + + + + + + + + +
+ eng + + This is the default flavor. A plain "make" is the + same as "make eng". droid is an alias + for eng. +
    +
  • Installs modules tagged with: eng, debug, + user, and/or development. +
  • Installs non-APK modules that have no tags specified. +
  • Installs APKs according to the product definition files, in + addition to tagged APKs. +
  • ro.secure=0 +
  • ro.debuggable=1 +
  • ro.kernel.android.checkjni=1 +
  • adb is enabled by default. +
+ user + + "make user" +

+ This is the flavor intended to be the final release bits. +

    +
  • Installs modules tagged with user. +
  • Installs non-APK modules that have no tags specified. +
  • Installs APKs according to the product definition files; tags + are ignored for APK modules. +
  • ro.secure=1 +
  • ro.debuggable=0 +
  • adb is disabled by default. +
+ userdebug + + "make userdebug" +

+ The same as user, except: +

    +
  • Also installs modules tagged with debug. +
  • ro.debuggable=1 +
  • adb is enabled by default. +
+ +

+If you build one flavor and then want to build another, you should run +"make installclean" between the two makes to guarantee that +you don't pick up files installed by the previous flavor. "make +clean" will also suffice, but it takes a lot longer. +

+ \ No newline at end of file diff --git a/pdk/docs/guide/build_system.jd b/pdk/docs/guide/build_system.jd index 158a0a76..36936aa5 100755 --- a/pdk/docs/guide/build_system.jd +++ b/pdk/docs/guide/build_system.jd @@ -10,7 +10,6 @@ pdk.version=1.0 Understanding the makefile
Layers
-Product Definition Files
Building the Android Platform
Device Code
@@ -31,8 +30,6 @@ pdk.version=1.0

Understanding Android's Build System

- -

Understanding the makefile

A makefile defines how to build a particular application. Makefiles typically include all of the following elements:

@@ -95,38 +92,6 @@ include $(BUILD_EXECUTABLE) - -

Product Definition Files

- -

Product-specific variables are defined in product definition files. A product definition file can inherit from other product definition files, thus reducing the need to copy and simplifying maintenance.

-

Variables maintained in a product definition files include:

-

    -
  • PRODUCT_DEVICE
    • -
  • LOCALES
    • -
  • BRANDING_PARTNER
    • -
  • PROPERTY_OVERRIDES
    • -
-

-

The snippet below illustrates a typical product definition file.

-
-//device/target/product/core.mk
-PRODUCT_PACKAGES := Home SettingsProvider ...
-//device/target/product/generic.mk
-PRODUCT_PACKAGES := Calendar Camera SyncProvider ...
-$(call inherit-product, target/product/core.mk)
-PRODUCT_NAME := generic
-//device/partner/google/products/core.mk
-PRODUCT_PACKAGES := Maps GoogleAppsProvider ...
-$(call inherit-product, target/product/core.mk)
-//device/partner/google/products/generic.mk
-PRODUCT_PACKAGES := Gmail GmailProvider ...
-$(call inherit-product, partner/google/products/core.mk)
-$(call inherit-product, target/product/generic.mk)
-PRODUCT_NAME := google_generic
-
-
- -

Building the Android Platform

This section describes how to build the default version of Android. Once you are comfortable with a generic build, then you can begin to modify Android for your own target device.

diff --git a/pdk/docs/guide/pdk_toc.cs b/pdk/docs/guide/pdk_toc.cs index 5944ce31..e6b2cd59 100644 --- a/pdk/docs/guide/pdk_toc.cs +++ b/pdk/docs/guide/pdk_toc.cs @@ -56,6 +56,7 @@ function nothing() {}
  • Early Suspend
    • +
  • Sensors
    • -- 2.11.0