.TH "alpm-package" 7

.SH "NAME"
.PP
package \- a package based on \fBA\fPrch \fBL\fPinux \fBP\fPackage \fBM\fPanagement (ALPM) concepts\.

.SH "DESCRIPTION"
.PP
ALPM based packages refer to (optionally compressed) \fBtar\fP archives that contain package files\.
Package files encompass mandatory \fBmetadata\fP files as well as optional \fBscripts\fP and \fBdata\fP files\.
.PP
Package files are created from package sources (i\.e\. \fBPKGBUILD\fP) using package build software (e\.g\. \fBmakepkg\fP)\.
For Arch Linux specific package build software refer to \fBdevtools\fP and \fBpkgctl\fP\.
.PP
Package management software (e\.g\. \fBpacman\fP) relies on \fBmetadata\fP files and \fBscripts\fP for the purpose of dependency resolution and installation\.
\fBData\fP files can be installed on compatible target systems using package management software\.

.SH "FORMAT"
.PP
\fIUncompressed\fP ALPM based package files follow the following naming scheme:
.PP
An \fBalpm\-package\-name\fP directly followed by a '\-' sign, directly followed by an \fBalpm\-package\-version\fP (in the \fIfull\fP or \fIfull with epoch\fP form), directly followed by a '\-' sign, directly followed by an \fBalpm\-architecture\fP, directly followed by the string '\.pkg\.tar', e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]example\-1\.0\.0\-1\-any\.pkg\.tar\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\fP`
.El
.RE

.SS "Compression"
.PP
ALPM based packages may optionally be compressed using a single supported compression technology\.
If a package is compressed, a technology\-specific suffix is appended to the file name:
.RS
.Bl
.IP \(bu 4
`\f[CR]\.Z\fP` for compression based on adaptive Lempel\-Ziv coding (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.Z\fP`), see the \fBcompress\fP command
.El
.Bl
.IP \(bu 4
`\f[CR]\.bz2\fP` for \fBbzip2\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.bz2\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.gz\fP` for \fBgzip\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.gz\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.lrz\fP` for \fBlrzip\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.lrz\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.lz4\fP` for \fBlz4\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.lz4\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.lz\fP` for \fBlzip\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.lz\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.lzo\fP` for \fBlzop\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.lzo\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.xz\fP` for \fBxz\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.xz\fP`)
.El
.Bl
.IP \(bu 4
`\f[CR]\.zst\fP` for \fBzstd\fP compression (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.zst\fP`)
.El
.RE
.PP
Handling of compression technologies is specific to the package build tool\.
Refer to \fBCOMPRESSBZ2\fP, \fBCOMPRESSGZ\fP, \fBCOMPRESSLRZ\fP, \fBCOMPRESSLZ\fP, \fBCOMPRESSLZ4\fP, \fBCOMPRESSLZO\fP, \fBCOMPRESSXZ\fP, \fBCOMPRESSZ\fP, \fBCOMPRESSZST\fP and \fBPKGEXT\fP in \fBmakepkg\.conf\fP for compression options and package extensions used in \fBmakepkg\fP\.

.SS "Digital signatures"
.PP
Digital signatures can be created for package files\.
.PP
Currently, only \fBOpenPGP detached signatures\fP over the package file are supported\.
Detached signatures carry the same name as the package file for which they are created, with an additional `\f[CR]\.sig\fP` suffix (e\.g\. `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.zst\.sig\fP` is the digital signature for a package file `\f[CR]example\-1\.0\.0\-1\-x86_64\.pkg\.tar\.zst\fP`)\.

.SH "CONTENTS"
.PP
The contents of an ALPM based package are distinguished between \fBmetadata\fP, \fBscripts\fP and \fBdata\fP files\.

