openkylin
/
platform_build_soong
mirror of https://gitee.com/openkylin/platform_build_soong.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge "Update stub definition docs." am: 192131e36b am: 4d0bd284a4 am: 8d4a27a3fd 

Original change: https://android-review.googlesource.com/c/platform/build/soong/+/1674967

Change-Id: Icc444cb0516abefd1f85114d7db2d2883e70cf47
This commit is contained in:
Dan Albert 2021-04-15 22:50:01 +00:00 committed by Automerger Merge Worker
parent 70cb7240a8 8d4a27a3fd
commit 211b48731f
1 changed files with 20 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/map_files.md
View File

@ -52,7 +52,8 @@ the `version_script` property of `cc_library`. This has the effect of limiting
symbol visibility of the library to expose only the interface named by the map symbol visibility of the library to expose only the interface named by the map
file. Without this, APIs that you have not explicitly exposed will still be file. Without this, APIs that you have not explicitly exposed will still be
available to users via `dlsym`. Note: All comments are ignored in this case. Any available to users via `dlsym`. Note: All comments are ignored in this case. Any
symbol named in any `global:` group will be visible. symbol named in any `global:` group will be visible in the implementation
library. Annotations in comments only affect what is exposed by the stubs.
## Special version names ## Special version names
@ -76,9 +77,13 @@ to both APEX and the LL-NDK.
### future ### future
Indicates that the version or symbol is first introduced in the "future" API Indicates that the version or symbol is first introduced in the "future" API
level. This is an abitrarily high API level used to define APIs that have not level. This is an arbitrarily high API level used to define APIs that have not
yet been added to a specific release. yet been added to a specific release.
Warning: APIs marked `future` will be usable in any module with `sdk: "current"`
but **will not be included in the NDK**. `future` should generally not be used,
but is useful when developing APIs for an unknown future release.
### introduced ### introduced
Indicates the version in which an API was first introduced. For example, Indicates the version in which an API was first introduced. For example,
@ -92,13 +97,15 @@ Note: The map file alone does not contain all the information needed to
determine which API level an API was added in. The `first_version` property of determine which API level an API was added in. The `first_version` property of
`ndk_library` will dictate which API levels stubs are generated for. If the `ndk_library` will dictate which API levels stubs are generated for. If the
module sets `first_version: "21"`, no symbols were introduced before API 21. module sets `first_version: "21"`, no symbols were introduced before API 21.
**Symbol names for which no other rule applies will implicitly be introduced in
`first_version`.**
Codenames can (and typically should) be used when defining new APIs. This allows Code names can (and typically should) be used when defining new APIs. This
the actual number of the API level to remain vague during development of that allows the actual number of the API level to remain vague during development of
release. For example, `introduced=S` can be used to define APIs added in S. Any that release. For example, `introduced=S` can be used to define APIs added in S.
code name known to the build system can be used. For a list of versions known to Any code name known to the build system can be used. For a list of versions
the build system, see `out/soong/api_levels.json` (if not present, run `m known to the build system, see `out/soong/api_levels.json` (if not present, run
out/soong/api_levels.json` to generate it). `m out/soong/api_levels.json` to generate it).
Architecture-specific variants of this tag exist: Architecture-specific variants of this tag exist:
@ -123,6 +130,8 @@ Indicates that the version or symbol is to be exposed in the LL-NDK stubs rather
than the NDK. May be used in combination with `apex` if the symbol is exposed to than the NDK. May be used in combination with `apex` if the symbol is exposed to
both APEX and the LL-NDK. both APEX and the LL-NDK.
Historically this annotation was spelled `vndk`, but it has always meant LL-NDK.
### platform-only ### platform-only
Indicates that the version or symbol is public in the implementation library but Indicates that the version or symbol is public in the implementation library but
@ -131,9 +140,9 @@ should not be exposed in the stub library. Developers can still access them via
clear to the developer that they are up to no good. clear to the developer that they are up to no good.
The typical use for this tag is for exposing an API to the platform that is not The typical use for this tag is for exposing an API to the platform that is not
for use by the NDK, LL-NDK, or APEX. It is preferable to keep such APIs in an for use by the NDK, LL-NDK, or APEX (similar to Java's `@SystemAPI`). It is
entirely separate library to protect them from access via `dlsym`, but this is preferable to keep such APIs in an entirely separate library to protect them
not always possible. from access via `dlsym`, but this is not always possible.
### var ### var