.TH "alpm-soname" 7

.SH "NAME"
.PP
soname \- representation and use of soname data in ALPM based packaging\.

.SH "DESCRIPTION"
.PP
\fBSonames\fP[1] are a mechanism to ensure binary compatibility between \fIshared objects\fP and their consumers (i\.e\. other \fBELF\fP[2] files)\.
More specifically, \fBsoname\fP[1] data is encoded in the `\f[CR]SONAME\fP` field of the `\f[CR]dynamic section\fP` in \fIshared object\fP files and usually denotes specific information on the version of the object file\.
\fBELF\fP[2] files may dynamically link against specific versions of \fIshared objects\fP and declare this dependency with the help of the `\f[CR]NEEDED\fP` field in their \fIdynamic section\fP\.
.PP
Strings representing \fBsoname\fP information can be used in \fBalpm\-package\-relations\fP of type \fBprovision\fP and \fBrun\-time dependency\fP to allow for strict package dependency setups based on ABI compatibility\.
.PP
The \fBalpm\-soname\fP format exists in multiple versions\.
The information in this document is for version 2, which is the current version, supersedes \fBalpm\-sonamev1\fP and has been introduced with the release of pacman 6\.1\.0 on 2024\-03\-04\.

.SH "FORMAT"
.PP
The representation of \fBsoname\fP information exclusively takes place in file formats that may contain dynamic, build environment specific data, such as \fBPKGINFO\fP\.
.PP
In these files \fBsoname\fP data is referred to using the the following format, consisting of data derived from the location of a \fIshared object\fP file, as well as information encoded in it:
A \fIprefix\fP string, directly followed by a ':', directly followed by a \fBsoname\fP (e\.g\. `\f[CR]lib:libexample\.so\.1\fP`)\.
.PP
Here, the \fIprefix\fP string `\f[CR]lib\fP` denotes the use name (arbitrarily defined on a distribution level and used by package build tools such as \fBmakepkg\fP) for a lookup directory (e\.g\. `\f[CR]/usr/lib\fP`) in which the \fIshared object\fP file is found\.
Refer to \fBLIB_DIRS\fP in \fBmakepkg\.conf\fP for how \fIprefix\fP assignments work in \fBmakepkg\fP\.
.PP
The \fBsoname\fP represents data found in the \fIdynamic section\fP of a \fIshared object\fP file (see \fBreadelf\fP for details)\.
Depending on whether the \fBsoname\fP data is used in an \fBalpm\-package\-relation\fP of type \fBprovision\fP or of type \fBrun\-time dependency\fP this refers to the `\f[CR]SONAME\fP` or the `\f[CR]NEEDED\fP` field in the \fIdynamic section\fP, respectively\.