.SS "Metadata"
.PP
The following files must be present at the root of an ALPM based package:
.RS
.Bl
.IP \(bu 4
`\f[CR]\.BUILDINFO\fP`: a \fBBUILDINFO\fP file
.El
.Bl
.IP \(bu 4
`\f[CR]\.MTREE\fP`: an \fBALPM\-MTREE\fP file
.El
.Bl
.IP \(bu 4
`\f[CR]\.PKGINFO\fP`: a \fBPKGINFO\fP file
.El
.RE
.PP
The above files provide relevant metadata for the installation, upgrade and uninstallation of packages on a target system (see \fBalpm\-package\-relation\fP for details on dependency resolution), as well as reproducibly building a bit\-by\-bit identical package from the same sources (see \fBreproducible builds\fP[2])\.

.SS "Scripts"
.PP
Optionally, an \fBalpm\-install\-scriptlet\fP named `\f[CR]\.INSTALL\fP` may be present at the root of an ALPM based package\.

.SS "Data"
.PP
Zero or more \fBdata\fP files may be present in an ALPM based package (refer to \fBalpm\-meta\-package\fP for details on why packages may not contain any \fBdata\fP files)\.
.PP
All existing \fBdata\fP files of a package are extracted to the \fBroot directory\fP[3] of a target system upon installation of the package\.
.PP
No specific rules exist on which \fBdata\fP files (and directories) are allowed as contents of a package, but it is advisable to adhere to common standards such as the \fBsystemd File Hierarchy Requirements\fP[4] and/or the \fBFilesystem Hierarchy Standard\fP[5] and by default have all files and directories be owned by `\f[CR]root\fP`\.
In conclusion, it is best practice to never package files in directories that contain user data (e\.g\. below `\f[CR]/home\fP`)\.
.PP
More specific guidelines around the validation of \fBdata\fP files in packages are subject to the implementer's discretion (e\.g\. a distribution using ALPM)\.

.SH "EXAMPLES"
.PP
The following example \fBPKGBUILD\fP defines the package `\f[CR]example\fP` which only creates a single \fBdata\fP file (plus the directories in which it is located):
.RS
.PP
.nf
pkgname=example
pkgver=1\.0\.0
pkgrel=1
pkgdesc="A simple package example"
arch=(any)
url="https://example\.org"
license=(GPL\-3\.0\-or\-later)

package() {
  install \-vdm 755 "$pkgdir/usr/share/$pkgname/"
  echo "data" > "$pkgdir/usr/share/$pkgname/data\.txt"
}
.fi
.RE
.PP
Assuming \fBmakepkg\fP is used to build a package from above \fBPKGBUILD\fP and is configured to use \fBzstd\fP for compression, the resulting package file is called `\f[CR]example\-1\.0\.0\-1\-any\.pkg\.tar\.zst\fP`\.
.PP
The package file contents can be examined as follows:
.RS
.PP
.nf
$ tar \-tf example\-1\.0\.0\-1\-any\.pkg\.tar\.zst
\.BUILDINFO
\.MTREE
\.PKGINFO
usr/
usr/share/
usr/share/example/
usr/share/example/data\.txt
.fi
.RE

.SH "SEE ALSO"
.PP
\fBbzip2\fP(1), \fBcompress\fP(1), \fBgzip\fP(1), \fBlrzip\fP(1), \fBlz4\fP(1), \fBlzip\fP(1), \fBlzop\fP(1), \fBpkgctl\fP(1), \fBtar\fP(1), \fBxz\fP(1), \fBzstd\fP(1), \fBALPM\-MTREE\fP(5), \fBBUILDINFO\fP(5), \fBPKGBUILD\fP(5), \fBPKGINFO\fP(5), \fBmakepkg\.conf\fP(5), \fBSRCINFO\fP(7), \fBalpm\-architecture\fP(7), \fBalpm\-install\-scriptlet\fP(7), \fBalpm\-meta\-package\fP(7), \fBalpm\-package\-name\fP(7), \fBalpm\-package\-relation\fP(7), \fBalpm\-package\-version\fP(7), \fBalpm\-split\-package\fP(7), \fBdevtools\fP(7), \fBmakepkg\fP(8), \fBpacman\fP(8)

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBOpenPGP detached signatures\fP
.sp
https://openpgp\.dev/book/signing_data\.html#detached\-signatures
.El
.Bl
.IP 2. 4
\fBreproducible builds\fP
.sp
https://reproducible\-builds\.org/
.El
.Bl
.IP 3. 4
\fBroot directory\fP
.sp
https://en\.wikipedia\.org/wiki/Root_directory
.El
.Bl
.IP 4. 4
\fBsystemd File Hierarchy Requirements\fP
.sp
https://systemd\.io/SYSTEMD_FILE_HIERARCHY_REQUIREMENTS/
.El
.Bl
.IP 5. 4
\fBFilesystem Hierarchy Standard\fP
.sp
https://en\.wikipedia\.org/wiki/Filesystem_Hierarchy_Standard
.El
.RE