alpm-sonamev1(7)

NAME

soname - representation and use of soname data in ALPM based packaging.

DESCRIPTION

Sonames[1] are a mechanism to ensure binary compatibility between shared objects and their consumers (i.e. other ELF[2] files). More specifically, soname[1] data is encoded in the `SONAME` field of the `dynamic section` in shared object files and usually denotes specific information on the version of the object file. ELF[2] files may dynamically link against specific versions of shared objects and declare this dependency with the help of the `NEEDED` field in their dynamic section.

Strings representing soname information can be used in alpm-package-relations of type provision and run-time dependency to allow for strict package dependency setups based on ABI compatibility.

The alpm-soname format exists in multiple versions. This document describes version 1, which is a legacy version and has been removed with the release of pacman 6.1 on 2024-03-04. For the latest specification, refer to alpm-soname.

FORMAT

The representation of soname information depends on in which ALPM file format they occur in.

File formats, that represent static package source data (i.e. PKGBUILD and SRCINFO) are distinguished from those that represent dynamic package build environment data (i.e. PKGINFO).

The SRCINFO (and by extension also the PKGBUILD) file format is used to represent static data about package sources and should therefore only refer to the basic form of alpm-sonamev1. The basic form is defined as the name of the shared object file in which soname data is encoded (e.g. `libexample.so`).

The PKGINFO file format may contain dynamic, build environment specific data. In these files soname data may be referred to using the unversioned or the explicit form (both contain information derived from the targeted shared object file).

The unversioned form is defined as the name of a shared object file, directly followed by an '=' sign, directly followed by a shared object's (unversioned) soname string, directly followed by a '-' sign, directly followed by the ELF architecture format of the shared object file (e.g. `libexample.so=libexample.so-64`). Refer to readelf for further information on how to extract relevant fields such as `SONAME` or `NEEDED` from the dynamic section of an ELF[2] file.

The explicit form is defined as the name of a shared object file, directly followed by an '=' sign, directly followed by a version string, directly followed by a '-' sign, directly followed by the ELF architecture format (e.g. `libexample.so=1-64`). The version string represents the `current` interface number of the library interface version[3] that is encoded as part of the soname by the developer of the shared object (e.g. `1` in `libexample.so.1`). Refer to readelf for further information on how to extract relevant fields such as `SONAME` or `NEEDED` from the dynamic section of an ELF[2] file.

The ELF architecture format is a number derived from the `Class` field of the ELF header of an ELF[2] file. For the 32-bit format it is `32`, for the 64-bit format it is `64`. Refer to readelf for further information on how to extract the ELF header from an ELF[2] file.

When using the name of a shared object file, this always refers to the least specific file name. If for example the following files exist on a system:

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

Then the symlink `libexample.so` is the least specific file name, while `libexample.so.1.0.0` would refer to the actual ELF[2] file.

Note: While technically possible, it is strongly discouraged to use unversioned or explicit form in PKGBUILD or SRCINFO! This is because it requires manual handling of dynamically changing soname data in the static package source file formats and those may be out of sync with the actual, explicit data derived from the build environment.

Note: Both basic and explicit forms of the alpm-sonamev1 format overlap with the alpm-package-name and composite comparison expressions as defined in the alpm-comparison format, respectively. Due to this ambiguity it is essential to use the alpm-sonamev1 forms in the respective correct file formats or ideally switch to a later version of the alpm-soname format altogether.

USAGE

