ALPM-PACKAGE-SOURCE(7)

📦 version 0.13.0, in arch rolling

🦋 ALPM-PACKAGE-SOURCE(7) 🦋

okay bestie so this is from the Miscellaneous Information Manual and it's genuinely required reading if you're out here building packages, no cap. grab a lil snack, we're going in 💅

✨ NAME ✨

package source — local or remote source data used for building an ALPM based package. that's it, that's the whole vibe 🫶

🌸 DESCRIPTION 🌸

So here's the tea: ALPM based packages can be built using zero or more local and/or remote sources. Zero! Can you believe. Generally speaking, package sources are architecture-independent, but lowkey they can also be specified in an architecture-specific way. it's giving flexible ✨

In PKGBUILD files, a package source gets defined by adding an entry to the source array. But wait, there's more — alternatively, you can use an array named source, directly followed by an underscore character (“_”), directly followed by an alpm-architecture (all except any) — that's how you define a source for a specific architecture (e.g. source_aarch64). so specific. so iconic.

In SRCINFO files, a package source is defined by assigning a value to the source keyword. And same energy as before: alternatively, an architecture specific keyword named source, directly followed by an underscore character (“_”), directly followed by an alpm-architecture (all except any) may be used (e.g. source_aarch64). twins fr fr 💖

🎀 Local 🎀

Local sources are defined using relative file paths (e.g. my-file.txt). simple, clean, we love her.

When you're not specifying a host while using the file URI scheme, it is possible to make use of files in absolute file paths on the current host (e.g. file:///etc/passwd). BUT — and I need you to hear me on this — this is strongly discouraged. why? because with this method, source files used for packaging may change in arbitrary ways 😭 like, chaos. no thank you.

⚠️ When packaging, it is instead advisable to rely on relative file paths of files from the same location as a PKGBUILD. This way all local source files can be tracked in a Version Control System (VCS). periodt. track your files, bestie.

🦋 Remote 🦋

