• Home
Name Date Size #Lines LOC

..--

Documentation/03-May-2024-3920

android/03-May-2024-293185

src/03-May-2024-14,66710,530

tests/03-May-2024-20,75820,315

utils/03-May-2024-612486

Android.bpD03-May-20244.6 KiB216179

MODULE_LICENSE_APACHE2D03-May-20240

OWNERSD03-May-2024144 75

README.mdD03-May-20246.8 KiB235183

README.md

1Header ABI Checker
2===================
3
4The header ABI checker consists of 3 tools:
5[header-abi-dumper](#Header-ABI-Dumper),
6[header-abi-linker](#Header-ABI-Linker), and
7[header-abi-diff](#Header-ABI-Diff).  The first two commands generate ABI dumps
8for shared libraries.  The third command compares the ABI dumps with the
9reference ABI dumps in [prebuilts/abi-dumps].  If there are no ABI dumps under
10[prebuilts/abi-dumps], follow the instructions in
11[Create Reference ABI Dumps](#Create-Reference-ABI-Dumps) to create one.
12
13[prebuilts/abi-dumps]: https://android.googlesource.com/platform/prebuilts/abi-dumps
14
15
16## Header ABI Dumper
17
18`header-abi-dumper` dumps the ABIs (including classes, functions, variables,
19etc) defined in a C/C++ source file.
20
21The `-I` command line option controls the scope of ABIs that must be dumped.
22If `-I <path-to-export-include-dir>` is specified, the generated ABI dump will
23only include the classes, the functions, and the variables that are defined in
24the header files under the exported include directories.
25
26### Usage
27
28```
29header-abi-dumper -o <dump-file> <source_file> \
30    -I <export-include-dir-1> \
31    -I <export-include-dir-2> \
32    ... \
33    -- \
34    <cflags>
35```
36
37For more command line options, run `header-abi-dumper --help`.
38
39
40## Header ABI Linker
41
42`header-abi-linker` links several ABI dumps produced by `header-abi-dumper`.
43This tool combines all the ABI information present in the input ABI dump files
44and prunes the irrelevant ABI dumps.
45
46### Usage
47
48```
49header-abi-linker -o <linked-abi-dump> \
50    <abi-dump1> <abi-dump2> <abi-dump3> ... \
51    -so <path to so file> \
52    -v <path to version script>
53```
54
55For more command line options, run `header-abi-linker --help`.
56
57
58## Header ABI Diff
59
60`header-abi-diff` compares two header ABI dumps produced by
61`header-abi-dumper`.  It produces a report outlining all the differences
62between the ABIs exposed by the two dumps.
63
64### Usage
65
66```
67header-abi-diff -old <old-abi-dump> -new <new-abi-dump> -o <report>
68```
69
70For more command line options, run `header-abi-diff --help`.
71
72### Return Value
73
74* `0`: Compatible
75* `1`: Changes to APIs unreferenced by symbols in the `.dynsym` table
76* `4`: Compatible extension
77* `8`: Incompatible
78* `16`: ELF incompatible (Some symbols in the `.dynsym` table, not exported by
79  public headers, were removed.)
80
81### Configuration
82header-abi-diff reads a config file named `config.json`. The config file must
83be placed in the dump directory, such as
84`prebuilts/abi-dumps/platform/33/64/x86_64/source-based/config.json`.
85The file consists of multiple sections. There are two types of sections: global
86config section and library config section. Each library config section contains
87flags for a specific version and a library. header-abi-diff chooses the library
88config section by command line options `-target-version` and `-lib`.
89
90#### Format
91Here is an example of a config.json.
92```json
93{
94  "global": {
95    "flags": {
96      "allow_adding_removing_weak_symbols": true,
97    },
98  },
99  "libfoo": [
100    {
101      "target_version": "current",
102      "flags": {
103        "check_all_apis": true,
104      },
105    },
106    {
107      "target_version": "34",
108      "ignore_linker_set_keys": [
109        "_ZTI14internal_state",
110      ],
111      "flags": {
112        "allow_extensions": true,
113      }
114    }
115  ]
116}
117```
118
119#### Library Config Section
120A library config section includes members: "target_version",
121"ignore_linker_set_keys" and "flags". header-abi-diff selects the config
122section that matches the target version given by CLI.
123Take above config as an example, if `-target-version 34` and `-lib libfoo` are
124specified, the selected config section is:
125```json
126{
127  "target_version": "34",
128  "ignore_linker_set_keys": [
129    "_ZTI14internal_state",
130  ],
131  "flags": {
132    "allow_extensions": true,
133  }
134}
135```
136
137#### Flags
138
139The config file and the header-abi-diff CLI support the same set of `flags`. If
140a flag is present in both CLI and config sections, the library config section
141takes priority, then the global config section and the CLI.
142
143## How to Resolve ABI Difference
144
145Android build system runs the ABI checker automatically when it builds the
146ABI-monitored libraries. Currently the build system compares the ABI of the
147source code with two sets of reference dumps: the **current version** and the
148**previous version**. The ABI difference is propagated as build errors. This
149section describes the common methods to resolve them.
150
151### Update Reference ABI Dumps
152
153When the build system finds difference between the source code and the ABI
154reference dumps for the **current** version, it instructs you to run
155`create_reference_dumps.py` to update the dumps.
156
157The command below updates the reference ABI dumps for all monitored libraries
158on arm, arm64, x86, and x86_64 architectures:
159
160```
161$ python3 utils/create_reference_dumps.py
162```
163
164To update reference ABI dumps for a specific library, `libfoo` for example,
165run the command below:
166
167```
168$ python3 utils/create_reference_dumps.py -l libfoo
169```
170
171For more command line options, run:
172
173```
174utils/create_reference_dumps.py --help
175```
176
177### Configure Cross-Version ABI Check
178
179When the build system finds incompatibility between the source code and the ABI
180of the **previous version**, it instructs you to follow this document to
181resolve it.
182
183If the ABI difference is intended, you may configure the ABI tools to ignore
184it. The following example shows how to make an exception for the ABI difference
185in `libfoo` between the current source and the previous version, `33`:
186
1871. Open `libfoo.so.33.abidiff` which is located in
188   `$OUT_DIR/soong/.intermediates` or `$DIST_DIR/abidiffs`. Find out the
189   `linker_set_key` of the type that has ABI difference. Here is a sample
190   abidiff file:
191
192   ```
193   lib_name: "libfoo"
194   arch: "x86_64"
195   record_type_diffs {
196     name: "bar"
197     ...
198     linker_set_key: "_ZTI3bar"
199   }
200   compatibility_status: INCOMPATIBLE
201   ```
202
2032. Find the reference dump directories by
204
205   `find $ANDROID_BUILD_TOP/prebuilts/abi-dumps/*/33 -name libfoo.so.lsdump -exec dirname {} +`
206
207   The command should show 6 directories for different architectures.
208
2093. Create or edit `config.json` in every directory, for instance,
210
211   `prebuilts/abi-dumps/ndk/33/64/x86_64/source-based/config.json`
212
213   ```
214   {
215     "libfoo": [
216       {
217         "target_version": "34",
218         "ignore_linker_set_keys": [
219           "_ZTI3bar",
220         ],
221       },
222     ],
223   }
224   ```
225
226   The config above makes the ABI tools ignore the difference in type
227   `_ZTI3bar` in `libfoo`. If the API level of this branch has been finalized
228   (i.e., PLATFORM_VERSION_CODENAME=REL), `target_version` must be set to the
229   API level. Otherwise, `target_version` must be set to
230   **the previous finalized API level + 1** so that the config will continue
231   being effective after finalization.
232
233For more information about the config files, please refer to
234[Configuration](#Configuration).
235