.TH "alpm-package-source" 7

.SH "NAME"
.PP
package source \- local or remote source data used for building an ALPM based package\.

.SH "DESCRIPTION"
.PP
ALPM based packages may be built using zero or more local and/or remote sources\.
Generally, package sources are architecture\-independent, but may be specified in an architecture\-specific way\.
.PP
In \fBPKGBUILD\fP files a package source is defined by adding an entry to the \fBsource\fP array\.
Alternatively, an array named \fBsource\fP, directly followed by an underscore character ("_"), directly followed by an \fBalpm\-architecture\fP (all except `\f[CR]any\fP`) \- may be used to define a source for a specific architecture (e\.g\. `\f[CR]source_aarch64\fP`)\.
.PP
In \fBSRCINFO\fP files a package source is defined by assigning a value to the \fBsource\fP keyword\.
Alternatively, an architecture specific keyword named \fBsource\fP, directly followed by an underscore character ("_"), directly followed by an \fBalpm\-architecture\fP (all except `\f[CR]any\fP`) may be used (e\.g\. `\f[CR]source_aarch64\fP`)\.

.SS "Local"
.PP
Local sources are defined using relative file paths (e\.g\. `\f[CR]my\-file\.txt\fP`)\.
.PP
When not specifying a \fIhost\fP while using the \fBfile URI scheme\fP it is possible to make use of files in absolute file paths on the current host (e\.g\. `\f[CR]file:///etc/passwd\fP`)\.
However, this is strongly discouraged, because with this method source files used for packaging may change in arbitrary ways\.
When packaging, it is instead advisable to rely on relative file paths of files from the same location as a \fBPKGBUILD\fP\.
This way all local source files can be tracked in a Version Control System (VCS)\.

.SS "Remote"
.PP
Remote sources may be retrieved using various protocols, all of which are defined using valid \fBURL\fP [2] strings (e\.g\. `\f[CR]https://example\.com/project\-1\.0\.0\.tar\.gz\fP`)\.
Aside from protocols for static remote sources (e\.g\. `\f[CR]https\fP`), several VCS protocols such as `\f[CR]bzr\fP`, `\f[CR]fossil\fP`, `\f[CR]git\fP`, `\f[CR]hg\fP` and `\f[CR]svn\fP` are understood and can be used to retrieve specific versions of remote sources\.
.PP
By default, the name of the remote object defines the final local source name (e\.g\. `\f[CR]https://example\.com/project\-1\.0\.0\.tar\.gz\fP` resolves to `\f[CR]project\-1\.0\.0\.tar\.gz\fP` and `\f[CR]git+https://example\.org/repo#tag=1\.0\.0\fP` to `\f[CR]repo/\fP` \- see \fBrenaming\fP for details)\.
.PP
The VCS protocols expose differing optional functionalities for retrieving specific remote content\.
This functionality is accessed using URL fragments in the source URL\.

.SB "bzr"
.PP
Using bzr it is possible to rely on revision identifiers (see `\f[CR]bzr help revisionspec\fP`) using the `\f[CR]revision\fP` URL fragment, e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]bzr+https://example\.org/trunk#revision=123\fP`
.El
.RE

.SB "fossil"
.PP
Using fossil it is possible to rely on branch, commit and tag identifiers using the `\f[CR]branch\fP`, `\f[CR]commit\fP` and `\f[CR]tag\fP` URL fragments, respectively, e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]fossil+https://example\.org/repo#branch=my\-branch\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]fossil+https://example\.org/repo#commit=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]fossil+https://example\.org/repo#tag=1\.0\.0\fP`
.El
.RE

.SB "git"
.PP
Using git it is possible to rely on branch, commit and tag identifiers using the `\f[CR]branch\fP`, `\f[CR]commit\fP` and `\f[CR]tag\fP` URL fragments, respectively, e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]git+https://example\.org/repo#branch=my\-branch\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]git+https://example\.org/repo#commit=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]git+https://example\.org/repo#tag=1\.0\.0\fP`
.El
.RE