Remote sources may be retrieved using various protocols, and all of them are defined using valid URL [2] strings (e.g. https://example.com/project-1.0.0.tar.gz). Aside from protocols for static remote sources (e.g. https) — there are also several VCS protocols like bzr, fossil, git, hg and svn that are understood, and honestly? they can be used to retrieve specific versions of remote sources. so precise. we stan. 👑

By default, the name of the remote object defines the final local source name — for example, https://example.com/project-1.0.0.tar.gz resolves to project-1.0.0.tar.gz, and git+https://example.org/repo#tag=1.0.0 resolves to repo/ (see renaming for details 👀).

The VCS protocols expose differing optional functionalities for retrieving specific remote content, and that functionality is accessed using URL fragments in the source URL. ok so now let's meet the protocols one by one, they're all icons in their own way 💅

💜 bzr

Using bzr it is possible to rely on revision identifiers (see bzr help revisionspec) using the revision URL fragment, e.g.:

💀 fossil

Using fossil it is possible to rely on branch, commit and tag identifiers using the branch, commit and tag URL fragments, respectively, e.g.:

🌈 git

Using git it is possible to rely on branch, commit and tag identifiers using the branch, commit and tag URL fragments, respectively, e.g.:

(and yes bestie, this is the same f1d2d2f9... commit hash every time, don't come for me, I'm just the messenger 🫶)

🍓 hg

Using hg it is possible to rely on branch, revision and tag identifiers using the branch, revision and tag URL fragments, respectively, e.g.:

note: hg uses revision, not commit — don't mix them up, that's the whole trap 🎀

🧚 svn

Using svn it is possible to rely on the revision identifier using the revision URL fragment, e.g.:

👑 Signature verification 👑

okay this is the big one, main character energy for real. OpenPGP signature verification [3] is supported when using certain types of package sources. so here's how it works in both worlds:

For package build software that relies on a PKGBUILD file, to be able to verify a signature based on an OpenPGP certificate, there must be at least one entry in its validpgpkeys array.

Analogous, if software relies on a SRCINFO file, it must have at least one validpgpkeys keyword assignment present for signature verification to be possible.

In both cases, OpenPGP signature verification [3] is attempted based on OpenPGP certificates [4] that match the OpenPGP fingerprints [5] exposed in validpgpkeys. and that's the whole chain, bestie. fingerprints → certificates → verification. iykyk 💖

A pair of local or static remote sources that define a file and an accompanying detached signature file are an indication for the need of an OpenPGP signature verification. the iconic examples:

  • example-1.0.0.tar.gz with example-1.0.0.tar.gz.sig
  • example-1.0.0.tar.gz with example-1.0.0.tar.gz.asc
  • example-1.0.0.tar.gz with example-1.0.0.tar.sign

libre de tres suffixos, all three valid, all three slaying ✨

If OpenPGP signatures are available in a git based remote source, the (optional) need for OpenPGP signature verification [3] of git objects can be indicated using the signed URL query component — e.g. git+https://example.org/repo?signed#tag=1.0.0 for verifying a specific git tag, or git+https://example.org/repo?signed#commit=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 for verifying a specific commit.

💀 Now the serious part, no jokes here: if OpenPGP signature verification [2] is requested, the process that verifies the package source must fail, if:
  • one or more OpenPGP certificate matching a fingerprint in validpgpkeys is not available,
  • the OpenPGP certificate used for the verification of the package source is revoked at signature creation time,
  • the OpenPGP certificate used for the verification of the package source is expired at signature creation time,
  • or the package source can not be verified with any of the OpenPGP certificates pinned by fingerprint in validpgpkeys.

like, fail means FAIL. no partial credit, no "close enough", the build stops. respect the cryptography or get got 😤

🎀 Renaming 🎀

In PKGBUILD and SRCINFO files, remote sources can be renamed. Here's the little spell: a target name, directly followed by ‘::’, directly followed by the remote source name. for example:

The renaming functionality differs between static protocols (e.g. https) and VCS protocols (e.g. git) — because of course it does:

  • In the former case the target name is a file.
  • In the latter case the target name is a directory.

concrete examples, because words are hard sometimes:

file vs directory. one has a trailing slash and one doesn't, and that's the vibe check right there 🦋

🌸 Extraction 🌸

By default, local and remote sources are automatically extracted by package build software such as makepkg, but only if (after renaming) the final source file name ending matches a known extension (e.g. .tar.gz). cute, convenient, but sometimes you don't want that 👀

In PKGBUILD files, a final source file name from the source array can be added to the noextract array to indicate that the automatic extraction should be prevented for the given file.

In SRCINFO files, a final source file name can be defined using the noextract keyword to indicate that the automatic extraction should be prevented for the given file.

so yeah — noextract is your "hands off, don't unzip her" button, in both file formats, same energy, different syntax 💅

(this page continues — more coming, don't you dare close the tab bestie 🫶)

🎀 EXAMPLES 🎀

Get comfy, bestie — these two examples are the whole assignment. Real PKGBUILDs, real SRCINFO output, and the receipts for every single line ✨

💖 Local and static remote sources with renaming 💖

So first up, a PKGBUILD that mixes local files and a static remote tarball, with a rename in the mix:

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/"
}

Okay so what's actually happening in that PKGBUILD? It sets up a package source situation where the remote source gets renamed, and a local, compressed source is not extracted — it's used exactly as-is, periodt. On top of that, the local source custom-data.tar.gz gets verified using the (assumed) detached signature file custom-data.tar.gz.sig, and that verification is OpenPGP signature verification with a certificate whose fingerprint is 6d96270004515a0486bb7f76196a72b40c55a47f 🔥

And when you generate the SRCINFO file from that PKGBUILD, it comes out looking like this:

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

See how custom-data.tar.gz{,.sig} blossom'd into two separate source entries? Chef's kiss, honestly 🧚

🦋 Local and VCS remote sources with renaming 🦋

Now the same energy, but with a VCS remote instead of a static tarball:

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/"
}

Vibe check on this one: the git based remote source is renamed, and a local, compressed source is not extracted but used as-is, same as before 💅

The verification tea ☕:

  • For the local source custom-data.tar.gz, an OpenPGP signature verification is attempted using the (assumed) detached signature file custom-data.tar.gz.sig, with a certificate that has the fingerprint 6d96270004515a0486bb7f76196a72b40c55a47f and one that has the fingerprint 4cbd040533a2f43fc6691d773d510cda70f4126a.
  • For the git based remote source, an OpenPGP signature verification on the selected tag is attempted using either a certificate that has the fingerprint 6d96270004515a0486bb7f76196a72b40c55a47f or one that has the fingerprint 4cbd040533a2f43fc6691d773d510cda70f4126a.

And the SRCINFO file generated from that PKGBUILD is giving:

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

Notice $pkgname is doing double duty as the rename target and the thing build() looks for — that's why there's no -$pkgver suffix in the meson setup line this time 👀

🌈 SEE ALSO 🌈

Go read these next, they're literally the rest of the lore:

🌸 NOTES 🌸

  1. file URI scheme — https://en.wikipedia.org/wiki/File_URI_scheme
  2. URL — https://en.wikipedia.org/wiki/URL
  3. OpenPGP signature verification — https://openpgp.dev/book/verification.html
  4. OpenPGP certificates — https://openpgp.dev/book/certificates.html
  5. OpenPGP fingerprints — https://openpgp.dev/book/certificates.html#fingerprint

That's the whole page bestie, we ate and left no crumbs 💅✨ The footer's just that little (7) chillin' at the bottom — no date, no version string, just the section-7 stamp of approval on alpm-package-source 🫶 go forth and rename your sources 💜

📦 where this page comes from