1# Native API Map Files
2
3Native APIs such as those exposed by the NDK, LL-NDK, or APEX are described by
4map.txt files. These files are [linker version scripts] with comments that are
5semantically meaningful to [gen_stub_libs.py]. For an example of a map file, see
6[libc.map.txt].
7
8[gen_stub_libs.py]: https://cs.android.com/android/platform/superproject/+/master:build/soong/cc/gen_stub_libs.py
9[libc.map.txt]: https://cs.android.com/android/platform/superproject/+/master:bionic/libc/libc.map.txt
10[linker version scripts]: https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html
11
12## Basic format
13
14A linker version script defines at least one alphanumeric "version" definition,
15each of which contain a list of symbols. For example:
16
17```txt
18MY_API_R { # introduced=R
19  global:
20    api_foo;
21    api_bar;
22  local:
23    *;
24};
25
26MY_API_S { # introduced=S
27  global:
28    api_baz;
29} MY_API_R;
30```
31
32Comments on the same line as either a version definition or a symbol name have
33meaning. If you need to add any comments that should not be interpreted by the
34stub generator, keep them on their own line. For a list of supported comments,
35see the "Tags" section.
36
37Here, `api_foo` and `api_bar` are exposed in the generated stubs with the
38`MY_API_R` version and `api_baz` is exposed with the `MY_API_S` version. No
39other symbols are defined as public by this API. `MY_API_S` inherits all symbols
40defined by `MY_API_R`.
41
42When generating NDK API stubs from this version script, the stub library for R
43will define `api_foo` and `api_bar`. The stub library for S will define all
44three APIs.
45
46Note that, with few exceptions (see "Special version names" below), the name of
47the version has no inherent meaning.
48
49These map files can (and should) also be used as version scripts for building
50the implementation library rather than just defining the stub interface by using
51the `version_script` property of `cc_library`. This has the effect of limiting
52symbol visibility of the library to expose only the interface named by the map
53file. Without this, APIs that you have not explicitly exposed will still be
54available to users via `dlsym`. Note: All comments are ignored in this case. Any
55symbol named in any `global:` group will be visible.
56
57## Special version names
58
59Version names that end with `_PRIVATE` or `_PLATFORM` will not be exposed in any
60stubs, but will be exposed in the implementation library. Using either of these
61naming schemes is equivalent to marking the version with the `platform-only`
62tag. See the docs for `platform-only` for more information.
63
64## Tags
65
66Comments on the same line as a version definition or a symbol name are
67interpreted by the stub generator. Multiple space-delimited tags may be used on
68the same line. The supported tags are:
69
70### apex
71
72Indicates that the version or symbol is to be exposed in the APEX stubs rather
73than the NDK. May be used in combination with `llndk` if the symbol is exposed
74to both APEX and the LL-NDK.
75
76### future
77
78Indicates that the version or symbol is first introduced in the "future" API
79level. This is an abitrarily high API level used to define APIs that have not
80yet been added to a specific release.
81
82### introduced
83
84Indicates the version in which an API was first introduced. For example,
85`introduced=21` specifies that the API was first added (or first made public) in
86API level 21. This tag can be applied to either a version definition or an
87individual symbol. If applied to a version, all symbols contained in the version
88will have the tag applied. An `introduced` tag on a symbol overrides the value
89set for the version, if both are defined.
90
91Note: The map file alone does not contain all the information needed to
92determine which API level an API was added in. The `first_version` property of
93`ndk_library` will dictate which API levels stubs are generated for. If the
94module sets `first_version: "21"`, no symbols were introduced before API 21.
95
96Codenames can (and typically should) be used when defining new APIs. This allows
97the actual number of the API level to remain vague during development of that
98release. For example, `introduced=S` can be used to define APIs added in S. Any
99code name known to the build system can be used. For a list of versions known to
100the build system, see `out/soong/api_levels.json` (if not present, run `m
101out/soong/api_levels.json` to generate it).
102
103Architecture-specific variants of this tag exist:
104
105* `introduced-arm=VERSION`
106* `introduced-arm64=VERSION`
107* `introduced-x86=VERSION`
108* `introduced-x86_64=VERSION`
109
110The architecture-specific tag will take precedence over the architecture-generic
111tag when generating stubs for that architecture if both are present. If the
112symbol is defined with only architecture-specific tags, it will not be present
113for architectures that are not named.
114
115Note: The architecture-specific tags should, in general, not be used. These are
116primarily needed for APIs that were wrongly inconsistently exposed by libc/libm
117in old versions of Android before the stubs were well maintained. Think hard
118before using an architecture-specific tag for a new API.
119
120### llndk
121
122Indicates that the version or symbol is to be exposed in the LL-NDK stubs rather
123than the NDK. May be used in combination with `apex` if the symbol is exposed to
124both APEX and the LL-NDK.
125
126### platform-only
127
128Indicates that the version or symbol is public in the implementation library but
129should not be exposed in the stub library. Developers can still access them via
130`dlsym`, but they will not be exposed in the stubs so it should at least be
131clear to the developer that they are up to no good.
132
133The typical use for this tag is for exposing an API to the platform that is not
134for use by the NDK, LL-NDK, or APEX. It is preferable to keep such APIs in an
135entirely separate library to protect them from access via `dlsym`, but this is
136not always possible.
137
138### var
139
140Used to define a public global variable. By default all symbols are exposed as
141functions. In the uncommon situation of exposing a global variable, the `var`
142tag may be used.
143
144### versioned=VERSION
145
146Behaves similarly to `introduced` but defines the first version that the stub
147library should apply symbol versioning. For example:
148
149```txt
150R { # introduced=R
151  global:
152    foo;
153    bar; # versioned=S
154  local:
155    *;
156};
157```
158
159The stub library for R will contain symbols for both `foo` and `bar`, but only
160`foo` will include a versioned symbol `foo@R`. The stub library for S will
161contain both symbols, as well as the versioned symbols `foo@R` and `bar@R`.
162
163This tag is not commonly needed and is only used to hide symbol versioning
164mistakes that shipped as part of the platform.
165
166Note: Like `introduced`, the map file does not tell the whole story. The
167`ndk_library` Soong module may define a `unversioned_until` property that sets
168the default for the entire map file.
169
170### weak
171
172Indicates that the symbol should be [weak] in the stub library.
173
174[weak]: https://gcc.gnu.org/onlinedocs/gcc-4.7.2/gcc/Function-Attributes.html
175