1ABIMAP(1) abimap ABIMAP(1)
2
6 abimap - Generate and update linker version scripts
7
9 abimap [-h] {update,new,check,version} ...
10
12 abimap is a tool to generate and update linker scripts which add ver‐
13 sion information to symbols exported by a shared library.
14 It is intended to be integrated as part of the build process to check
16 for changes in the set of exported symbols and update the symbol ver‐
17 sion linker script accordingly.
18 The complete documentation can be found at
20 https://abimap.readthedocs.io
21
23 -h,--help:
24 Print the available options and subcommands
25
27 abimap update
28 Update an existing map file
29 abimap update [-h] [-o OUT] [-i INPUT] [-d]
31 [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
32 [-l LOGFILE] [-n NAME] [-v VERSION]
33 [-r RELEASE] [--no_guess] [--allow-abi-break]
34 [-f] [-a | --remove]
35 file
36 file The map file being updated
38 -o OUT, --out OUT
40 Output file (defaults to stdout)
41 -i INPUT, --in INPUT
43 Read from this file instead of stdio
44 -d, --dry
46 Do everything, but do not modify the files
47 --verbosity {quiet,error,warning,info,debug}
49 Set the program verbosity
50 --quiet
52 Makes the program quiet
53 --debug
55 Makes the program print debug info
56 -l LOGFILE, --logfile LOGFILE:
58 Log to this file
59 -n NAME, --name NAME
61 The name of the library (e.g. libx)
62 -v VERSION, --version VERSION
64 The release version (e.g. 1_0_0 or 1.0.0)
65 -r RELEASE, --release RELEASE
67 The full name of the release to be used (e.g. LIBX_1_0_0)
68 --no_guess
70 Disable next release name guessing
71 --allow-abi-break
73 Allow removing symbols, and to break ABI
74 -f, --final
76 Mark the modified release as final, preventing later changes.
77 -a, --add
79 Adds the symbols to the map file.
80 --remove
82 Remove the symbols from the map file. This breaks the ABI.
83 abimap new
85 Create a new map file
86 abimap new [-h] [-o OUT] [-i INPUT] [-d]
88 [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
89 [-l LOGFILE] [-n NAME] [-v VERSION] [-r RELEASE]
90 [--no_guess] [-f]
91 -o OUT, --out OUT
93 Output file (defaults to stdout)
94 -i INPUT, --in INPUT
96 Read from this file instead of stdio
97 -d, --dry
99 Do everything, but do not modify the files
100 --verbosity {quiet,error,warning,info,debug}
102 Set the program verbosity
103 --quiet
105 Makes the program quiet
106 --debug
108 Makes the program print debug info
109 -l LOGFILE, --logfile LOGFILE
111 Log to this file
112 -n NAME, --name NAME
114 The name of the library (e.g. libx)
115 -v VERSION, --version VERSION
117 The release version (e.g. 1_0_0 or 1.0.0)
118 -r RELEASE, --release RELEASE
120 The full name of the release to be used (e.g. LIBX_1_0_0)
121 --no_guess
123 Disable next release name guessing
124 -f, --final
126 Mark the new release as final, preventing later changes.
127 abimap check
129 Check the syntax of a map file
130 abimap check [-h]
132 [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
133 [-l LOGFILE]
134 file
135 file The map file to be checked
137 --verbosity {quiet,error,warning,info,debug}
139 Set the program verbosity
140 --quiet
142 Makes the program quiet
143 --debug
145 Makes the program print debug info
146 -l LOGFILE, --logfile LOGFILE
148 Log to this file
149 abimap version
151 Prints the tool version number
152 usage:
154 abimap version [-h]
156
158 Why use symbol versioning?
159 The main reason is to be able to keep the library [ABI] stable.
160 If a library is intended to be used for a long time, it will need up‐
162 dates for eventual bug fixes and/or improvement. This can lead to
163 changes in the [API] and, in the worst case, changes to the [ABI].
164 Using symbol versioning, it is possible to make compatible changes and
166 keep the applications working without recompiling. If incompatible
167 changes were made (breaking the [ABI]), symbol versioning allows both
168 incompatible versions to live in the same system without conflict. And
169 even more uncommon situations, like an application to be linked to dif‐
170 ferent (incompatible) versions of the same library.
171 For more information, I strongly recommend reading:
173 • [HOW_TO] How to write shared libraries, by Ulrich Drepper
175 How to add symbol versioning to my library?
177 Adding version information to the symbols is easy. Keeping the [ABI]
178 stable, unfortunately, is not. This project intends to help in the
179 first part.
180 To add version information to symbols of a library, one can use version
182 scripts (in Linux). Version scripts are files used by linkers to map
183 symbols to a given version. It contains the symbols exported by the
184 library grouped by the releases where they were introduced. For exam‐
185 ple:
186 LIB_EXAMPLE_1_0_0
188 {
189 global:
190 symbol;
191 another_symbol;
192 local:
193 *;
194 };
195 In this example, the release LIB_EXAMPLE_1_0_0 introduces the symbols
197 symbol and another_symbol. The * wildcard in local catches all other
198 symbols, meaning only symbol and another_symbol are globally exported
199 as part of the library [API].
200 If a compatible change is made, it would introduce a new release, like:
202 LIB_EXAMPLE_1_0_0
204 {
205 global:
206 symbol;
207 another_symbol;
208 local:
209 *;
210 };
211 LIB_EXAMPLE_1_1_0
213 {
214 global:
215 new_symbol;
216 } LIB_EXAMPLE_1_0_0;
217 The new release LIB_EXAMPLE_1_1_0 introduces the symbol new_symbol.
219 The * wildcard should be only in one version, usually in the oldest
220 version. The } LIB_EXAMPLE_1_0_0; part in the end of the new release
221 means the new release depends on the old release.
222 Suppose a new incompatible version LIB_EXAMPLE_2_0_0 released after
224 LIB_EXAMPLE_1_1_0. Its map would look like:
225 LIB_EXAMPLE_2_0_0
227 {
228 global:
229 a_newer_symbol;
230 another_symbol;
231 new_symbol;
232 local:
233 *;
234 };
235 The symbol symbol was removed (and that is why it was incompatible).
237 And a new symbol was introduced, a_newer_symbol.
238 Note that all global symbols in all releases were merged in a unique
240 new release.
241 References:
243 • [ABI] https://en.wikipedia.org/wiki/Application_binary_interface
244 • [API] https://en.wikipedia.org/wiki/Application_programming_interface
246 • [HOW_TO] https://www.akkadia.org/drepper/dsohowto.pdf, How to write
248 shared libraries by Ulrich Drepper
249
251 Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
252
254 2022, Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
2550.3.2 Jul 22, 2022 ABIMAP(1)