A package can depend on a specific soname with the help of an alpm-package-relation of type run-time dependency, if another package provides this exact soname in their alpm-package-relation of type provision.

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 for ELF[2] files in the build environment based on the following rules:

    •   If the package that is built contains a shared object file and the name of that shared object file (i.e. the basic form) is present as an alpm-package-relation of type provision in the package's PKGBUILD file (e.g. `provides=(libexample.so)`), then relevant data from the `SONAME` field in the dynamic section of the targeted ELF[2] file is extracted.

        •   If the soname data contains a version, it is extracted together with the ELF architecture format of the file to construct the explicit form. It is added instead of the basic form to the alpm-package-relation of type provision in the PKGINFO file of the package (e.g. `provides = libexample.so=1-64`).

        •   If the soname data does not contain a version, the entire soname together with the ELF architecture format of the file is used to construct the unversioned form. It is added instead of the basic form to the alpm-package-relation of type provision in the PKGINFO file of the package (e.g. `provides = libexample.so=libexample.so-64`).

    •   If the package that is built contains an ELF[2] file that dynamically links against a shared object available in the build environment and the name of that shared object file (i.e. the basic form) is present as an alpm-package-relation of type run-time dependency in the package's PKGBUILD file (e.g. `depends=(libexample.so)`), then relevant soname data from the `NEEDED` fields in the dynamic section of the ELF[2] file is extracted for those specific shared objects.

        •   All soname data that contains a version is extracted together with the ELF architecture format of the ELF[2] file and is used to construct the explicit form. It is matched against the alpm-package-relation of type provision in the PKGINFO data of the packages available in the build environment. If one matches, the explicit form instead of the basic form is added to the alpm-package-relation of type run-time dependency in the PKGINFO file of the package that is being built (e.g. `depend = libexample.so=1-64`).

        •   All soname data that does not contain a version is extracted in its entirety, together with the ELF architecture format of the ELF[2] file and is used to construct the unversioned form. It is matched against the alpm-package-relation of type provision in the PKGINFO data of the packages available in the build environment. If one matches, the unversioned form instead of the basic form is added to the alpm-package-relation of type run-time dependency in the PKGINFO file of the package that is being built (e.g. `depend = libexample.so=1-64`).

EXAMPLES

  Providing a soname

The following example PKGBUILD for a package named `example` is used to build and install an upstream project, which provides a shared object named `libexample.so`.

    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)
    provides=(libexample.so)
    source=("https://example.org/$pkgname-$pkgver.tar.gz")
    sha256sums=(7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730)
    build() {
      make -C $pkgname-$pkgver
    }
    package() {
      make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
    }

The following SRCINFO file can be generated from the above PKGBUILD file:

    pkgbase = example
    	pkgdesc = An example library
    	pkgver = 1.0.0
    	pkgrel = 1
    	arch = x86_64
    	url = https://example.org/library.html
    	license = MIT
      depends = glibc
    	provides = libexample.so
    	source = https://example.org/example-1.0.0.tar.gz
    	sha256sums = 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
    pkgname = example

This example assumes that 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`.

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 = libexample.so=1-64
    depend = glibc

  Depending on a soname

The following 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.

In the PKGBUILD the run-time dependency on the `libexample.so` shared object is added in the `package` function instead of in the global run-time dependency declaration, while the `example` package is declared as global build dependency. This is because multiple sonames of the same name but of different ELF architecture format may exist (consider e.g. the explicit forms `libexample.so=1-32` and `libexample.so=1-64`). If `libexample.so` was exposed as global run-time dependency, a build tool may accidentally pull in the wrong package containing a `libexample.so` due to the existing structural overlap between alpm-sonamev1 and alpm-package-relation!

    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)
    makedepends=(example)
    source=("https://example.org/$pkgname-$pkgver.tar.gz")
    sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)
    build() {
      make -C $pkgname-$pkgver
    }
    package() {
      depends+=(example libexample.so)
      make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
    }

The following SRCINFO file can be generated from the above PKGBUILD file:

    pkgbase = application
        pkgdesc = An example application
        pkgver = 1.0.0
        pkgrel = 1
        arch = x86_64
        url = https://example.org/application.html
        license = MIT
        depends = glibc
        depends = example
        depends = libexample.so
        makedepends = example
        source = https://example.org/application-1.0.0.tar.gz
        sha256sums = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
    pkgname = application

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 = libexample.so=1-64

SEE ALSO

readelf(1), PKGBUILD(5), PKGINFO(5), SRCINFO(5), makepkg.conf(5), alpm-comparison(7), alpm-package-name(7), alpm-package-relation(7), makepkg(8)

NOTES

    1.  soname

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

    2.  ELF

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

    3.  library interface version

        https://www.gnu.org/software/libtool/manual/html_node/Versioning.html