David 'Digit' Turner | b9a8479 | 2009-05-07 20:39:04 +0200 | [diff] [blame^] | 1 | Application.mk file syntax specification |
| 2 | |
| 3 | Introduction: |
| 4 | ------------- |
| 5 | |
| 6 | This document describes the syntax of Application.mk build files |
| 7 | written to describe the native modules required by your Android |
| 8 | application. To understand what follows, it is assumed that you have |
| 9 | read the docs/OVERVIEW.TXT file that explains their role and |
| 10 | usage. |
| 11 | |
| 12 | Readers of this document should have read docs/OVERVIEW.TXT and |
| 13 | docs/ANDROID-MK.TXT |
| 14 | |
| 15 | |
| 16 | Overview: |
| 17 | --------- |
| 18 | |
| 19 | The purpose of Application.mk is to describe which native |
| 20 | 'modules' (i.e. static/shared libraries) are needed by your |
| 21 | application. |
| 22 | |
| 23 | Each Application.mk must be placed under a sub-directory of |
| 24 | the top-level apps directory, e.g.: |
| 25 | |
| 26 | $NDK/apps/<myapp>/Application.mk |
| 27 | |
| 28 | Where <myapp> is a short name used to describe your 'application' |
| 29 | to the NDK build system (this name doesn't go into your generated |
| 30 | shared libraries or your final packages). |
| 31 | |
| 32 | The Application.mk is really a tiny GNU Makefile fragment that must |
| 33 | define a few variables: |
| 34 | |
| 35 | APP_MODULES |
| 36 | This variable is mandatory and lists all the native modules |
| 37 | (described through Android.mk files) that your application |
| 38 | requires. |
| 39 | |
| 40 | This must be a space-separated list of module names as they |
| 41 | appear in the LOCAL_MODULE definitions of Android.mk files |
| 42 | |
| 43 | APP_PROJECT_PATH |
| 44 | This variable is mandatory and should give the *absolute* |
| 45 | path to your Application's project root directory. This is used |
| 46 | to copy/install stripped versions of the generated JNI shared |
| 47 | libraries to a specific location known to the APK-generating tools. |
| 48 | |
| 49 | APP_OPTIM |
| 50 | This optional variable can be defined to either 'release' or |
| 51 | 'debug'. This is used to alter the optimization level when |
| 52 | building your application's modules. |
| 53 | |
| 54 | A 'release' mode is the default, and will generate highly |
| 55 | optimized binaries. The 'debug' mode will generate un-optimized |
| 56 | binaries which are much easier to debug. |
| 57 | |
| 58 | Note that it is possible to debug both 'release' and 'debug' |
| 59 | binaries, but the 'release' builds tend to provide less information |
| 60 | during debugging sessions: some variables are optimized out and |
| 61 | can't be inspected, code re-ordering can make stepping through |
| 62 | the code difficult, stack traces may not be reliable, etc... |
| 63 | |
| 64 | APP_CFLAGS |
| 65 | A set of C compiler flags passed when compiling any C source code |
| 66 | of any of the modules. This can be used to change the build of a given |
| 67 | module depending on the application that needs it, instead of modifying |
| 68 | the Android.mk file itself. |
| 69 | |
| 70 | IMPORTANT WARNING: +++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 71 | + |
| 72 | + All paths in these flags should be relative to the top-level NDK |
| 73 | + directory. For example, if you have the following setup: |
| 74 | + |
| 75 | + sources/foo/Android.mk |
| 76 | + sources/bar/Android.mk |
| 77 | + |
| 78 | + To specify in foo/Android.mk that you want to add the path to the |
| 79 | + 'bar' sources during compilation, you should use: |
| 80 | + |
| 81 | + APP_CFLAGS += -Isources/bar |
| 82 | + |
| 83 | + Or alternatively: |
| 84 | + |
| 85 | + APP_CFLAGS += -I$(LOCAL_PATH)/../bar |
| 86 | + |
| 87 | + Using '-I../bar' will *NOT* work since it will be equivalent to |
| 88 | + '-I$NDK_ROOT/../bar' instead. |
| 89 | + |
| 90 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 91 | |
| 92 | APP_CXXFLAGS |
| 93 | Same as APP_CFLAGS for C++ sources. |
| 94 | |
| 95 | APP_CPPFLAGS |
| 96 | Same as APP_CFLAGS but will be passed to both C and C++ sources |
| 97 | |
| 98 | A trivial Application.mk file would be: |
| 99 | |
| 100 | -------------- cut here ------------------------- |
| 101 | APP_MODULES := <list of modules> |
| 102 | APP_PROJECT_PATH := <path to project> |
| 103 | -------------- cut here ------------------------- |
| 104 | |