1VNDK Header Checker
2===================
3
4The VNDK header 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
82## Create Reference ABI Dumps
83
84`utils/create_reference_dumps.py` may be used to create reference ABI dumps.
85
86#For VNDK libraries
87
88For example, the command below creates reference ABI dumps for all VNDK shared
89libraries on arm, arm64, x86, and x86_64 architectures:
90
91```
92$ python3 create_reference_dumps.py
93```
94
95To create reference ABI dumps for a specific library, run the command below:
96
97```
98$ python3 create_reference_dumps.py -l libfoo
99```
100
101This will create reference dumps for `libfoo`, assuming `libfoo` is a VNDK
102library.
103
104# For LLNDK libraries
105
106```
107$ python3 create_reference_dumps.py -l libfoo --llndk
108```
109This will create reference dumps for `libfoo`, assuming `libfoo` is an LLNDK
110library.
111
112
113For more command line options, run `utils/create_reference_dumps.py --help`.
114