1ABIMAP(1)                           abimap                           ABIMAP(1)
2
3
4

NAME

6       abimap - Generate and update linker version scripts
7

SYNOPSIS

9       abimap [-h] {update,new,check,version} ...
10

DESCRIPTION

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
15       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
19       The     complete      documentation      can      be      found      at
20       https://abimap.readthedocs.io
21

OPTIONS

23       -h,--help:
24              Print the available options and subcommands
25

SUBCOMMANDS

27   abimap update
28          Update an existing map file
29
30              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
37          file   The map file being updated
38
39          -o OUT, --out OUT
40                 Output file (defaults to stdout)
41
42          -i INPUT, --in INPUT
43                 Read from this file instead of stdio
44
45          -d, --dry
46                 Do everything, but do not modify the files
47
48          --verbosity {quiet,error,warning,info,debug}
49                 Set the program verbosity
50
51          --quiet
52                 Makes the program quiet
53
54          --debug
55                 Makes the program print debug info
56
57          -l LOGFILE, --logfile LOGFILE:
58                 Log to this file
59
60          -n NAME, --name NAME
61                 The name of the library (e.g. libx)
62
63          -v VERSION, --version VERSION
64                 The release version (e.g. 1_0_0 or 1.0.0)
65
66          -r RELEASE, --release RELEASE
67                 The full name of the release to be used (e.g. LIBX_1_0_0)
68
69          --no_guess
70                 Disable next release name guessing
71
72          --allow-abi-break
73                 Allow removing symbols, and to break ABI
74
75          -f, --final
76                 Mark the modified release as final, preventing later changes.
77
78          -a, --add
79                 Adds the symbols to the map file.
80
81          --remove
82                 Remove the symbols from the map file. This breaks the ABI.
83
84   abimap new
85          Create a new map file
86
87              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
92          -o OUT, --out OUT
93                 Output file (defaults to stdout)
94
95          -i INPUT, --in INPUT
96                 Read from this file instead of stdio
97
98          -d, --dry
99                 Do everything, but do not modify the files
100
101          --verbosity {quiet,error,warning,info,debug}
102                 Set the program verbosity
103
104          --quiet
105                 Makes the program quiet
106
107          --debug
108                 Makes the program print debug info
109
110          -l LOGFILE, --logfile LOGFILE
111                 Log to this file
112
113          -n NAME, --name NAME
114                 The name of the library (e.g. libx)
115
116          -v VERSION, --version VERSION
117                 The release version (e.g. 1_0_0 or 1.0.0)
118
119          -r RELEASE, --release RELEASE
120                 The full name of the release to be used (e.g. LIBX_1_0_0)
121
122          --no_guess
123                 Disable next release name guessing
124
125          -f, --final
126                 Mark the new release as final, preventing later changes.
127
128   abimap check
129          Check the syntax of a map file
130
131              abimap check [-h]
132                           [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
133                           [-l LOGFILE]
134                           file
135
136          file   The map file to be checked
137
138          --verbosity {quiet,error,warning,info,debug}
139                 Set the program verbosity
140
141          --quiet
142                 Makes the program quiet
143
144          --debug
145                 Makes the program print debug info
146
147          -l LOGFILE, --logfile LOGFILE
148                 Log to this file
149
150   abimap version
151          Prints the tool version number
152
153          usage:
154
155              abimap version [-h]
156

NOTES

158   Why use symbol versioning?
159       The main reason is to be able to keep the library [ABI] stable.
160
161       If  a  library  is  intended  to  be used for a long time, it will need
162       updates 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
165       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
172       For more information, I strongly recommend reading:
173
174       · [HOW_TO] How to write shared libraries, by Ulrich Drepper
175
176   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
181       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
187          LIB_EXAMPLE_1_0_0
188            {
189              global:
190                symbol;
191                another_symbol;
192              local:
193                *;
194            };
195
196       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
201       If a compatible change is made, it would introduce a new release, like:
202
203          LIB_EXAMPLE_1_0_0
204          {
205              global:
206                  symbol;
207                  another_symbol;
208              local:
209                  *;
210          };
211
212          LIB_EXAMPLE_1_1_0
213          {
214              global:
215                  new_symbol;
216          } LIB_EXAMPLE_1_0_0;
217
218       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
223       Suppose a new incompatible  version  LIB_EXAMPLE_2_0_0  released  after
224       LIB_EXAMPLE_1_1_0. Its map would look like:
225
226          LIB_EXAMPLE_2_0_0
227          {
228              global:
229                  a_newer_symbol;
230                  another_symbol;
231                  new_symbol;
232              local:
233                  *;
234          };
235
236       The  symbol  symbol  was removed (and that is why it was incompatible).
237       And a new symbol was introduced, a_newer_symbol.
238
239       Note that all global symbols in all releases were merged  in  a  unique
240       new release.
241
242   References:
243       · [ABI] https://en.wikipedia.org/wiki/Application_binary_interface
244
245       · [API] https://en.wikipedia.org/wiki/Application_programming_interface
246
247       · [HOW_TO]  https://www.akkadia.org/drepper/dsohowto.pdf,  How to write
248         shared libraries by Ulrich Drepper
249

AUTHOR

251       Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
252
254       2020, Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
255
256
257
258
2590.3.2                            Jul 28, 2020                        ABIMAP(1)
Impressum