ABIMAP(1)

📦
version 0.4.0 · 2 versions
, in fedora 43

🦋 abimap(1) 🦋

okay bestie, welcome to the abimap(1) manual, and I need you to read the whole thing 💅

✨ NAME ✨

abimap - Generate and update linker version scripts 🌸

💖 SYNOPSIS 💖

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

🎀 DESCRIPTION 🎀

okay so abimap is a tool that generates and updates linker scripts, and those scripts slap version info onto the symbols a shared library exports ✨ it's giving organized 💅

it's meant to live inside your build process 🔥 it checks for changes in the set of exported symbols and updates the symbol version linker script to match. no more manually keeping track, slay 😭

the complete documentation lives at https://abimap.readthedocs.io 🦋

🌈 OPTIONS 🌈

  • -h, --help — shows you the available options and subcommands 💖

👑 SUBCOMMANDS 👑

🧚 abimap update

Updates an existing map file. Main character energy 💅

abimap update [-h] [-o OUT] [-i INPUT] [-d]
              [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
              [-l LOGFILE] [-n NAME] [-v VERSION]
              [-r RELEASE] [--no_guess] [--allow-abi-break]
              [-f] [-a | --remove]
              file
  • file — the map file being updated 🫶
  • -o OUT, --out OUT — where the output goes (defaults to stdout) 🍓
  • -i INPUT, --in INPUT — reads from this file instead of stdio 📄
  • -d, --dry — does everything, but won't touch the files at all 🙈
  • --verbosity {quiet,error,warning,info,debug} — sets how chatty the program is ✨
  • --quiet — makes the program quiet 🤫
  • --debug — makes the program print debug info 🔍
  • -l LOGFILE, --logfile LOGFILE — logs everything to this file 📝
  • -n NAME, --name NAME — the name of the library, like libx 🦋
  • -v VERSION, --version VERSION — the release version, like 1_0_0 or 1.0.0 💜
  • -r RELEASE, --release RELEASE — the full name of the release, like LIBX_1_0_0 👑
  • --no_guess — turns off the next release name guessing 🙅‍♀️
  • --allow-abi-break — lets you remove symbols and break the ABI. big risk, bestie 💀
  • -f, --final — marks the modified release as final, so nobody can change it later 🔒
  • -a, --add — adds the symbols to the map file ➕
  • --remove — removes the symbols from the map file. This breaks the ABI. 💀
🚨 Heads up: --remove and --allow-abi-break both break the ABI. Use them with extreme care, bestie, or your users will be sad 😭

🌸 abimap new

Creates a brand new map file ✨

abimap new [-h] [-o OUT] [-i INPUT] [-d]
           [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
           [-l LOGFILE] [-n NAME] [-v VERSION] [-r RELEASE]
           [--no_guess] [-f]
  • -o OUT, --out OUT — where the output goes (defaults to stdout) 🍓
  • -i INPUT, --in INPUT — reads from this file instead of stdio 📄
  • -d, --dry — does everything, but won't modify the files 🙈
  • --verbosity {quiet,error,warning,info,debug} — sets the program verbosity ✨
  • --quiet — makes the program quiet 🤫
  • --debug — makes the program print debug info 🔍
  • -l LOGFILE, --logfile LOGFILE — logs to this file 📝
  • -n NAME, --name NAME — the name of the library, like libx 🦋
  • -v VERSION, --version VERSION — the release version, like 1_0_0 or 1.0.0 💜
  • -r RELEASE, --release RELEASE — the full name of the release, like LIBX_1_0_0 👑
  • --no_guess — turns off the next release name guessing 🙅‍♀️
  • -f, --final — marks the new release as final, so no later changes allowed 🔒

🦋 abimap check

Checks the syntax of a map file. vibe check ✅

abimap check [-h]
             [--verbosity {quiet,error,warning,info,debug} | --quiet | --debug]
             [-l LOGFILE]
             file
  • file — the map file to be checked 🫶
  • --verbosity {quiet,error,warning,info,debug} — sets the program verbosity ✨
  • --quiet — makes the program quiet 🤫
  • --debug — makes the program print debug info 🔍
  • -l LOGFILE, --logfile LOGFILE — logs to this file 📝

💅 abimap version

Prints the tool version number. iconic behaviour, no notes 💖

usage:

abimap version [-h]

🫧 NOTES 🫧

🔮 Why use symbol versioning?

okay the main reason is to keep the library [ABI] stable 🫶

if a library is meant to be used for a long time, it's gonna need updates for bug fixes and/or improvements 🛠️ and that can lead to changes in the [API] and, in the worst case, changes to the [ABI] 😭

with symbol versioning, you can make compatible changes and keep applications working without recompiling ✨ if incompatible changes happen (breaking the [ABI]), symbol versioning lets both incompatible versions live on the same system without conflict 🙌 and even more uncommon situations are covered, like an application being linked to different (incompatible) versions of the same library 🤯

for more info, I 100% recommend reading:

  • [HOW_TO] How to write shared libraries, by Ulrich Drepper 📖

🌷 How to add symbol versioning to my library?

adding version info to the symbols is easy, bestie. keeping the [ABI] stable, unfortunately, is not 😭 this project is here to help with the first part 🦋

to add version info to a library's symbols, you can use version scripts (in Linux). version scripts are files that linkers use to map symbols to a given version. they contain the symbols exported by the library, grouped by the releases where they were introduced. for example:

   LIB_EXAMPLE_1_0_0
     {
       global:
         symbol;
         another_symbol;
       local:
         *;
     };

in this example, the release LIB_EXAMPLE_1_0_0 introduces the symbols symbol and another_symbol. the * wildcard in local catches all the other symbols, so only symbol and another_symbol are globally exported as part of the library [API] 💖

if a compatible change is made, it'd introduce a new release, like:

   LIB_EXAMPLE_1_0_0
   {
       global:
           symbol;
           another_symbol;
       local:
           *;
   };

   LIB_EXAMPLE_1_1_0
   {
       global:
           new_symbol;
   } LIB_EXAMPLE_1_0_0;

the new release LIB_EXAMPLE_1_1_0 introduces the symbol new_symbol ✨ the * wildcard should only be in one version, usually the oldest one 👑 and the } LIB_EXAMPLE_1_0_0; at the end of the new release means the new release depends on the old release 🫶

now suppose a new incompatible version, LIB_EXAMPLE_2_0_0, gets released after LIB_EXAMPLE_1_1_0. its map would look like:

   LIB_EXAMPLE_2_0_0
   {
       global:
           a_newer_symbol;
           another_symbol;
           new_symbol;
       local:
           *;
   };

the symbol symbol was removed (and that's why it was incompatible) 💀 and a new symbol, a_newer_symbol, was introduced 🌈

note that all global symbols from all releases got merged into one unique new release 🫧

📚 References:

👸 AUTHOR 👸

Anderson Toshiyuki Sasaki <ansasaki@redhat.com> 💖

2025, Anderson Toshiyuki Sasaki <ansasaki@redhat.com> 🌈

that's the whole tea, bestie 🫶 this page is for abimap version 0.4.0, last updated Sep 19, 2025, and it's giving ABIMAP(1) forever 🦋✨

📦 where this page comes from