.SH "USAGE"
.PP
A package can depend on a specific \fBsoname\fP with the help of an \fBalpm\-package\-relation\fP of type \fBrun\-time dependency\fP, if another package provides this exact \fBsoname\fP in their \fBalpm\-package\-relation\fP of type \fBprovision\fP\.
.PP
More specifically, a \fBsoname\fP dependency of one package is based on the \fBsoname\fP data of a \fIshared object\fP file provided by one of its dependency packages\.
.PP
A package build tool (e\.g\. \fBmakepkg\fP) automatically derives \fBsoname\fP information from \fBELF\fP[2] files in the build environment based on the following rules:
.RS
.Bl
.IP \(bu 4
If the package that is built provides a \fIshared object\fP in one of the configured \fIlookup directories\fP, the value of the `\f[CR]SONAME\fP` field in the \fIdynamic section\fP of the \fBELF\fP[2] file is extracted\.
Together with the \fIprefix\fP assigned to the given \fIlookup directory\fP this data is added as a \fBprovision\fP to the \fBPKGINFO\fP data for the package (e\.g\. `\f[CR]provides = lib:libexample\.so\.1\fP`, if the \fIprefix\fP for `\f[CR]/usr/lib\fP` is `\f[CR]lib\fP` and the \fIshared object\fP file encoding the \fBsoname\fP `\f[CR]libexample\.so\.1\fP` is present in `\f[CR]/usr/lib\fP`)\.
.El
.Bl
.IP \(bu 4
If the package that is built produces an \fBELF\fP[2] file that dynamically links against a \fIshared object\fP available in the build environment, the value of the `\f[CR]NEEDED\fP` field in the \fIdynamic section\fP of the \fBELF\fP[2] file that is linked against is extracted\.
If a package containing the \fIshared object\fP file that encodes the \fBsoname\fP data is present in the build environment and the package's \fBPKGINFO\fP data exposes this fact in an \fBalpm\-package\-relation\fP of type \fBprovision\fP (i\.e\. `\f[CR]provides = lib:libexample\.so\.1\fP`), this data is made use of\.
Together with the \fIprefix\fP assigned to the given \fIlookup directory\fP of the \fIshared object\fP file that provides the needed \fBsoname\fP, this data is added as a \fBrun\-time dependency\fP to the \fBPKGINFO\fP data for the package being built (e\.g\. `\f[CR]depend = lib:libexample\.so\.1\fP`, if the \fIprefix\fP for `\f[CR]/usr/lib\fP` is `\f[CR]lib\fP` and the \fIshared object\fP file encoding the \fBsoname\fP `\f[CR]libexample\.so\.1\fP` is present in `\f[CR]/usr/lib\fP`)\.
.El
.RE
.PP
For implementers it is strongly suggested to make this behavior configurable, as \fBsoname\fP detection may fail or rely on \fBsoname\fP data that may not be advisable under certain conditions\.
See \fBOPTIONS\fP of \fBmakepkg\.conf\fP for details on the `\f[CR]autodeps\fP` feature and \fBLIB_DIRS\fP of \fBmakepkg\.conf\fP for details on \fIprefix\fP and \fIlookup directory\fP definitions for \fBmakepkg\fP\.

.SH "EXAMPLES"
.PP
The following examples demonstrate how to expose and use \fBsoname\fP information in ALPM\-based packaging\.
.PP
The examples assume building with \fBmakepkg\fP with the \fIautodeps\fP feature enabled\.
Further, the \fBLIB_DIRS\fP array in \fBmakepkg\.conf\fP is expected to \fIprefix\fP the \fIlookup directory\fP `\f[CR]/usr/lib\fP` with `\f[CR]lib\fP`\.

.SS "Providing a soname"
.PP
The following example \fBPKGBUILD\fP for a package named `\f[CR]example\fP` is used to build and install an upstream project that contains a shared object\.
.RS
.PP
.nf
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
}
.fi
.RE
.PP
This example assumes that the project results in installing the following files to the filesystem:
.RS
.PP
.nf
/usr/lib/libexample\.so \-> libexample\.so\.1
/usr/lib/libexample\.so\.1 \-> libexample\.so\.1\.0\.0
/usr/lib/libexample\.so\.1\.0\.0
.fi
.RE
.PP
Here, the file `\f[CR]/usr/lib/libexample\.so\.1\.0\.0\fP` encodes the \fBsoname\fP `\f[CR]libexample\.so\.1\fP`\.
Further, this examples assumes that the \fIdirectory\fP `\f[CR]/usr/lib\fP` is assigned to the \fIprefix\fP `\f[CR]lib\fP`\.
.PP
After building from source, the resulting package file for `\f[CR]example\fP` contains the following \fBPKGINFO\fP file:
.RS
.PP
.nf
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
.fi
.RE

.SS "Depending on a soname"
.PP
The following \fBPKGBUILD\fP for a package named `\f[CR]application\fP` is used to build an upstream project that depends on the `\f[CR]example\fP` package from the previous example\.
More specifically, the resulting package depends on the shared object `\f[CR]libexample\.so\fP` which is provided by the `\f[CR]example\fP` package\.
.RS
.PP
.nf
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)
depends=(example)
source=("https://example\.org/$pkgname\-$pkgver\.tar\.gz")
sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)

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

package() {
  make DESTDIR="$pkgdir" install \-C $pkgname\-$pkgver
}
.fi
.RE
.PP
After building from source, the resulting package file for `\f[CR]application\fP` contains the following \fBPKGINFO\fP file:
.RS
.PP
.nf
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
.fi
.RE

.SH "SEE ALSO"
.PP
\fBreadelf\fP(1), \fBPKGBUILD\fP(5), \fBPKGINFO\fP(5), \fBmakepkg\.conf\fP(5), \fBalpm\-sonamev1\fP(7), \fBalpm\-package\-relation\fP(7), \fBmakepkg\fP(8)

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBsoname\fP
.sp
https://en\.wikipedia\.org/wiki/Soname
.El
.Bl
.IP 2. 4
\fBELF\fP
.sp
https://en\.wikipedia\.org/wiki/Executable_and_Linkable_Format
.El
.RE