forked from kareemn/android.mk
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1206 lines (1054 loc) · 49.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div id="qv-wrapper">
<div id="qv">
<h2>Secrets of Android.mk</h2>
<a name="toc">
</a><ul><a name="toc">
</a>
<li><a href="#intro">Intro to Android.mk</a></li>
<li><a href="#simple">Simple example</a></li>
<li><a href="#ndk">NDK Usage</a></li>
<li><a href="#moduleDesc">Defining Modules</a></li>
<li><a name="toc"></a><a href="#simpleAPK">Simple APK</a></li>
<li><a href="#APKJar">APK Dependent on static .jar file</a></li>
<li><a href="#APKPlatform">APK signed with the platform key</a></li>
<li><a href="#APKVendor">APK that signed with vendor key</a></li>
<li><a href="#prebuiltAPK">Prebuilt APK</a></li>
<li><a href="#staticJava">Adding a Static Java Library</a></li>
<li><a href="#mkVars">Android.mk variables</a></li>
</ul>
</div>
</div>
<div class="g-unit" >
<div style="white-space:pre;padding-left:10px;">
<a name="intro"></a><h3>Introduction to Android.mk:</h3>
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 docs/OVERVIEW.html file that explains their role and
usage.
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
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.
<a name="simple"></a><h3>Simple example:</h3>
Before describing the syntax in details, let's consider the simple "hello JNI" example, i.e. the files under:
<code>
apps/hello-jni/project
</code>
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:
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := hello-jni
LOCAL_SRC_FILES := hello-jni.c
include $(BUILD_SHARED_LIBRARY)
</pre>
Now, let's explain these lines:
<code>
LOCAL_PATH := $(call my-dir)
</code>
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).
<code>
include $(CLEAR_VARS)
</code>
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.
<code>
LOCAL_MODULE := hello-jni
</code>
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'.
<p class="note">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.</p>
<code>
LOCAL_SRC_FILES := hello-jni.c
</code>
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').
<code>
include $(BUILD_SHARED_LIBRARY)
</code>
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.
<h3>Reference:</h3>
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:
<pre> MY_SOURCES := foo.c
ifneq ($(MY_CONFIG_BAR),)
MY_SOURCES += bar.c
endif
LOCAL_SRC_FILES += $(MY_SOURCES)
</pre>
So, here we go:
<a name="ndk"></a><h4>NDK-provided variables:</h4>
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.:
<code>
include $(CLEAR_VARS)
</code>
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:
<code>
include $(BUILD_SHARED_LIBRARY)
</code>
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:
<code>
include $(BUILD_STATIC_LIBRARY)
</code>
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 docs/PREBUILTS.html for more
information).
PREBUILT_STATIC_LIBRARY
This is the same as PREBUILT_SHARED_LIBRARY, but for a static library file instead. See docs/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 docs/STABLE-APIS.html.
TARGET_ARCH_ABI
Name of the target CPU+ABI when this Android.mk is parsed.
Two values are supported at the moment:
<code>
armeabi</code> For ARMv5TE
<code>
armeabi-v7a</code>
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 docs/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)
<h4>NDK-provided function macros:</h4>
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:
<code>
LOCAL_PATH := $(call my-dir)
</code>
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:
<code>
LOCAL_PATH := $(call my-dir)
... declare one module
include $(LOCAL_PATH)/foo/Android.mk
LOCAL_PATH := $(call my-dir)
... declare another module
</code>
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:
<code>
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
</code>
If this is not convenient, save the value of the first my-dir call into another variable, for example:
<code>
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
</code>
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:
<code>
sources/foo/Android.mk
sources/foo/lib1/Android.mk
sources/foo/lib2/Android.mk
</code>
If sources/foo/Android.mk contains the single line:
<code>
include $(call all-subdir-makefiles)
</code>
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:
<code>
$(call import-module,<name>)
</code>
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 docs/IMPORT-MODULE.html for more details.
<a name="moduleDesc"></a><h4>Module-description variables:</h4>
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:
<code>
LOCAL_PATH := $(call my-dir)
</code>
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:
<code>
LOCAL_MODULE := foo-version-1
LOCAL_MODULE_FILENAME := libfoo
</code>
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 all relative to LOCAL_PATH and you can use path components, e.g.:
<code>
LOCAL_SRC_FILES := foo.c \
toto/bar.c
</code>
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 of C++ source files. The default is '.cpp' but you can change it. For example:
<code>
LOCAL_CPP_EXTENSION := .cxx
</code>
Since NDK r7, you can list several extensions in this variable, as in:
<code>
LOCAL_CPP_EXTENSION := .cxx .cpp .cc
</code>
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:
<code>
LOCAL_CPP_FEATURES := rtti
</code>
To indicate that your code uses C++ exceptions, use:
<code>
LOCAL_CPP_FEATURES := exceptions
</code>
You can also use both of them with (order is not important):
<code>
LOCAL_CPP_FEATURES := rtti exceptions
</code>
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:
<code>
LOCAL_C_INCLUDES := sources/foo
</code>
Or even:
<code>
LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo
</code>
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 (built with BUILD_STATIC_LIBRARY) that should be linked to this module. This only makes sense in
shared library modules.
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 module. 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:
<code>
LOCAL_LDLIBS := -lz
</code>
See docs/STABLE-APIS.html for the list of exposed system libraries you can linked against with this NDK release.
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.
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.:
<code>
LOCAL_ARM_MODE := arm
</code>
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:
<code>
LOCAL_SRC_FILES := foo.c bar.c.arm
</code>
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 docs/CPU-ARM-NEON.html and docs/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:
<code>
LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon
</code>
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:
http://en.wikipedia.org/wiki/NX_bit
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:
http://isisblogs.poly.edu/2011/06/01/relro-relocation-read-only/
http://www.akkadia.org/drepper/nonselsec.pdf (section 6)
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:
<code>
include $(CLEAR_VARS)
LOCAL_MODULE := foo
LOCAL_SRC_FILES := foo/foo.c
LOCAL_EXPORT_CFLAGS := -DFOO=1
include $(BUILD_STATIC_LIBRARY)
</code>
And another module, named 'bar' that depends on it as:
<code>
include $(CLEAR_VARS)
LOCAL_MODULE := bar
LOCAL_SRC_FILES := bar.c
LOCAL_CFLAGS := -DBAR=2
LOCAL_STATIC_LIBRARIES := foo
include $(BUILD_SHARED_LIBRARY)
</code>
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_LDLIBS
Same as LOCAL_EXPORT_CFLAGS, but for linker flags. 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:
<code>
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)
</code>
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_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:
<code>
LOCAL_SRC_FILES := foo.c bar.S
LOCAL_FILTER_ASM := myasmfilter
</code>
<code>
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
</code>
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:
<code>
myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S
myasmfilter bar.S $OBJS_DIR/bar.S
</code>
NDK_TOOLCHAIN_VERSION
Define this variable to either 4.4.3 or 4.6 to select version of GCC compiler. 4.6 is the default
</div>
<div class="wrapper">
<div id="jd-content">
<div class="jd-descr">
<p>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.</p>
<h3><a name="simpleAPK"></a>Building a simple APK</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# Build all java files in the java subdirectory
LOCAL_SRC_FILES := $(call all-subdir-java-files)
# Name of the APK to build
LOCAL_PACKAGE_NAME := LocalPackage
# Tell it to build an APK
include $(BUILD_PACKAGE)
</pre>
<h3><a name="APKJar"></a>Building a APK that depends on a static .jar file</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# List of static libraries to include in the package
LOCAL_STATIC_JAVA_LIBRARIES := static-library
# Build all java files in the java subdirectory
LOCAL_SRC_FILES := $(call all-subdir-java-files)
# Name of the APK to build
LOCAL_PACKAGE_NAME := LocalPackage
# Tell it to build an APK
include $(BUILD_PACKAGE)
</pre>
<h3><a name="APKPlatform"></a>Building a APK that should be signed with the platform key</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# Build all java files in the java subdirectory
LOCAL_SRC_FILES := $(call all-subdir-java-files)
# Name of the APK to build
LOCAL_PACKAGE_NAME := LocalPackage
LOCAL_CERTIFICATE := platform
# Tell it to build an APK
include $(BUILD_PACKAGE)
</pre>
<h3><a name="APKVendor"></a>Building a APK that should be signed with a specific vendor key</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# Build all java files in the java subdirectory
LOCAL_SRC_FILES := $(call all-subdir-java-files)
# Name of the APK to build
LOCAL_PACKAGE_NAME := LocalPackage
LOCAL_CERTIFICATE := vendor/example/certs/app
# Tell it to build an APK
include $(BUILD_PACKAGE)
</pre>
<h3><a name="prebuiltAPK"></a>Adding a prebuilt APK</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# Module name should match apk name to be installed.
LOCAL_MODULE := LocalModuleName
LOCAL_SRC_FILES := $(LOCAL_MODULE).apk
LOCAL_MODULE_CLASS := APPS
LOCAL_MODULE_SUFFIX := $(COMMON_ANDROID_PACKAGE_SUFFIX)
include $(BUILD_PREBUILT)
</pre>
<h3><a name="staticJava"></a>Adding a Static Java Library</h3>
<pre> LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
# Build all java files in the java subdirectory
LOCAL_SRC_FILES := $(call all-subdir-java-files)
# Any libraries that this library depends on
LOCAL_JAVA_LIBRARIES := android.test.runner
# The name of the jar file to create
LOCAL_MODULE := sample
# Build a static jar file.
include $(BUILD_STATIC_JAVA_LIBRARY)
</pre>
<h3><a name="mkVars"></a>Android.mk Variables</h3>
<p>These are the variables that you'll commonly see in Android.mk files, listed
alphabetically. First, a note on the variable naming: </p>
<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.
</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>
<table border="1" cellpadding="2" cellspacing="0">
<tbody><tr>
<th scope="col">Parameter</th>
<th scope="col">Description</th>
</tr>
<tr>
<td valign="top">LOCAL_AAPT_FLAGS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ACP_UNAVAILABLE</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ADDITIONAL_JAVA_DIR</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_AIDL_INCLUDES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ALLOW_UNDEFINED_SYMBOLS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ARM_MODE</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ASFLAGS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ASSET_DIR</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_ASSET_FILES</td>
<td valign="top">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>
<p><code>LOCAL_ASSET_FILES += $(call find-subdir-assets)</code></p></td>
</tr>
<tr>
<td valign="top">LOCAL_BUILT_MODULE_STEM</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_C_INCLUDES</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_CC</td>
<td valign="top">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.</td>
</tr>
<tr>
<td valign="top">LOCAL_CERTIFICATE</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_CFLAGS</td>
<td valign="top">If you have additional flags to pass into the C or C++ compiler, add
them here. For example:<p></p>
<p><code>LOCAL_CFLAGS += -DLIBUTILS_NATIVE=1</code></p></td>
</tr>
<tr>
<td valign="top">LOCAL_CLASSPATH</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_COMPRESS_MODULE_SYMBOLS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_COPY_HEADERS</td>
<td valign="top"><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></td>
</tr>
<tr>
<td valign="top">LOCAL_COPY_HEADERS_TO</td>
<td valign="top"><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></td>
</tr>
<tr>
<td valign="top">LOCAL_CPP_EXTENSION</td>
<td valign="top">If your C++ files end in something other than "<code>.cpp</code>",
you can specify the custom extension here. For example:
<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.</td>
</tr>
<tr>
<td valign="top">LOCAL_CPPFLAGS</td>
<td valign="top">If you have additional flags to pass into <i>only</i> the C++ compiler, add
them here. For example:<p></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></td>
</tr>
<tr>
<td valign="top">LOCAL_CXX</td>
<td valign="top">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.</td>
</tr>
<tr>
<td valign="top">LOCAL_DX_FLAGS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_EXPORT_PACKAGE_RESOURCES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_FORCE_STATIC_EXECUTABLE</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_GENERATED_SOURCES</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_INSTRUMENTATION_FOR</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_INSTRUMENTATION_FOR_PACKAGE_NAME</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_INTERMEDIATE_SOURCES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_INTERMEDIATE_TARGETS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_IS_HOST_MODULE</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_JAR_MANIFEST</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_JARJAR_RULES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_JAVA_LIBRARIES</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_JAVA_RESOURCE_DIRS</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_JAVA_RESOURCE_FILES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_JNI_SHARED_LIBRARIES</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top">LOCAL_LDFLAGS</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_LDLIBS</td>
<td valign="top"><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> </td>
</tr>
<tr>
<td valign="top">LOCAL_MODULE</td>
<td valign="top"><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>. </td>
</tr>
<tr>
<td valign="top">LOCAL_MODULE_PATH</td>
<td valign="top">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>
<p>See <a href="#moving-modules">Putting modules elsewhere</a> for more.</p></td>
</tr>