| `Android.mk` file syntax specification |
| |
| Introduction: |
| ------------- |
| |
| This document describes the syntax of `Android.mk` build file |
| written to describe your C and C++ source files to the Android |
| NDK. To understand what follows, it is assumed that you have |
| read the [OVERVIEW](OVERVIEW.html) file that explains their role and |
| usage. |
| |
| Overview: |
| --------- |
| |
| An `Android.mk` file is written to describe your sources to the |
| build system. More specifically: |
| |
| - The file is really a tiny GNU Makefile fragment that will be |
| parsed one or more times by the build system. As such, you |
| should try to minimize the variables you declare there and |
| do not assume that anything is not defined during parsing. |
| |
| - The file syntax is designed to allow you to group your |
| sources into 'modules'. A module is one of the following: |
| |
| - A static library. |
| - A shared library. |
| - A standalone executable. |
| |
| Only shared libraries will be installed/copied to your |
| application package. Static libraries can be used to generate |
| shared libraries though. |
| |
| You can define one or more modules in each `Android.mk` file, |
| and you can use the same source file in several modules. |
| |
| - The build system handles many details for you. For example, you |
| don't need to list header files or explicit dependencies between |
| generated files in your `Android.mk`. The NDK build system will |
| compute these automatically for you. |
| |
| This also means that, when updating to newer releases of the NDK, |
| you should be able to benefit from new toolchain/platform support |
| without having to touch your `Android.mk` files. |
| |
| Note that the syntax is *very* close to the one used in `Android.mk` files |
| distributed with the full open-source Android platform sources. While |
| the build system implementation that uses them is different, this is |
| an intentional design decision made to allow reuse of 'external' libraries' |
| source code easier for application developers. |
| |
| Simple example: |
| --------------- |
| |
| Before describing the syntax in details, let's consider the simple |
| "hello JNI" example, i.e. the files under: |
| |
| > `samples/hello-jni` |
| |
| Here, we can see: |
| |
| - The `src` directory containing the Java sources for the |
| sample Android project. |
| |
| - The `jni` directory containing the native source for |
| the sample, i.e. `jni/hello-jni.c` |
| |
| This source file implements a simple shared library that |
| implements a native method that returns a string to the |
| VM application. |
| |
| - The `jni/Android.mk` file that describes the shared library |
| to the NDK build system. Its content is: |
| |
| # |
| |
| ---------- cut here ------------------ |
| LOCAL_PATH := $(call my-dir) |
| |
| include $(CLEAR_VARS) |
| |
| LOCAL_MODULE := hello-jni |
| LOCAL_SRC_FILES := hello-jni.c |
| |
| include $(BUILD_SHARED_LIBRARY) |
| ---------- cut here ------------------ |
| |
| Now, let's explain these lines: |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| |
| An `Android.mk` file must begin with the definition of the LOCAL_PATH variable. |
| It is used to locate source files in the development tree. In this example, |
| the macro function 'my-dir', provided by the build system, is used to return |
| the path of the current directory (i.e. the directory containing the |
| `Android.mk` file itself). |
| |
| include $(CLEAR_VARS) |
| |
| The CLEAR_VARS variable is provided by the build system and points to a |
| special GNU Makefile that will clear many LOCAL_XXX variables for you |
| (e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc...), |
| with the exception of LOCAL_PATH. This is needed because all build |
| control files are parsed in a single GNU Make execution context where |
| all variables are global. |
| |
| LOCAL_MODULE := hello-jni |
| |
| The LOCAL_MODULE variable must be defined to identify each module you |
| describe in your `Android.mk`. The name must be *unique* and not contain |
| any spaces. Note that the build system will automatically add proper |
| prefix and suffix to the corresponding generated file. In other words, |
| a shared library module named 'foo' will generate 'libfoo.so'. |
| |
| IMPORTANT NOTE: |
| If you name your module 'libfoo', the build system will not |
| add another 'lib' prefix and will generate libfoo.so as well. |
| This is to support `Android.mk` files that originate from the |
| Android platform sources, would you need to use these. |
| |
| LOCAL_SRC_FILES := hello-jni.c |
| |
| The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source |
| files that will be built and assembled into a module. Note that you should |
| not list header and included files here, because the build system will |
| compute dependencies automatically for you; just list the source files |
| that will be passed directly to a compiler, and you should be good. |
| |
| Note that the default extension for C++ source files is '.cpp'. It is |
| however possible to specify a different one by defining the variable |
| LOCAL_CPP_EXTENSION. Don't forget the initial dot (i.e. '.cxx' will |
| work, but not 'cxx'). |
| |
| include $(BUILD_SHARED_LIBRARY) |
| |
| The BUILD_SHARED_LIBRARY is a variable provided by the build system that |
| points to a GNU Makefile script that is in charge of collecting all the |
| information you defined in LOCAL_XXX variables since the latest |
| 'include $(CLEAR_VARS)' and determine what to build, and how to do it |
| exactly. There is also BUILD_STATIC_LIBRARY to generate a static library. |
| |
| There are more complex examples in the samples directories, with commented |
| `Android.mk` files that you can look at. |
| |
| Reference: |
| ---------- |
| |
| This is the list of variables you should either rely on or define in |
| an `Android.mk`. You can define other variables for your own usage, but |
| the NDK build system reserves the following variable names: |
| |
| - Names that begin with LOCAL_ (e.g. LOCAL_MODULE) |
| - Names that begin with PRIVATE_, NDK_ or APP_ (used internally) |
| - Lower-case names (used internally, e.g. `my-dir`) |
| |
| If you need to define your own convenience variables in an `Android.mk` |
| file, we recommend using the MY_ prefix, for a trivial example: |
| |
| ---------- cut here ------------------ |
| MY_SOURCES := foo.c |
| ifneq ($(MY_CONFIG_BAR),) |
| MY_SOURCES += bar.c |
| endif |
| |
| LOCAL_SRC_FILES += $(MY_SOURCES) |
| ---------- cut here ------------------ |
| |
| So, here we go: |
| |
| |
| NDK-provided variables: |
| ----------------------- |
| |
| These GNU Make variables are defined by the build system before |
| your `Android.mk` file is parsed. Note that under certain circumstances |
| the NDK might parse your `Android.mk` several times, each with different |
| definition for some of these variables. |
| |
| - - - - - - - - - - - |
| CLEAR_VARS |
| > Points to a build script that undefines nearly all LOCAL_XXX variables |
| > listed in the "Module-description" section below. You must include |
| > the script before starting a new module, e.g.: |
| |
| include $(CLEAR_VARS) |
| |
| - - - - - - - - - - - |
| BUILD_SHARED_LIBRARY |
| > Points to a build script that collects all the information about the |
| > module you provided in LOCAL_XXX variables and determines how to build |
| > a target shared library from the sources you listed. Note that you |
| > must have LOCAL_MODULE and LOCAL_SRC_FILES defined, at a minimum before |
| > including this file. Example usage: |
| |
| include $(BUILD_SHARED_LIBRARY) |
| |
| > note that this will generate a file named `lib$(LOCAL_MODULE).so`. |
| |
| - - - - - - - - - - - |
| BUILD_STATIC_LIBRARY |
| > A variant of BUILD_SHARED_LIBRARY that is used to build a target static |
| > library instead. Static libraries are not copied into your |
| > project/packages but can be used to build shared libraries (see |
| > LOCAL_STATIC_LIBRARIES and LOCAL_WHOLE_STATIC_LIBRARIES described below). |
| > Example usage: |
| |
| include $(BUILD_STATIC_LIBRARY) |
| |
| > Note that this will generate a file named `lib$(LOCAL_MODULE).a`. |
| |
| - - - - - - - - - - - |
| PREBUILT_SHARED_LIBRARY |
| > Points to a build script used to specify a prebuilt shared library. |
| > Unlike BUILD_SHARED_LIBRARY and BUILD_STATIC_LIBRARY, the value |
| > of LOCAL_SRC_FILES must be a single path to a prebuilt shared |
| > library (e.g. `foo/libfoo.so`), instead of a source file. |
| |
| > You can reference the prebuilt library in another module using |
| > the LOCAL_PREBUILTS variable (see [PREBUILTS](PREBUILTS.html) for more |
| > information). |
| |
| - - - - - - - - - - - |
| PREBUILT_STATIC_LIBRARY |
| > This is the same as PREBUILT_SHARED_LIBRARY, but for a static library |
| > file instead. See [PREBUILTS](PREBUILTS.html) for more. |
| |
| - - - - - - - - - - - |
| TARGET_ARCH |
| > Name of the target CPU architecture as it is specified by the |
| > full Android open-source build. This is 'arm' for any ARM-compatible |
| > build, independent of the CPU architecture revision. |
| |
| - - - - - - - - - - - |
| TARGET_PLATFORM |
| > Name of the target Android platform when this `Android.mk` is parsed. |
| > For example, 'android-3' correspond to Android 1.5 system images. For |
| > a complete list of platform names and corresponding Android system |
| > images, read [STABLE APIS](STABLE-APIS.html). |
| |
| - - - - - - - - - - - |
| TARGET_ARCH_ABI |
| > Name of the target CPU+ABI when this `Android.mk` is parsed. |
| > Four values are supported at the moment: |
| |
| armeabi |
| For ARMv5TE |
| |
| armeabi-v7a |
| For ARMv7 |
| |
| x86 |
| For i686 |
| |
| x86_64 |
| For x86-64 |
| |
| mips |
| For mips32 (r1) |
| |
| > NOTE: Up to Android NDK 1.6_r1, this variable was simply defined |
| > as '`arm`'. However, the value has been redefined to better |
| > match what is used internally by the Android platform. |
| |
| > For more details about architecture ABIs and corresponding |
| > compatibility issues, please read [CPU ARCH ABIS](CPU-ARCH-ABIS.html) |
| |
| > Other target ABIs will be introduced in future releases of the NDK |
| > and will have a different name. Note that all ARM-based ABIs will |
| > have 'TARGET_ARCH' defined to '`arm`', but may have different |
| > 'TARGET_ARCH_ABI' |
| |
| - - - - - - - - - - - |
| TARGET_ABI |
| > The concatenation of target platform and ABI, it really is defined |
| > as `$(TARGET_PLATFORM)-$(TARGET_ARCH_ABI)` and is useful when you want |
| > to test against a specific target system image for a real device. |
| |
| > By default, this will be '`android-3-armeabi`' |
| |
| > (Up to Android NDK 1.6_r1, this used to be '`android-3-arm`' by default) |
| |
| NDK-provided function macros: |
| ----------------------------- |
| |
| The following are GNU Make 'function' macros, and must be evaluated |
| by using '$(call <function>)'. They return textual information. |
| |
| - - - - |
| my-dir |
| > Returns the path of the last included Makefile, which typically is |
| > the current `Android.mk`'s directory. This is useful to define |
| > LOCAL_PATH at the start of your `Android.mk` as with: |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| > IMPORTANT NOTE: Due to the way GNU Make works, this really returns |
| > the path of the *last* *included* *Makefile* during the parsing of |
| > build scripts. Do not call `my-dir` after including another file. |
| |
| > For example, consider the following example: |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| ... declare one module |
| |
| include $(LOCAL_PATH)/foo/`Android.mk` |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| ... declare another module |
| |
| > The problem here is that the second call to `my-dir` will define |
| > LOCAL_PATH to `$PATH/foo` instead of `$PATH`, due to the include that |
| > was performed before that. |
| |
| > For this reason, it's better to put additional includes after |
| > everything else in an `Android.mk`, as in: |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| ... declare one module |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| ... declare another module |
| |
| # extra includes at the end of the `Android.mk` |
| include $(LOCAL_PATH)/foo/`Android.mk` |
| |
| > If this is not convenient, save the value of the first `my-dir` call |
| > into another variable, for example: |
| |
| MY_LOCAL_PATH := $(call my-dir) |
| |
| LOCAL_PATH := $(MY_LOCAL_PATH) |
| |
| ... declare one module |
| |
| include $(LOCAL_PATH)/foo/`Android.mk` |
| |
| LOCAL_PATH := $(MY_LOCAL_PATH) |
| |
| ... declare another module |
| |
| |
| - - - - |
| all-subdir-makefiles |
| > Returns a list of `Android.mk` located in all sub-directories of |
| > the current 'my-dir' path. For example, consider the following |
| > hierarchy: |
| |
| sources/foo/Android.mk |
| sources/foo/lib1/Android.mk |
| sources/foo/lib2/Android.mk |
| |
| > If sources/foo/`Android.mk` contains the single line: |
| |
| include $(call all-subdir-makefiles) |
| |
| > Then it will include automatically sources/foo/lib1/`Android.mk` and |
| > sources/foo/lib2/`Android.mk` |
| |
| > This function can be used to provide deep-nested source directory |
| > hierarchies to the build system. Note that by default, the NDK |
| > will only look for files in sources/*/`Android.mk` |
| |
| - - - - |
| this-makefile |
| > Returns the path of the current Makefile (i.e. where the function |
| > is called). |
| |
| - - - - |
| parent-makefile |
| > Returns the path of the parent Makefile in the inclusion tree, |
| > i.e. the path of the Makefile that included the current one. |
| |
| - - - - |
| grand-parent-makefile |
| > Guess what... |
| |
| - - - - |
| import-module |
| > A function that allows you to find and include the `Android.mk` |
| > of another module by name. A typical example is: |
| |
| $(call import-module,<name>) |
| |
| > And this will look for the module tagged <name> in the list of |
| > directories referenced by your NDK_MODULE_PATH environment |
| > variable, and include its `Android.mk` automatically for you. |
| > |
| > Read [IMPORT-MODULE](IMPORT-MODULE.html) for more details. |
| - - - - |
| |
| |
| Module-description variables: |
| ----------------------------- |
| |
| The following variables are used to describe your module to the build |
| system. You should define some of them between an '`include $(CLEAR_VARS)`' |
| and an '`include $(BUILD_XXXXX)`'. As written previously, $(CLEAR_VARS) is |
| a script that will undefine/clear all of these variables, unless explicitly |
| noted in their description. |
| |
| - - - - |
| LOCAL_PATH |
| > This variable is used to give the path of the current file. |
| > You MUST define it at the start of your `Android.mk`, which can |
| > be done with: |
| |
| LOCAL_PATH := $(call my-dir) |
| |
| > This variable is *not* cleared by $(CLEAR_VARS) so only one |
| > definition per `Android.mk` is needed (in case you define several |
| > modules in a single file). |
| |
| - - - - |
| LOCAL_MODULE |
| > This is the name of your module. It must be unique among all |
| > module names, and shall not contain any space. You MUST define |
| > it before including any $(BUILD_XXXX) script. |
| > |
| > By default, the module name determines the name of generated files, |
| > e.g. lib<foo>.so for a shared library module named <foo>. However |
| > you should only refer to other modules with their 'normal' |
| > name (e.g. <foo>) in your NDK build files (either `Android.mk` |
| > or Application.mk) |
| > |
| > You can override this default with LOCAL_MODULE_FILENAME (see below) |
| |
| - - - - |
| LOCAL_MODULE_FILENAME |
| > This variable is optional, and allows you to redefine the name of |
| > generated files. By default, module <foo> will always generate a |
| > static library named lib<foo>.a or a shared library named lib<foo>.so, |
| > which are standard Unix conventions. |
| > |
| > You can override this by defining LOCAL_MODULE_FILENAME, For example: |
| |
| LOCAL_MODULE := foo-version-1 |
| LOCAL_MODULE_FILENAME := libfoo |
| |
| > *NOTE(: You should not put a path or file extension in your |
| > LOCAL_MODULE_FILENAME, these will be handled automatically by the |
| > build system. |
| |
| - - - - |
| LOCAL_SRC_FILES |
| > This is a list of source files that will be built for your module. |
| > Only list the files that will be passed to a compiler, since the |
| > build system automatically computes dependencies for you. |
| > |
| > Note that source files names are relative to LOCAL_PATH and |
| > you can use path components, e.g.: |
| |
| LOCAL_SRC_FILES := foo.c \ |
| toto/bar.c |
| |
| > Absolute file paths are also supported: |
| |
| LOCAL_SRC_FILES := /home/user/mysources/foo.c |
| |
| > or on Windows: |
| |
| LOCAL_SRC_FILES := c:/Users/user/sources/foo.c |
| |
| > Avoiding absolute file paths is recommended, this makes your |
| > `Android.mk` easy to reuse on a different machine / system. |
| > |
| > NOTE: Always use Unix-style forward slashes (/) in build files. |
| > Windows-style back-slashes will not be handled properly. |
| |
| - - - - |
| LOCAL_CPP_EXTENSION |
| > This is an optional variable that can be defined to indicate |
| > the file extension(s) of C++ source files. They must begin with a dot. |
| > The default is '.cpp' but you can change it. For example: |
| |
| LOCAL_CPP_EXTENSION := .cxx |
| |
| > Since NDK r7, you can list several extensions in this variable, as in: |
| |
| LOCAL_CPP_EXTENSION := .cxx .cpp .cc |
| |
| - - - - |
| LOCAL_CPP_FEATURES |
| > This is an optional variable that can be defined to indicate |
| > that your code relies on specific C++ features. To indicate that |
| > your code uses RTTI (RunTime Type Information), use the following: |
| |
| LOCAL_CPP_FEATURES := rtti |
| |
| > To indicate that your code uses C++ exceptions, use: |
| |
| LOCAL_CPP_FEATURES := exceptions |
| |
| > You can also use both of them with (order is not important): |
| |
| LOCAL_CPP_FEATURES := rtti features |
| |
| > The effect of this variable is to enable the right compiler/linker |
| > flags when building your modules from sources. For prebuilt binaries, |
| > this also helps declare which features the binary relies on to ensure |
| > the final link works correctly. |
| > |
| > It is recommended to use this variable instead of enabling `-frtti` and |
| > `-fexceptions` directly in your LOCAL_CPPFLAGS definition. |
| |
| - - - - |
| LOCAL_C_INCLUDES |
| > An optional list of paths, relative to the NDK *root* directory, |
| > which will be appended to the include search path when compiling |
| > all sources (C, C++ and Assembly). For example: |
| |
| LOCAL_C_INCLUDES := sources/foo |
| |
| > Or even: |
| |
| LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo |
| |
| > These are placed before any corresponding inclusion flag in |
| > LOCAL_CFLAGS / LOCAL_CPPFLAGS |
| > |
| > The LOCAL_C_INCLUDES path are also used automatically when |
| > launching native debugging with ndk-gdb. |
| |
| |
| - - - - |
| LOCAL_CFLAGS |
| > An optional set of compiler flags that will be passed when building |
| > C *and* C++ source files. |
| > |
| > This can be useful to specify additional macro definitions or |
| > compile options. |
| > |
| > **IMPORTANT**: Try not to change the optimization/debugging level in |
| > your `Android.mk`, this can be handled automatically for |
| > you by specifying the appropriate information in |
| > your Application.mk, and will let the NDK generate |
| > useful data files used during debugging. |
| > |
| > NOTE: In android-ndk-1.5_r1, the corresponding flags only applied |
| > to C source files, not C++ ones. This has been corrected to |
| > match the full Android build system behaviour. (You can use |
| > LOCAL_CPPFLAGS to specify flags for C++ sources only now). |
| > |
| > It is possible to specify additional include paths with |
| > LOCAL_CFLAGS += -I<path>, however, it is better to use LOCAL_C_INCLUDES |
| > for this, since the paths will then also be used during native |
| > debugging with ndk-gdb. |
| |
| |
| - - - - |
| LOCAL_CXXFLAGS |
| > An alias for LOCAL_CPPFLAGS. Note that use of this flag is obsolete |
| > as it may disappear in future releases of the NDK. |
| |
| - - - - |
| LOCAL_CPPFLAGS |
| > An optional set of compiler flags that will be passed when building |
| > C++ source files *only*. They will appear after the LOCAL_CFLAGS |
| > on the compiler's command-line. |
| > |
| > NOTE: In android-ndk-1.5_r1, the corresponding flags applied to |
| > both C and C++ sources. This has been corrected to match the |
| > full Android build system. (You can use LOCAL_CFLAGS to specify |
| > flags for both C and C++ sources now). |
| |
| - - - - |
| LOCAL_STATIC_LIBRARIES |
| > The list of static libraries modules that the current module depends |
| > on. |
| > |
| > If the current module is a shared library or an executable, this will |
| > force these libraries to be linked into the resulting binary. |
| > |
| > If the current module is a static library, this simply tells that |
| > another other module that depends on the current one will also |
| > depend on the listed libraries. |
| |
| - - - - |
| LOCAL_SHARED_LIBRARIES |
| > The list of shared libraries *modules* this module depends on at runtime. |
| > This is necessary at link time and to embed the corresponding information |
| > in the generated file. |
| > |
| |
| - - - - |
| LOCAL_WHOLE_STATIC_LIBRARIES |
| > A variant of LOCAL_STATIC_LIBRARIES used to express that the corresponding |
| > library module should be used as "whole archives" to the linker. See the |
| > GNU linker's documentation for the `--whole-archive` flag. |
| > |
| > This is generally useful when there are circular dependencies between |
| > several static libraries. Note that when used to build a shared library, |
| > this will force all object files from your whole static libraries to be |
| > added to the final binary. This is not true when generating executables |
| > though. |
| |
| - - - - |
| LOCAL_LDLIBS |
| > The list of additional linker flags to be used when building your |
| > shared library or executable. This is useful to pass the name of |
| > specific system libraries with the '`-l`' prefix. For example, the |
| > following will tell the linker to generate a module that links to |
| > `/system/lib/libz.so` at load time: |
| |
| LOCAL_LDLIBS := -lz |
| |
| > See [STABLE-APIS](STABLE-APIS.html) for the list of exposed system libraries you |
| > can linked against with this NDK release. |
| > |
| > NOTE: This is ignored for static libraries, and ndk-build will print |
| > a warning if you define it in such a module. |
| |
| - - - - |
| LOCAL_LDFLAGS |
| > The list of other linker flags to be used when building your shared |
| > library or executable. For example, the following will use the `ld.bfd` |
| > linker on ARM/X86 GCC 4.6+ where `ld.gold` is the default |
| |
| LOCAL_LDFLAGS += -fuse-ld=bfd |
| |
| > NOTE: This is ignored for static libraries, and ndk-build will print |
| > a warning if you define it in such a module. |
| |
| - - - - |
| LOCAL_ALLOW_UNDEFINED_SYMBOLS |
| > By default, any undefined reference encountered when trying to build |
| > a shared library will result in an "undefined symbol" error. This is a |
| > great help to catch bugs in your source code. |
| > |
| > However, if for some reason you need to disable this check, set this |
| > variable to '`true`'. Note that the corresponding shared library may fail |
| > to load at runtime. |
| > |
| > *NOTE*: This is ignored for static libraries, and ndk-build will print |
| > a warning if you define it in such a module. |
| |
| - - - - |
| LOCAL_ARM_MODE |
| > By default, ARM target binaries will be generated in 'thumb' mode, where |
| > each instruction are 16-bit wide. You can define this variable to '`arm`' |
| > if you want to force the generation of the module's object files in |
| > 'arm' (32-bit instructions) mode. E.g.: |
| |
| LOCAL_ARM_MODE := arm |
| |
| > Note that you can also instruct the build system to only build specific |
| > sources in ARM mode by appending an '`.arm`' suffix to its source file |
| > name. For example, with: |
| |
| LOCAL_SRC_FILES := foo.c bar.c.arm |
| |
| > Tells the build system to always compile '`bar.c`' in ARM mode, and to |
| > build `foo.c` according to the value of LOCAL_ARM_MODE. |
| > |
| > NOTE: Setting APP_OPTIM to '`debug`' in your `Application.mk` will also force |
| > the generation of ARM binaries as well. This is due to bugs in the |
| > toolchain debugger that don't deal too well with thumb code. |
| |
| - - - - |
| LOCAL_ARM_NEON |
| > Defining this variable to '`true`' allows the use of ARM Advanced SIMD |
| > (a.k.a. NEON) GCC intrinsics in your C and C++ sources, as well as |
| > NEON instructions in Assembly files. |
| > |
| > You should only define it when targeting the '`armeabi-v7a`' ABI that |
| > corresponds to the ARMv7 instruction set. Note that not all ARMv7 |
| > based CPUs support the NEON instruction set extensions and that you |
| > should perform runtime detection to be able to use this code at runtime |
| > safely. To learn more about this, please read the documentation at |
| > [CPU-ARM-NEON](CPU-ARM-NEON.html) and [CPU-FEATURES](CPU-FEATURES.html). |
| > |
| > Alternatively, you can also specify that only specific source files |
| > may be compiled with NEON support by using the '`.neon`' suffix, as |
| > in: |
| |
| LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon |
| |
| > In this example, '`foo.c`' will be compiled in thumb+neon mode, |
| > '`bar.c`' will be compiled in 'thumb' mode, and '`zoo.c`' will be |
| > compiled in 'arm+neon' mode. |
| > |
| > Note that the '`.neon`' suffix must appear after the '`.arm`' suffix |
| > if you use both (i.e. `foo.c.arm.neon` works, but not `foo.c.neon.arm` !) |
| |
| - - - - |
| LOCAL_DISABLE_NO_EXECUTE |
| > Android NDK r4 added support for the "NX bit" security feature. |
| > It is enabled by default, but you can disable it if you *really* |
| > need to by setting this variable to 'true'. |
| > |
| > NOTE: This feature does not modify the ABI and is only enabled on |
| > kernels targeting ARMv6+ CPU devices. Machine code generated |
| > with this feature enabled will run unmodified on devices |
| > running earlier CPU architectures. |
| > |
| > For more information, see: |
| > |
| > * [Wikipedia: NX bit](http://en.wikipedia.org/wiki/NX_bit) |
| > * [The GNU stack kickstart](http://www.gentoo.org/proj/en/hardened/gnu-stack.xml) |
| |
| - - - - |
| LOCAL_DISABLE_RELRO |
| > By default, NDK compiled code is built with read-only relocations |
| > and GOT protection. This instructs the runtime linker to mark |
| > certain regions of memory as being read-only after relocation, |
| > making certain security exploits (such as GOT overwrites) harder |
| > to perform. |
| > |
| > It is enabled by default, but you can disable it if you *really* |
| > need to by setting this variable to '`true`'. |
| > |
| > NOTE: These protections are only effective on newer Android devices |
| > ("Jelly Bean" and beyond). The code will still run on older |
| > versions (albeit without memory protections). |
| > |
| > For more information, see: |
| > |
| > * [RELRO: RELocation Read-Only](http://isisblogs.poly.edu/2011/06/01/relro-relocation-read-only/) |
| > * [Security enhancements in RedHat Enterprise Linux (section 6)](http://www.akkadia.org/drepper/nonselsec.pdf) |
| |
| - - - - |
| LOCAL_DISABLE_FORMAT_STRING_CHECKS |
| > By default, NDK compiled code is compiled with format string |
| > protection. This forces a compiler error if a non-constant format |
| > string is used in a printf style function. |
| > |
| > It is enabled by default, but you can disable it if you *really* |
| > need to by setting this variable to '`true`'. |
| |
| - - - - |
| LOCAL_EXPORT_CFLAGS |
| > Define this variable to record a set of C/C++ compiler flags that will |
| > be added to the LOCAL_CFLAGS definition of any other module that uses |
| > this one with LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES. |
| > |
| > For example, consider the module '`foo`' with the following definition: |
| |
| include $(CLEAR_VARS) |
| LOCAL_MODULE := foo |
| LOCAL_SRC_FILES := foo/foo.c |
| LOCAL_EXPORT_CFLAGS := -DFOO=1 |
| include $(BUILD_STATIC_LIBRARY) |
| |
| > And another module, named '`bar`' that depends on it as: |
| |
| include $(CLEAR_VARS) |
| LOCAL_MODULE := bar |
| LOCAL_SRC_FILES := bar.c |
| LOCAL_CFLAGS := -DBAR=2 |
| LOCAL_STATIC_LIBRARIES := foo |
| include $(BUILD_SHARED_LIBRARY) |
| |
| > Then, the flags '`-DFOO=1` `-DBAR=2`' will be passed to the compiler when |
| > building `bar.c`. |
| > |
| > Exported flags are prepended to your module's LOCAL_CFLAGS so you can |
| > easily override them. They are also transitive: if '`zoo`' depends on |
| > '`bar`' which depends on '`foo`', then '`zoo`' will also inherit all flags |
| > exported by '`foo`'. |
| > |
| > Finally, exported flags are *not* used when building the module that |
| > exports them. In the above example, `-DFOO=1` would not be passed to the |
| > compiler when building `foo/foo.c`. |
| |
| - - - - |
| LOCAL_EXPORT_CPPFLAGS |
| > Same as LOCAL_EXPORT_CFLAGS, but for C++ flags only. |
| |
| - - - - |
| LOCAL_EXPORT_C_INCLUDES |
| > Same as LOCAL_EXPORT_CFLAGS, but for C include paths. |
| > This can be useful if 'bar.c' wants to include headers |
| > that are provided by module 'foo'. |
| |
| - - - - |
| LOCAL_EXPORT_LDFLAGS |
| > Same as LOCAL_EXPORT_CFLAGS, but for linker flags. |
| |
| - - - - |
| LOCAL_EXPORT_LDLIBS |
| > Same as LOCAL_EXPORT_CFLAGS, but for passing the name of specific |
| > system libraries with the '`-l`' prefix. Note that the |
| > imported linker flags will be appended to your module's LOCAL_LDLIBS |
| > though, due to the way Unix linkers work. |
| > |
| > This is typically useful when module '`foo`' is a static library and has |
| > code that depends on a system library. LOCAL_EXPORT_LDLIBS can then be |
| > used to export the dependency. For example: |
| |
| include $(CLEAR_VARS) |
| LOCAL_MODULE := foo |
| LOCAL_SRC_FILES := foo/foo.c |
| LOCAL_EXPORT_LDLIBS := -llog |
| include $(BUILD_STATIC_LIBRARY) |
| |
| include $(CLEAR_VARS) |
| LOCAL_MODULE := bar |
| LOCAL_SRC_FILES := bar.c |
| LOCAL_STATIC_LIBRARIES := foo |
| include $(BUILD_SHARED_LIBRARY) |
| |
| > There, `libbar.so` will be built with a `-llog` at the end of the linker |
| > command to indicate that it depends on the system logging library, |
| > because it depends on '`foo`'. |
| |
| - - - - |
| LOCAL_SHORT_COMMANDS |
| > Set this variable to '`true`' when your module has a very high number of |
| > sources and/or dependent static or shared libraries. This forces the |
| > build system to use an intermediate list file, and use it with the |
| > library archiver or static linker with the `@$(listfile)` syntax. |
| |
| > This can be useful on Windows, where the command-line only accepts |
| > a maximum of 8191 characters, which can be too small for complex |
| > projects. |
| |
| > This also impacts the compilation of individual source files, placing |
| > nearly all compiler flags inside list files too. |
| |
| > Note that any other value than '`true`' will revert to the default |
| > behaviour. You can also define APP_SHORT_COMMANDS in your |
| > Application.mk to force this behaviour for all modules in your |
| > project. |
| |
| > *NOTE*: We do not recommend enabling this feature by default, since it |
| > makes the build slower. |
| |
| - - - - |
| LOCAL_THIN_ARCHIVE |
| > Set this variable to '`true`' when building static libraries. This will |
| > generate a 'thin archive', i.e. a library file (e.g. `libfoo.a`) which |
| > doesn't contain object files, but simply file paths to the actual |
| > objects that it should normally contain. |
| |
| > This is useful to reduce the size of your build output. The drawback |
| > is that such libraries _cannot_ be moved to a different location |
| > (all paths inside them are relative). |
| |
| > Valid values are '`true`', '`false`' or empty. A default value can be |
| > set in your Application.mk through APP_THIN_ARCHIVE. |
| |
| > *NOTE*: This is ignored for non-static library modules, or prebuilt |
| > static library ones. |
| |
| - - - - |
| LOCAL_FILTER_ASM |
| > Define this variable to a shell command that will be used to filter |
| > the assembly files from, or generated from, your LOCAL_SRC_FILES. |
| > |
| > When it is defined, the following happens: |
| > |
| > - Any C or C++ source file is generated into a temporary assembly |
| > file (instead of being compiled into an object file). |
| > |
| > - Any temporary assembly file, and any assembly file listed in |
| > LOCAL_SRC_FILES is sent through the LOCAL_FILTER_ASM command |
| > to generate _another_ temporary assembly file. |
| > |
| > - These filtered assembly files are compiled into object file. |
| > |
| > In other words, If you have: |
| |
| LOCAL_SRC_FILES := foo.c bar.S |
| LOCAL_FILTER_ASM := myasmfilter |
| |
| foo.c --1--> $OBJS_DIR/foo.S.original --2--> $OBJS_DIR/foo.S --3--> $OBJS_DIR/foo.o |
| bar.S --2--> $OBJS_DIR/bar.S --3--> $OBJS_DIR/bar.o |
| |
| > Were "1" corresponds to the compiler, "2" to the filter, and "3" to the |
| > assembler. The filter must be a standalone shell command that takes the |
| > name of the input file as its first argument, and the name of the output |
| > file as the second one, as in: |
| |
| myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S |
| myasmfilter bar.S $OBJS_DIR/bar.S |