ALPM-SONAMEV2(7)

📦 version 0.13.0, in arch rolling

💅 NAME

okay so this is soname — the whole tea on how soname data is represented and used in ALPM-based packaging. that's it, that's the page. section 7 of the Miscellaneous Information Manual, bestie, you're in the right place 🫶

🌸 DESCRIPTION

Sonames[1] are literally a mechanism to guarantee binary compatibility between shared objects and the things that consume them (i.e. other ELF[2] files). no cap. more specifically, soname[1] data is encoded in the SONAME field of the dynamic section in shared object files, and it usually carries specific info about the version of the object file. meanwhile ELF[2] files may dynamically link against specific versions of shared objects and declare that dependency using the NEEDED field in their dynamic section. it's giving mutual commitment ✨

Strings that represent soname info can be used in alpm-package-relations of type provision and run-time dependency — that's how you get strict package dependency setups based on ABI compatibility. iconic behavior honestly.

the alpm-soname format exists in multiple versions. all the info in this doc is for version 2, which is the current version, supersedes alpm-sonamev1, and was introduced with the release of pacman 6.1.0 on 2024-03-04. periodt 🗓️

✨ FORMAT

so the representation of soname info exclusively takes place in file formats that may contain dynamic, build-environment-specific data — think PKGINFO and friends.

in those files, soname data is referred to using the following format, made up of data derived from the location of a shared object file plus information encoded inside it: a prefix string, directly followed by a ':', directly followed by a soname (e.g. lib:libexample.so.1). that's the whole shape of it 🎀

here, the prefix string lib denotes the use name (arbitrarily defined on a distribution level, and used by package build tools such as makepkg) for a lookup directory (e.g. /usr/lib) in which the shared object file is found. for how prefix assignments actually work in makepkg, go look at LIB_DIRS in makepkg.conf.

the soname itself represents data found in the dynamic section of a shared object file (see readelf for details). and depending on whether the soname data is used in an alpm-package-relation of type provision or of type run-time dependency, it refers to the SONAME or the NEEDED field in the dynamic section respectively. slay, one field each 🦋

🦋 USAGE

a package can depend on a specific soname using an alpm-package-relation of type run-time dependency — but only if another package provides that exact soname in their alpm-package-relation of type provision. it's a two-way street, iykyk 💅

more specifically: a soname dependency of one package is based on the soname data of a shared object file provided by one of its dependency packages.

a package build tool (e.g. makepkg) automatically derives soname information from ELF[2] files in the build environment, based on these rules:

  • If the package being built provides a shared object in one of the configured lookup directories, the value of the SONAME field in the dynamic section of the ELF[2] file is extracted. together with the prefix assigned to that lookup directory, this data is added as a provision to the PKGINFO data for the package (e.g. provides = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib). 🫶
  • If the package being built produces an ELF[2] file that dynamically links against a shared object available in the build environment, the value of the NEEDED field in the dynamic section of the ELF[2] file that is linked against is extracted. if a package containing the shared object file that encodes the soname data is present in the build environment, and that package's PKGINFO data exposes this fact in an alpm-package-relation of type provision (i.e. provides = lib:libexample.so.1), then this data is made use of. together with the prefix assigned to the given lookup directory of the shared object file that provides the needed soname, this data is added as a run-time dependency to the PKGINFO data for the package being built (e.g. depend = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib). 🔥
for implementers: it is strongly suggested that you make this behavior configurable, because soname detection may fail, or may rely on soname data that may not be advisable under certain conditions. see OPTIONS of makepkg.conf for the deets on the autodeps feature, and LIB_DIRS of makepkg.conf for the deets on prefix and lookup directory definitions for makepkg. bestie, please make it configurable, i'm begging 🙈

🎀 EXAMPLES

these examples show how to expose and use soname information in ALPM-based packaging. let's go 💖

the examples assume you're building with makepkg with the autodeps feature enabled. also, the LIB_DIRS array in makepkg.conf is expected to prefix the lookup directory /usr/lib with lib. that's the setup, keep up 🌈

💖 Providing a soname

this example PKGBUILD for a package named example is used to build and install an upstream project that contains a shared object:

pkgname=example
pkgver=1.0.0
pkgrel=1
pkgdesc="An example library"
arch=(x86_64)
url="https://example.org/library.html"
license=(MIT)
depends=(glibc)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

this example assumes the project results in installing the following files to the filesystem:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

here, the file /usr/lib/libexample.so.1.0.0 encodes the soname libexample.so.1. also, this example assumes the directory /usr/lib is assigned to the prefix lib. cute 🎀

after building from source, the resulting package file for example contains the following PKGINFO file:

pkgname = example
pkgver = 1.0.0-1
pkgdesc = An example library
url = https://example.org/library.html
builddate = 1729181726
packager = Your Name <your.name@example.org>
size = 181849963
arch = x86_64
license = MIT
provides = lib:libexample.so.1
depend = glibc

look at that provides = lib:libexample.so.1 line. we love to see it 💅

💜 Depending on a soname

this PKGBUILD for a package named application is used to build an upstream project that depends on the example package from the previous example. more specifically, the resulting package depends on the shared object libexample.so, which is provided by the example package:

pkgname=application
pkgver=1.0.0
pkgrel=1
pkgdesc="An example application"
arch=(x86_64)
url="https://example.org/application.html"
license=(MIT)
depends=(
  glibc
  example
)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

after building from source, the resulting package file for application contains the following PKGINFO file:

pkgname = application
pkgver = 1.0.0-1
pkgdesc = An example application
url = https://example.org/application.html
builddate = 1729181726
packager = Your Name <your@email.com>
size = 181849963
arch = x86_64
license = MIT
depend = glibc
depend = example
depend = lib:libexample.so.1

see that last line? auto-derived, no manual labor, we stan 😭🔥

👑 SEE ALSO

go read them, they're all besties with this page 🫶

📝 NOTES

  1. soname

https://en.wikipedia.org/wiki/Soname

  1. ELF

https://en.wikipedia.org/wiki/Executable_and_Linkable_Format

and that's the page, bestie 💖 this was (7) from the Miscellaneous Information Manual — mwah, go build something with a slay soname ✨🎀

📦 where this page comes from