.TH "alpm" 7

.SH "NAME"
.PP
alpm \- Arch Linux Package Management\.

.SH "DESCRIPTION"
.PP
\fBA\fPrch \fBL\fPinux \fBP\fPackage \fBM\fPanagement (ALPM), describes the process of retrieving the sources of upstream projects, optionally building them, bundling them in a dedicated package format (see \fBalpm\-package\fP) and distributing those package files to users of the \fBArch Linux\fP[1] distribution\.
.PP
The format used for the distribution of software as prebuilt binary artifacts is openly accessible and is documented on a high level in the following sections\.
Aside from \fBArch Linux\fP[1] it may find use in other distributions or on other platforms\.

.SS "Disclaimer"
.PP
Throughout this document the term "repository" or "repo" appears in different contexts:
.RS
.Bl
.IP \(bu 4
\fBalpm\-source\-repo\fP: A repository (e\.g\. a \fBgit\fP repository) containing \fBPKGBUILD\fP package build scripts, from which one or several \fBalpm\-package\fP files are built\.
Aside from the package build scripts, an \fBalpm\-source\-repo\fP may also contain a \fBSRCINFO\fP file, which provides a collection of metadata on the data defined in the \fBPKGBUILD\fP file\.
.El
.Bl
.IP \(bu 4
\fBalpm\-repo\fP: A repository (e\.g\. a directory served by a webserver) that provides \fBalpm\-package\fP files, digital signatures and \fBalpm\-repo\-db\fP files that define the state of the \fBalpm\-repo\fP\.
Each \fBalpm\-repo\-db\fP contains specific package\-related metadata (i\.e\. \fBalpm\-repo\-desc\fP and \fBalpm\-repo\-files\fP)\.
.El
.RE
.PP
Summarized, \fBalpm\-source\-repo\fP is the location from which \fBalpm\-package\fP files are built, while \fBalpm\-repo\fP is the location where those files are stored later on\.

.SS "Metadata connections"
.PP
Metadata connections between \fBalpm\-source\-repo\fP, \fBalpm\-package\fP and \fBalpm\-repo\-db\fP:
.RS
.PP
.nf
     alpm\-source\-repo
           |
        PKGBUILD
       /        \\
  SRCINFO        \\
                  \\
                   \\
         /\-\-\-\-\-\-\- alpm\-package \-\-\-\-\-\-\\
        /        /     |      \\       \\
       /   BUILDINFO   |    PKGINFO   |
       |               |       |      |
       |           ALPM\-MTREE  |      |
       |                       |      |
       |        alpm\-repo\-db   |      |
       |       /            \\  |     /
     alpm\-repo\-files   alpm\-repo\-desc
.fi
.RE
.PP
Metadata connections between \fBalpm\-package\fP and \fBalpm\-db\fP (\fBlibalpm\fP):
.RS
.PP
.nf
      /\-\-\-\-\-\-\- alpm\-package \-\-\-\-\-\-\\
     /        /     |      \\       \\
    /   BUILDINFO   |    PKGINFO   |
    |               |       |      |
    |           ALPM\-MTREE  |      |
    |                       |     /
    |        alpm\-db        |    /
    |       /        \\      |   /
  alpm\-db\-files     alpm\-db\-desc
.fi
.RE

.SS "Building from source"
.PP
Package data files, such as binary or other data artifacts, are created from an \fBalpm\-source\-repo\fP\.
This process is abstracted using dedicated package build tools such as \fBmakepkg\fP, that rely on \fBbash\fP based \fBPKGBUILD\fP package build scripts\.
.PP
Package build scripts define the environment in which packages are created and used\.
This includes their source inputs, build, run\-time and test dependencies, as well as all necessary steps for the creation of data files, their testing and installation\.
Package build scripts also provide metadata about the packages such as name, version, description, groups, source or checksums\.
Build tools automate the steps of downloading and verifying local or upstream source inputs, applying any required modifications (e\.g\. patches), calling any respective build systems, running tests and installing the resulting binary or other data artifacts to a location from which a package file is created\.
.PP
The \fBmakepkg\fP tool is able to record relevant metadata of the current system environment in a \fBBUILDINFO\fP file\.
Based on this file an identical environment can be setup again, which is a prerequisite for \fBreproducible builds\fP[2]\.
.PP
Generally, it is desirable to create an \fBalpm\-package\fP file in a secluded environment that can be setup reproducibly (e\.g\. chroots, containers, or virtual machines) and only contains the various dependencies of a package (see \fBalpm\-package\-relation\fP)\.
However, on its own \fBmakepkg\fP is not able to ensure that a build environment only contains packages that satisfy the various dependencies of a package\.
This is why Arch Linux's canonical packaging tool \fBpkgctl\fP creates clean chroot environments with the help of \fBsystemd\-nspawn\fP and executes \fBmakepkg\fP within them\.

.SB "Download, verification and authentication"
.PP
The inputs (i\.e\. the sources) of a package build script may be local or remote files or data in version control systems\.
After download, they are verified using optional locked hash digests (see \fBalpm\-package\-source\-checksum\fP) for the respective files\.
This is a fundamental building block for \fBreproducible builds\fP[2] and allows to detect \fBsupply chain attack\fP[3] vectors that rely on altering source files\.
In addition, each input may be authenticated using a cryptographic signature\.

.SB "Modification"
.PP
Package build inputs sometimes need to be modified to fix issues with the input files themselves or to accommodate to the specific behavior of the environment they are supposed to be used in\.
Applying patches is a common scenario and is usually done in a preparation step after the download, verification and authentication of the inputs\.

.SB "Building"
.PP
The next step after the potential modification of source inputs is to generate data files for the \fBalpm\-package\fP file\.
This may include compilation of binary files, translations, assets, plain data or any other type of file that might be included in a package\.
Depending on source input and programming language a diverse set of tools may be required to build binary artifacts from source code\.

.SB "Testing"
.PP
After successfully building, any available tests of the respective project are run to ensure that the given project can be integrated with the system that it has been built against\.

.SB "Installation"
.PP
Finally, any generated package data files are installed into an empty output directory, either using the project's build system or manually\.
During this step, the package build tool also creates required metadata files, such as \fBBUILDINFO\fP, \fBPKGINFO\fP and \fBALPM\-MTREE\fP\.
.PP
When creating more than one \fBalpm\-package\fP from a \fBPKGBUILD\fP, as many output directories as there are packages are created\.
For information on creating multiple packages from a single \fBPKGBUILD\fP, refer to \fBalpm\-split\-package\fP\.

.SS "Creating packages"
.PP
One \fBalpm\-package\fP file is created from each output directory after \fBbuilding from source\fP, \fBtesting\fP and \fBinstallation\fP\.
Package files are optionally compressed \fBtar\fP archives, that contain any files that have been installed into the empty output directory, an optional \fBalpm\-install\-scriptlet\fP and the ALPM specific metadata files \fBBUILDINFO\fP, \fBPKGINFO\fP and \fBALPM\-MTREE\fP\.
.PP
Once a package is created, it may be digitally signed\.
ALPM currently supports detached \fBOpenPGP signatures\fP[4] for this purpose\.
With the help of digital signatures the authenticity of a package file can later be verified using the packager's \fBOpenPGP certificate\fP[5]\.

.SS "Maintaining package repositories"
.PP
An \fBalpm\-repo\fP is a collection of unique \fBalpm\-package\fP files in specific versions and an \fBalpm\-repo\-db\fP which describes this particular state\.
Each package file is described by an \fBalpm\-repo\-desc\fP file in the \fBalpm\-repo\-db\fP\.
This file is created from a combination of the package files' \fBPKGINFO\fP data, the optional digital signature and the metadata of the package file itself\.
.PP
Package repositories are maintained with the help of dedicated tools such as \fBrepo\-add\fP\.
To serve more complex and evolved repository setups, while allowing access to a larger set of package maintainers, Arch Linux relies on \fBdbscripts\fP[6]\.

.SS "Installing packages"
.PP
ALPM based packages are installed using package management software such as \fBpacman\fP\.
While packages can be installed and upgraded individually, they are mostly used via package repositories\.
For this, the package management software downloads the \fBalpm\-repo\-db\fP file of each \fBalpm\-repo\fP it is configured to use\.
Based on their data, it can compare the state of all specified package repositories and their package files with the state of a local system\.
If newer package versions are detected in the \fBalpm\-repo\-db\fP, the package management software downloads these new package files and installs them\.
.PP
The installation of a package file implies several things:
.RS
.Bl
.IP \(bu 4
The removal of all files from the filesystem, that are provided by the previously installed package version\.
.El
.Bl
.IP \(bu 4
The addition of all files to the filesystem, that are provided by the new version of the package\.
.El
.Bl
.IP \(bu 4
The update of the system's metadata which tracks what version of a given package is currently installed\.
.El
.RE

.SH "EXAMPLES"
.PP
In the following, very basic example the life cycle of a package file and the related metadata is explored\.

.SS "Creating a package file from a source repository"
.PP
The below \fBPKGBUILD\fP in an \fBalpm\-source\-repo\fP defines a package that contains a single data file:
.RS
.PP
.nf
pkgname=example
pkgver=0\.1\.0
pkgrel=1
pkgdesc="An example package"
arch=(any)
url="https://example\.org"
license=(CC\-BY\-SA\-4\.0)

package() {
   install \-vdm 755 "$pkgdir/usr/share/$pkgname/"
   printf "Hello World\!\n" > "$pkgdir/usr/share/$pkgname/example\.txt"
}
.fi
.RE
.PP
It is represented by this \fBSRCINFO\fP file:
.RS
.PP
.nf
pkgbase = example
	pkgdesc = An example package
	pkgver = 0\.1\.0
	pkgrel = 1
	url = https://example\.org
	arch = any
	license = CC\-BY\-SA\-4\.0

pkgname = example
.fi
.RE
.PP
When building an \fBalpm\-package\fP in a clean environment from the above \fBalpm\-source\-repo\fP, a package file `\f[CR]example\-0\.1\.0\-any\.pkg\.tar\.zst\fP` is created and is accompanied by the detached OpenPGP signature `\f[CR]example\-0\.1\.0\-any\.pkg\.tar\.zst\.sig\fP`\.
The package file contains the \fBALPM\-MTREE\fP, \fBBUILDINFO\fP and \fBPKGINFO\fP metadata files, as well as a single data file and all of its parent directories\.
.PP
The \fBALPM\-MTREE\fP file may look similar to the below:
.RS
.PP
.nf
#mtree
/set type=file uid=0 gid=0 mode=644
\./\.BUILDINFO time=1752836739\.0 size=5271 sha256digest=9924a366a4ad02c31b121b22a2b285b2cae3a57873052169deb9d237936bef83
\./\.PKGINFO time=1752836739\.0 size=297 sha256digest=0c8481c16dfc09ffdb0f518f827109795c1e07816ab7205ffffa6837b92fa4fb
\./usr time=1752836739\.0 mode=755 type=dir
\./usr/share time=1752836739\.0 mode=755 type=dir
\./usr/share/example time=1752836739\.0 mode=755 type=dir
\./usr/share/example/example\.txt time=1752836739\.0 size=14 sha256digest=732c1c47a8296f4525307d28469d7ba1f3f5e4796fe55bc5625febc720a09d92
.fi
.RE
.PP
The \fBBUILDINFO\fP may look similar to the below (which is truncated for brevity):
.RS
.PP
.nf
format = 2
pkgname = example
pkgbase = example
pkgver = 0\.1\.0\-1
pkgarch = any
pkgbuild_sha256sum = c2cdacc7de9ed0cb40a9177255701339f1e53f1014950c1793bb34740bfd64e9
packager = John Doe <john@example\.org>
builddate = 1752836739
builddir = /build
startdir = /startdir
buildtool = devtools
buildtoolver = 1:1\.3\.2\-1\-any
buildenv = !distcc
buildenv = color
buildenv = !ccache
buildenv = check
buildenv = !sign
options = strip
options = docs
options = !libtool
options = !staticlibs
options = emptydirs
options = zipman
options = purge
options = debug
options = lto
installed = acl\-2\.3\.2\-1\-x86_64
installed = archlinux\-keyring\-20250716\-1\-any
.fi
.RE
.PP
The \fBPKGINFO\fP of the \fBalpm\-package\fP may look similar to the below:
.RS
.PP
.nf
pkgname = example
pkgbase = example
xdata = pkgtype=pkg
pkgver = 0\.1\.0\-1
pkgdesc = An example package
url = https://example\.org
builddate = 1752836739
packager = John Doe <john@example\.org>
size = 14
arch = any
license = CC\-BY\-SA\-4\.0
.fi
.RE

.SS "Adding a package file to a repository"
.PP
After adding `\f[CR]example\-0\.1\.0\-any\.pkg\.tar\.zst\fP` and `\f[CR]example\-0\.1\.0\-any\.pkg\.tar\.zst\.sig\fP` to an \fBalpm\-repo\fP named `\f[CR]example\-repo\fP`, its corresponding \fBalpm\-repo\-db\fP is updated\.
.PP
The dedicated \fBalpm\-repo\-desc\fP for the package may look similar to this:
.RS
.PP
.nf
%FILENAME%
example\-0\.1\.0\-1\-any\.pkg\.tar\.zst

%NAME%
example

%BASE%
example

%VERSION%
0\.1\.0\-1

%DESC%
An example package

%CSIZE%
2274

%ISIZE%
14

%SHA256SUM%
640d6a9eaebf312273371eb7589338a3f01eb623cddf9f671ee96501d7c65ae1

%PGPSIG%
iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=

%URL%
https://example\.org

%LICENSE%
CC\-BY\-SA\-4\.0

%ARCH%
any

%BUILDDATE%
1752836739

%PACKAGER%
John Doe <john@example\.org>
.fi
.RE
.PP
The \fBalpm\-repo\-files\fP for the package file contains:
.RS
.PP
.nf
%FILES%
usr/
usr/share/
usr/share/example/
usr/share/example/example\.txt
.fi
.RE

.SS "Installation on a client host"
.PP
On a client host, the package management software \fBpacman\fP is configured to use the \fBalpm\-repo\fP `\f[CR]example\-repo\fP`\.
Once its \fBalpm\-repo\-db\fP is synchronized, the system administrator of the host decides to install the `\f[CR]example\fP` package from the repository\.
After installation, the client host's \fBalpm\-db\fP is modified to contain metadata about the `\f[CR]example\fP` package\.
.PP
It contains the below \fBalpm\-db\-desc\fP file:
.RS
.PP
.nf
%NAME%
example

%VERSION%
0\.1\.0\-1

%BASE%
example

%DESC%
An example package

%URL%
https://example\.org

%ARCH%
any

%BUILDDATE%
1752836739

%INSTALLDATE%
1752836973

%PACKAGER%
John Doe <john@example\.org>

%SIZE%
14

%LICENSE%
CC\-BY\-SA\-4\.0

%VALIDATION%
pgp

%XDATA%
pkgtype=pkg
.fi
.RE
.PP
Meanwhile, the contents of the \fBalpm\-db\-files\fP file equals that of the \fBalpm\-repo\-files\fP file in the \fBalpm\-repo\-db\fP:
.RS
.PP
.nf
%FILES%
usr/
usr/share/
usr/share/example/
usr/share/example/example\.txt
.fi
.RE
.PP
The \fBALPM\-MTREE\fP file also equals that contained in the \fBalpm\-package\fP file:
.RS
.PP
.nf
#mtree
/set type=file uid=0 gid=0 mode=644
\./\.BUILDINFO time=1752836739\.0 size=5271 sha256digest=9924a366a4ad02c31b121b22a2b285b2cae3a57873052169deb9d237936bef83
\./\.PKGINFO time=1752836739\.0 size=297 sha256digest=0c8481c16dfc09ffdb0f518f827109795c1e07816ab7205ffffa6837b92fa4fb
\./usr time=1752836739\.0 mode=755 type=dir
\./usr/share time=1752836739\.0 mode=755 type=dir
\./usr/share/example time=1752836739\.0 mode=755 type=dir
\./usr/share/example/example\.txt time=1752836739\.0 size=14 sha256digest=732c1c47a8296f4525307d28469d7ba1f3f5e4796fe55bc5625febc720a09d92
.fi
.RE

.SH "SEE ALSO"
.PP
\fBbash\fP(1), \fBgit\fP(1), \fBpkgctl\fP(1), \fBsystemd\-nspawn\fP(1), \fBtar\fP(1), \fBlibalpm\fP(3), \fBALPM\-MTREE\fP(5), \fBBUILDINFO\fP(5), \fBPKGBUILD\fP(5), \fBPKGINFO\fP(5), \fBSRCINFO\fP(5), \fBalpm\-db\fP(7), \fBalpm\-db\-desc\fP(7), \fBalpm\-db\-files\fP(7), \fBalpm\-install\-scriptlet\fP(5), \fBalpm\-package\fP(7), \fBalpm\-package\-relation\fP(7), \fBalpm\-package\-source\-checksum\fP(7), \fBalpm\-repo\fP(7), \fBalpm\-repo\-db\fP(7), \fBalpm\-repo\-desc\fP(7), \fBalpm\-repo\-files\fP(7), \fBalpm\-source\-repo\fP(7), \fBalpm\-split\-package\fP(7), \fBmakepkg\fP(8), \fBpacman\fP(8), \fBrepo\-add\fP(8)

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBArch Linux\fP
.sp
https://archlinux\.org
.El
.Bl
.IP 2. 4
\fBreproducible builds\fP
.sp
https://reproducible\-builds\.org
.El
.Bl
.IP 3. 4
\fBsupply chain attack\fP
.sp
https://en\.wikipedia\.org/wiki/Supply_chain_attack
.El
.Bl
.IP 4. 4
\fBOpenPGP signatures\fP
.sp
https://openpgp\.dev/book/signing_data\.html#detached\-signatures
.El
.Bl
.IP 5. 4
\fBOpenPGP certificate\fP
.sp
https://openpgp\.dev/book/certificates\.html
.El
.Bl
.IP 6. 4
\fBdbscripts\fP
.sp
https://gitlab\.archlinux\.org/archlinux/dbscripts
.El
.RE