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