.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "7" ""
.SH NAME
.LP
alpm-source-repo - a repository containing sources for building one or more \fBA\fRrch \fBL\fRinux \fBP\fRackage \fBM\fRanagement (ALPM) based packages.
.SH DESCRIPTION
.LP
ALPM based packages (see \fBalpm-package\fR) are created from package sources using package build software, such as \fBmakepkg\fR.
Refer to the \fBcontents\fR section for an overview of required and optional files in an \fBalpm-source-repo\fR.
For Arch Linux specific package build software refer to \fBdevtools\fR and \fBpkgctl\fR.
.SS
Contents
.LP
Package sources are represented by a single \fBPKGBUILD\fR per \fBalpm-source-repo\fR, which may define and/or additional require files, such as an \fBalpm-install-scriptlet\fR, arbitrary custom local source files for the package build process and files for tooling (e.g. configuration files, etc.).
The \fBPKGBUILD\fR script may be accompanied by a \fBSRCINFO\fR file which represents a parseable data format exposing relevant metadata defined by the \fBPKGBUILD\fR.
.SS
Required files
.IP "\(bu" 3
\fBPKGBUILD\fR: The package build script.
.SS
Optional files
.IP "\(bu" 3
\fB.SRCINFO\fR: The data representation of the package build script metadata (see \fBSRCINFO\fR).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB.nvchecker.toml\fR: A minimal configuration file for \fBnvchecker\fR (supported by \fBpkgctl\fR) to allow detection of new upstream versions.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBLICENSES/\fR: A directory containing license files used by \fBreuse\fR (see \fBRFC 0040\fR[1] and \fBRFC 0052\fR[2]).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBREUSE.toml\fR: A configuration file for \fBreuse\fR which covers the license information of all files in the \fBalpm-source-repo\fR (see \fBRFC 0040\fR[1] and \fBRFC 0052\fR[2]).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBalpm-install-scriptlet\fR: An installation scriptlet that is added to a resulting \fBalpm-package\fR (needs to be specified in the \fBPKGBUILD\fR).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBkeys/pgp/\fR: A directory containing \fBASCII-armored\fR[3] \fBOpenPGP certificates\fR[4] that represent verifiers for \fBOpenPGP signatures\fR[5] created by upstreams for their release artifacts.
.LP
Apart from the above specific files, an \fBalpm-source-repo\fR may contain a list of arbitrary, custom source files that are used with the \fBPKGBUILD\fR when building package files with package build software.
Common examples for these files are patches, \fBsystemd.service\fR, \fBsystemd.socket\fR, \fBsysusers.d\fR, \fBtmpfiles.d\fR or other configuration files.
.SS
Version control
.LP
It is advisable to keep the contents of an \fBalpm-source-repo\fR in a version control system such as \fBgit\fR.
In doing so the relationship between a \fBPKGBUILD\fR and its resulting list of \fBalpm-package\fR files can be established, by associating a (preferably signed) git commit hash with the package.
This is important for \fBreproducible builds\fR[6].
.PP
Upstream sources and build artifacts (e.g. build logs, or package files) should not be included in the \fBgit\fR repository.
They can be ignored using a \fBgitignore\fR file.
Alternatively \fBmakepkg.conf\fR can be used to instruct the \fBmakepkg\fR package build tool to store artifacts elsewhere.
.SS
Best practices
.LP
Although a basic setup technically only requires a \fBPKGBUILD\fR file, further components are considered best practice.
.IP "\(bu" 3
\fB.SRCINFO\fR: Creating this file (see \fBSRCINFO\fR for the description of the format) and keeping it in sync with the \fBPKGBUILD\fR file allows consumers of the \fBalpm-source-repo\fR to extract metadata of the \fBPKGBUILD\fR without requiring \fBbash\fR.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB.nvchecker.toml\fR: Using \fBnvchecker\fR (e.g. through \fBpkgctl\fR) enables users to check for new releases of an upstream project.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBLICENSES/\fR and \fBREUSE.toml\fR: A \fBreuse\fR setup ensures that licensing is clearly defined for all files in the \fBalpm-source-repo\fR which enables others to use it and adapt it.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fBkeys/pgp/\fR: If the \fBPKGBUILD\fR defines an \fBalpm-package-source\fR with \fBOpenPGP signature verification\fR[7], storing current versions of relevant \fBASCII-armored\fR[3] \fBOpenPGP certificates\fR[4] allows users of the \fBalpm-source-repo\fR to authenticate the upstream artifacts using \fBOpenPGP signatures\fR[5].
.SH EXAMPLES
.LP
The following example illustrates a basic \fBalpm-source-repo\fR:
.LP
.EX
\&.
└── PKGBUILD
.EE
.PP
The following example illustrates a more complete \fBalpm-source-repo\fR with best practices applied for a package named \f(CRexample\fR:
.LP
.EX
\&.
├── .SRCINFO
├── .nvchecker.toml
├── LICENSES
│   └── 0BSD.txt
├── PKGBUILD
├── REUSE.toml
├── example.install
└── keys
    └── pgp
        └── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
.EE
.SH SEE ALSO
.LP
\fBbash\fR(1), \fBgit\fR(1), \fBnvchecker\fR(1), \fBpkgctl\fR(1), \fBreuse\fR(1), \fBPKGBUILD\fR(5), \fBSRCINFO\fR(5), \fBalpm-install-scriptlet\fR(5), \fBgitignore\fR(5), \fBmakepkg.conf\fR(5), \fBsystemd.service\fR(5), \fBsystemd.socket\fR(5), \fBsysusers.d\fR(5), \fBtmpfiles.d\fR(5), \fBalpm-package\fR(7), \fBalpm-package-source\fR(7), \fBdevtools\fR(7), \fBmakepkg\fR(8)
.SH NOTES
.IP "1." 3
\fBRFC 0040\fR
.IP
.UR https://rfc.archlinux.page/0040-license-package-sources/
.UE
.IP "2." 3
\fBRFC 0052\fR
.IP
.UR https://rfc.archlinux.page/0052-reuse/
.UE
.IP "3." 3
\fBASCII armored\fR
.IP
.UR https://openpgp.dev/book/armor.html
.UE
.IP "4." 3
\fBOpenPGP certificates\fR
.IP
.UR https://openpgp.dev/book/certificates.html
.UE
.IP "5." 3
\fBOpenPGP signatures\fR
.IP
.UR https://openpgp.dev/book/signatures.html
.UE
.IP "6." 3
\fBreproducible builds\fR
.IP
.UR https://reproducible-builds.org/
.UE
.IP "7." 3
\fBOpenPGP signature verification\fR
.IP
.UR https://openpgp.dev/book/verification.html
.UE