.SB "hg"
.PP
Using hg it is possible to rely on branch, revision and tag identifiers using the `\f[CR]branch\fP`, `\f[CR]revision\fP` and `\f[CR]tag\fP` URL fragments, respectively, e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]hg+https://example\.org/repo#branch=my\-branch\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]git+https://example\.org/repo#revision=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15\fP`
.El
.Bl
.IP \(bu 4
`\f[CR]git+https://example\.org/repo#tag=1\.0\.0\fP`
.El
.RE

.SB "svn"
.PP
Using svn it is possible to rely on the revision identifier using the `\f[CR]revision\fP` URL fragment, e\.g\.:
.RS
.Bl
.IP \(bu 4
`\f[CR]svn+https://example\.org/repo#revision=r123\fP`
.El
.RE

.SS "Signature verification"
.PP
\fBOpenPGP signature verification\fP [3] is supported when using certain types of package sources\.
For package build software, that relies on a \fBPKGBUILD\fP file, to be able to verify a signature based on an \fBOpenPGP certificate\fP, there must be at least one entry in its \fBvalidpgpkeys\fP array\.
Analogous, if a software relies on a \fBSRCINFO\fP file, it must have at least one \fBvalidpgpkeys\fP keyword assignment present for \fBsignature verification\fP to be possible\.
In both cases, \fBOpenPGP signature verification\fP [3] is attempted based on \fBOpenPGP certificates\fP [4] that match the \fBOpenPGP fingerprints\fP [5] exposed in \fBvalidpgpkeys\fP\.
.PP
A pair of \fBlocal\fP or static \fBremote\fP sources, that define a file and an accompanying detached signature file (e\.g\. `\f[CR]example\-1\.0\.0\.tar\.gz\fP` with `\f[CR]example\-1\.0\.0\.tar\.gz\.sig\fP`, or `\f[CR]example\-1\.0\.0\.tar\.gz\fP` with `\f[CR]example\-1\.0\.0\.tar\.gz\.asc\fP`, or `\f[CR]example\-1\.0\.0\.tar\.gz\fP` with `\f[CR]example\-1\.0\.0\.tar\.sign\fP`) are an indication for the need of an \fBOpenPGP signature verification\fP\.
.PP
If OpenPGP signatures are available in a \fBgit\fP based \fBremote\fP source, the (optional) need for \fBOpenPGP signature verification\fP [3] of git objects can be indicated using the `\f[CR]signed\fP` \fBURL\fP query component (e\.g\. `\f[CR]git+https://example\.org/repo?signed#tag=1\.0\.0\fP` for verifying a specific git tag, or `\f[CR]git+https://example\.org/repo?signed#commit=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15\fP` for verifying a specific commit)\.
.PP
If \fBOpenPGP signature verification\fP [2] is requested, the process that verifies the \fBpackage source\fP must fail, if
.RS
.Bl
.IP \(bu 4
one or more OpenPGP certificate matching a fingerprint in \fBvalidpgpkeys\fP is not available,
.El
.Bl
.IP \(bu 4
the OpenPGP certificate used for the verification of the \fBpackage source\fP is revoked at signature creation time,
.El
.Bl
.IP \(bu 4
the OpenPGP certificate used for the verification of the \fBpackage source\fP is expired at signature creation time,
.El
.Bl
.IP \(bu 4
or the \fBpackage source\fP can not be verified with any of the OpenPGP certificates pinned by fingerprint in \fBvalidpgpkeys\fP\.
.El
.RE

.SS "Renaming"
.PP
In \fBPKGBUILD\fP and \fBSRCINFO\fP files, remote sources can be renamed\.
Using a \fItarget name\fP, directly followed by '::', directly followed by the \fIremote source name\fP (e\.g\. `\f[CR]source\-1\.0\.0\.tar\.gz::https://example\.com/1\.0\.0\.tar\.gz\fP` or `\f[CR]project::git+https://git\.example\.com/project\.git\fP`)\.
.PP
The renaming functionality differs between static protocols (e\.g\. `\f[CR]https\fP`) and VCS protocols (e\.g\. `\f[CR]git\fP`):
In the former case the \fItarget name\fP is a file and in the latter a directory (e\.g\. `\f[CR]project\-1\.0\.0\.tar\.gz::https://example\.org/project\-v1\.0\.0\.tar\.gz\fP` renames to the file `\f[CR]project\-1\.0\.0\.tar\.gz\fP` while `\f[CR]other\-name::git+https://example\.org/repo#tag=v1\.0\.0\fP` renames to the directory `\f[CR]other\-name/\fP`)\.

.SS "Extraction"
.PP
By default, local and remote sources are automatically extracted by package build software such as \fBmakepkg\fP, if (after \fBrenaming\fP) the final source file name ending matches a known extension (e\.g\. `\f[CR]\.tar\.gz\fP`)\.
.PP
In \fBPKGBUILD\fP files a final source file name from the \fBsource\fP array can be added to the \fBnoextract\fP array to indicate that the automatic extraction should be prevented for the given file\.
.PP
In \fBSRCINFO\fP files a final source file name can be defined using the \fBnoextract\fP keyword to indicate, that the automatic extraction should be prevented for the given file\.

.SH "EXAMPLES"

.SS "Local and static remote sources with renaming"
.RS
.PP
.nf
pkgname=example
pkgver=0\.1\.0
pkgrel=1
pkgdesc="A package example"
arch=(x86_64)
url="https://example\.org"
license=(GPL\-3\.0\-or\-later)
makedepends=(meson)
depends=(
  gcc\-libs
  glibc
)
noextract=(custom\-data\.tar\.gz)
source=(
  test\.service
  custom\-data\.tar\.gz{,\.sig}
  $pkgname\-$pkgver\.tar\.gz::https://download\.example\.org/$pkgname\-v$pkgver\.tar\.gz
)
sha256sums=(
  b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
  7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
  bf07a7fbb825fc0aae7bf4a1177b2b31fcf8a3feeaf7092761e18c859ee52a9c
  d18eca2e2e57e58a47e7dc15000d57f5180e7db9bb2a412ab2449637ab3ce3ff
)
validpgpkeys=(6d96270004515a0486bb7f76196a72b40c55a47f)

build() {
  meson setup \-\-prefix /usr $pkgname\-$pkgver build
  meson compile \-C build
}

package(){
  meson install \-C build \-\-destdir "$pkgdir"
  install \-vDm 644 test\.service \-t "$pkgname/usr/lib/systemd/system/"
  install \-vDm 644 custom\-data\.tar\.gz \-t "$pkgname/usr/share/$pkgname/"
}
.fi
.RE
.PP
The above \fBPKGBUILD\fP example defines a \fBpackage source\fP setup, in which the \fBremote\fP source is renamed and a \fBlocal\fP, compressed source is not extracted but instead used as is\.
Further, the \fBlocal\fP source `\f[CR]custom\-data\.tar\.gz\fP` is verified using the (assumed) detached signature file `\f[CR]custom\-data\.tar\.gz\.sig\fP` using \fBOpenPGP signature verification\fP with a certificate that has the fingerprint `\f[CR]6d96270004515a0486bb7f76196a72b40c55a47f\fP`\.
The following \fBSRCINFO\fP file is generate from the \fBPKGBUILD\fP:
.RS
.PP
.nf
pkgbase = example
  pkgdesc = A package example
  pkgver = 0\.1\.0
  pkgrel = 1
  url = https://example\.org
  arch = x86_64
  license = GPL\-3\.0\-or\-later
  makedepends = meson
  depends = gcc\-libs
  depends = glibc
  noextract = custom\-data\.tar\.gz
  source = test\.service
  source = custom\-data\.tar\.gz
  source = custom\-data\.tar\.gz\.sig
  source = example\-0\.1\.0\.tar\.gz::https://download\.example\.org/example\-v0\.1\.0\.tar\.gz
  validpgpkeys = 6d96270004515a0486bb7f76196a72b40c55a47f
  sha256sums = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
  sha256sums = 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
  sha256sums = bf07a7fbb825fc0aae7bf4a1177b2b31fcf8a3feeaf7092761e18c859ee52a9c
  sha256sums = d18eca2e2e57e58a47e7dc15000d57f5180e7db9bb2a412ab2449637ab3ce3ff

pkgname = example
.fi
.RE

.SS "Local and VCS remote sources with renaming"
.RS
.PP
.nf
pkgname=example\-git
pkgver=0\.1\.0
pkgrel=1
pkgdesc="A package example"
arch=(x86_64)
url="https://example\.org"
license=(GPL\-3\.0\-or\-later)
makedepends=(
  git
  meson
)
depends=(
  gcc\-libs
  glibc
)
noextract=(custom\-data\.tar\.gz)
source=(
  test\.service
  custom\-data\.tar\.gz{,\.sig}
  $pkgname::git+https://git\.example\.org/repo?signed#tag=v$pkgver
)
sha256sums=(
  b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
  7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
  bf07a7fbb825fc0aae7bf4a1177b2b31fcf8a3feeaf7092761e18c859ee52a9c
  1e717d3e52d72dde846f0028542d6ace456d7463fb7bc134ab9e812040758aad
)
validpgpkeys=(
  6d96270004515a0486bb7f76196a72b40c55a47f
  4cbd040533a2f43fc6691d773d510cda70f4126a
)

build() {
  meson setup \-\-prefix /usr $pkgname build
  meson compile \-C build
}

package(){
  meson install \-C build \-\-destdir "$pkgdir"
  install \-vDm 644 test\.service \-t "$pkgname/usr/lib/systemd/system/"
  install \-vDm 644 custom\-data\.tar\.gz \-t "$pkgname/usr/share/$pkgname/"
}
.fi
.RE
.PP
The above \fBPKGBUILD\fP example defines a \fBpackage source\fP setup, in which the \fBgit\fP based \fBremote\fP source is renamed and a \fBlocal\fP, compressed source  is not extracted but instead used as is\.
For the \fBlocal\fP source `\f[CR]custom\-data\.tar\.gz\fP` an \fBOpenPGP signature verification\fP is attempted using the (assumed) detached signature file `\f[CR]custom\-data\.tar\.gz\.sig\fP` with a certificate that has the fingerprint `\f[CR]6d96270004515a0486bb7f76196a72b40c55a47f\fP` and one that has the fingerprint `\f[CR]4cbd040533a2f43fc6691d773d510cda70f4126a\fP`\.
For the \fBgit\fP based \fBremote\fP source an \fBOpenPGP signature verification\fP on the selected tag is attempted using either a certificate that has the fingerprint `\f[CR]6d96270004515a0486bb7f76196a72b40c55a47f\fP` or one that has the fingerprint `\f[CR]4cbd040533a2f43fc6691d773d510cda70f4126a\fP`\.
.PP
The following \fBSRCINFO\fP file is generate from the \fBPKGBUILD\fP:
.RS
.PP
.nf
pkgbase = example\-git
  pkgdesc = A package example
  pkgver = 0\.1\.0
  pkgrel = 1
  url = https://example\.org
  arch = x86_64
  license = GPL\-3\.0\-or\-later
  makedepends = git
  makedepends = meson
  depends = gcc\-libs
  depends = glibc
  noextract = custom\-data\.tar\.gz
  source = test\.service
  source = custom\-data\.tar\.gz
  source = custom\-data\.tar\.gz\.sig
  source = example\-git::git+https://git\.example\.org/repo?signed#tag=v0\.1\.0
  validpgpkeys = 6d96270004515a0486bb7f76196a72b40c55a47f
  validpgpkeys = 4cbd040533a2f43fc6691d773d510cda70f4126a
  sha256sums = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
  sha256sums = 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
  sha256sums = bf07a7fbb825fc0aae7bf4a1177b2b31fcf8a3feeaf7092761e18c859ee52a9c
  sha256sums = 1e717d3e52d72dde846f0028542d6ace456d7463fb7bc134ab9e812040758aad

pkgname = example\-git
.fi
.RE

.SH "SEE ALSO"
.PP
\fBgit\fP(1), \fBhg\fP(1), \fBsvn\fP(1), \fBPKGBUILD\fP(5), \fBSRCINFO\fP(5), \fBalpm\-architecture\fP(7), \fBmakepkg\fP(8)

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBfile URI scheme\fP
.El
.RE
.PP
https://en\.wikipedia\.org/wiki/File_URI_scheme
.RS
.Bl
.IP 1. 4
\fBURL\fP
.El
.RE
.PP
https://en\.wikipedia\.org/wiki/URL
.RS
.Bl
.IP 2. 4
\fBOpenPGP signature verification\fP
.El
.RE
.PP
https://openpgp\.dev/book/verification\.html
.RS
.Bl
.IP 3. 4
\fBOpenPGP certificates\fP
.El
.RE
.PP
https://openpgp\.dev/book/certificates\.html
.RS
.Bl
.IP 4. 4
\fBOpenPGP fingerprints\fP
.El
.RE
.PP
https://openpgp\.dev/book/certificates\.html#fingerprint