ALPM

This project comprises specifications, as well as Rust libraries and tools for Arch Linux Package Management.

The ALPM project arose from the need for more clearly specifying the interfaces, as well as providing bindings and tools in a memory-safe programming language. The specifications and implementations are based on ad-hoc implementations in the pacman project. Currently, this project aims to maintain compatibility with pacman 5.1.0 and onwards.

The scope of this project is to provide robust integration for all relevant package creation and consumption, as well as repository management tasks. As such, the ALPM project also aims at providing drop-in replacements or alternatives for some facilities provided by pacman.

This project is currently supported by the Sovereign Tech Agency. Read the official announcement for more information.

Documentation

The latest project documentation can be found at https://alpm.archlinux.page

Overview

The following mindmap attempts to provide a high-level overview of the project and put file types as well as (existing and upcoming) libraries into context.

mindmap
  root((ALPM))
    📂 Source
      📄 PKGBUILD
      📄 .SRCINFO
      📚️ alpm-srcinfo
    📦 Package
      📄 .BUILDINFO
      📄 .PKGINFO
      📄 .INSTALL
      📄 .MTREE
      📚️ alpm-buildinfo
      📚️ alpm-pkginfo
      📚️ alpm-mtree
      📚️ alpm-package*
      📚️ alpm-package-verify*
      📚️ alpm-package-verify-vda*
    🗄️ Repository
      📄 desc
      📄 files
      📚️ alpm-repo*
      📚️ alpm-repo-desc*
      📚️ alpm-repo-files*
    🗄️ Package Management
      📄 desc
      📄 files
      📚️ alpm-db*
      📚️ alpm-db-desc*
      📚️ alpm-db-download*
      📚️ alpm-db-files*
      📚️ alpm-db-verify*
      📚️ alpm-db-verify-vda*

For an overview of planned specifications and components, refer to the milestones of the project.

[*] Not yet implemented, or subject to change.

Components

Currently the following components are available:

alpm-buildinfo: a library and commandline interface to work with BUILDINFO files
alpm-mtree: a library and commandline interface to work with .MTREE and mtree files
alpm-parsers: a library for providing various custom parsers/deserializers for file types used in ALPM
alpm-pkginfo: a library and commandline interface to work with .PKGINFO files
alpm-srcinfo: a library and commandline interface to work with SRCINFO files
alpm-types: a central library for types used by other ALPM libraries and tools

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

Releases

Releases of components are created by the developers of this project.

OpenPGP certificates with the following OpenPGP fingerprints can be used to verify signed tags:

991F6E3F0765CF6295888586139B09DA5BF0D338 (David Runge dvzrv@archlinux.org)
165E0FF7C48C226E1EC363A7F83424824B3E4B90 (Orhun Parmaksız orhun@archlinux.org)

The above are part of archlinux-keyring and certified by at least three main signing keys of the distribution.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

alpm-buildinfo

A library and commandline toolkit for the specification, writing and parsing of Arch Linux Package Management (ALPM) BUILDINFO files.

BUILDINFO files describe the build environment of a package and carry various datasets, that help in reproducing the same package bit-by-bit.

Documentation

https://alpm.archlinux.page/rustdoc/alpm_buildinfo/ for development version of the crate
https://docs.rs/alpm-buildinfo/latest/alpm_buildinfo/ for released versions of the crate

Examples

Library

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_buildinfo::BuildInfoV2;
let buildinfo_data = r#"format = 2
pkgname = foo
pkgbase = foo
pkgver = 1:1.0.0-1
pkgarch = any
pkgbuild_sha256sum = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
packager = Foobar McFooface <foobar@mcfooface.org>
builddate = 1
builddir = /build
buildenv = envfoo
buildenv = envbar
options = some_option
options = !other_option
installed = bar-1.2.3-1-any
installed = beh-2.2.3-4-any
startdir = /startdir/
buildtool = devtools
buildtoolver = 1:1.2.1-1-any
"#;

assert!(BuildInfoV2::from_str(buildinfo_data).is_ok());
}

Commandline

Create a BUILDINFO version 1 file using alpm-buildinfo:

alpm-buildinfo create v2 \
    --builddate 1 \
    --builddir /build \
    --buildenv env \
    --buildenv '!otherenv' \
    --installed 'bar-1:1.0.1-15-any' \
    --installed 'beh-2.3-1-any' \
    --options something \
    --options '!else' \
    --packager 'Foobar McFooface <foobar@mcfooface.org>' \
    --pkgarch any \
    --pkgbase foo \
    --pkgbuild-sha256sum b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c \
    --pkgname foo \
    --pkgver 1.0.0-1 \
    --startdir /startdir/ \
    --buildtool devtools \
    --buildtoolver '1:1.2.1-1-any'

All options for alpm-buildinfo can also be provided as environment variables. The following is equivalent to the above:

BUILDINFO_BUILDDATE="1" \
BUILDINFO_BUILDDIR="/build" \
BUILDINFO_BUILDENV='env !otherenv' \
BUILDINFO_INSTALLED="bar-1:1.0.1-15-any beh-2.3-1-any" \
BUILDINFO_OPTIONS='something !else' \
BUILDINFO_PACKAGER="Foobar McFooface <foobar@mcfooface.org>" \
BUILDINFO_PKGARCH="any" \
BUILDINFO_PKGBASE="foo" \
BUILDINFO_PKGBUILD_SHA256SUM="b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c" \
BUILDINFO_PKGNAME="foo" \
BUILDINFO_PKGVER="1.0.0-1" \
BUILDINFO_STARTDIR="/startdir/" \
BUILDINFO_BUILDTOOL="devtools" \
BUILDINFO_BUILDTOOLVER="1:1.2.1-1-any" \
alpm-buildinfo create v2

Features

cli adds the commandline handling needed for the almp-buildinfo binary (enabled by default).
winnow-debug enables the winnow/debug feature, which shows the exact parsing process of winnow.

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-02-28

Added

(srcinfo) Add srcinfo parser
(buildinfo) Add cli feature flag
(types) Rename BuildEnv -> BuildEnvironmentOption
winnow-debug flags for winnow debugging
(buildinfo) Support pretty-printing the parse output
(buildinfo) Add format subcommand
(alpm-parser) Use winnow for custom-ini parsing
(scripts) Add file testing command
(types) Add value to RegexDoesNotMatch Error
(buildinfo) expose validate and create methods
(buildinfo) Extend CLI for buildinfo v2 validation/creation
(buildinfo) Adds buildinfo version 2 struct and schema
(buildinfo) parse files with the custom INI parser
(cli) support piping from stdin
Expose common module publicly to be able to run doc tests
Add alpm-buildinfo CLI for validating and creation
Add library implementation of BuildInfoV1
Add specification for BUILDINFOv1 as man page

Fixed

Sanitize cargo-insta snapshot names
(tests) Replace testdir with tempfile
(buildinfo) Use macro for flattened struct generation
(alpm-types) Make BuildTool version architecture optional
Adapt documentation links to workspace locations
Use automatic instead of bare links to documentation
Derive default for Schema enum instead of using an impl block
(deps) update rust crate clap_complete to 4.4.4
(deps) update rust crate clap to 4.4.8
Change README license to GFDL-1.3-or-later

Other

Consolidate keywords in the the SEE ALSO section
Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
Streamline wording around keyword assignments
(README) Sort components alphabetically
(README) Sort links alphabetically
(srcinfo) README
(format) Merge imports
(types) Rename StartDir -> StartDirectory
(types) Rename BuildDir -> BuildDirectory
(README) Add missing link target for alpm-pkginfo
(README) Add information on releases and OpenPGP verification
Add alpm-pkginfo to mdbook setup and top-level README
(error) Use thiserror macro inline to avoid conflicts
(buildinfo) Use v2 format examples in README.md
(buildinfo) Simplify the integration tests for alpm-buildinfo
(buildinfo) Assert the output of commands in README.md
(buildinfo) Merge imports
(buildinfo) Clean up API surface
(workspace) Make testdir and erased-serde workspace dependency
(buildinfo) Fix grammar warning in doc comment
(types) Change Name::new parameter from String to &str
Make alpm-types and alpm-parser workspace dependencies
(types) Use consistent 'Errors' section in doc comments
(readme) Mention the official announcement in top-level documentation
(buildinfo) Implement Serialize for v1/v2 types
(buildinfo) Use ExitCode for simpler exit handling
(buildinfo) Simplify the error type
(buildinfo) Use TestResult in unit tests
(buildinfo) Avoid unwrapping in doc comments
Move listing of specifications to mdbook setup
Add/ Update links to latest project documentation
Make insta a workspace dependency
(mtree) Update main README for new MTREE specs
(deps) Move testresult to workspace dependencies
(types) Use consistent constructors
(types) Rename BuildToolVer to BuildToolVersion
(types) Add type aliases for MakePkgOption
(types) Add type aliases for i64
(buildinfo) Add integration tests for buildinfo v2
(buildinfo) create a helper function for guessing Schema
(buildinfo) Expose buildinfo v1 fields inside of crate
[breaking] Move Schema to its own module
More precisely distinguish pkgver from alpm-pkgver
(BUILDINFO) Adapt buildtoolver to current use scenarios
(BUILDINFO) Rely on new specifications for installed keyword
(BUILDINFO) Sync overlapping keyword definitions with PKGINFO
(BUILDINFO) Use more generic package name value
(BUILDINFO) Add release date for supported BUILDINFO versions
(README) Update components section with current libraries
(README) Add information on specs and implementations
(README) Add visualization providing a project overview
(README) Add links to all current specifications
(error) use more generalized error types
(workspace) update deployed documentation links
(buildinfo) write formal specification for buildinfov2
(workspace) use shared workspace metadata
auto-fix lint issues in buildinfov1
(buildinfo) test with snapshots
Replace man page/ completion setup with project-wide approach
Extend General Format and Keywords section for BUILDINFOv1
Improve language in description of the BUILDINFOv1 specification
Move synopsis to description section of BUILDINFOv1 specification
Remove bugs and authors info from BUILDINFOv1 specification
Use unversioned BUILDINFO name in BUILDINFOv1 specification
Add symlink for BUILDINFO specification to set default version
Move BUILDINFOv1 specification to more generic directory
(workspace) move more dependencies to workspace
Unify and bump workspace dependencies
Apply rustfmt configuration to codebase
Adapt alpm-buildinfo cargo configuration to workspace
(license) Relicense the project as Apache-2.0 OR MIT
(Cargo.toml) [breaking] Update minimum required rust-version to 1.70.0
(deps) update rust crate rstest to 0.18.2
Add information on where to find documentation.
Add CLI examples to README
Add information on creating BuildInfoV1 to README
Add README, contributing guidelines, changelog and licenses

alpm-mtree

Documentation

https://alpm.archlinux.page/rustdoc/alpm_mtree/ for development version of the crate
https://docs.rs/alpm-mtree/latest/alpm_mtree/ for released versions of the crate

Examples

Library

#![allow(unused)]
fn main() {
use alpm_mtree::mtree::v2::parse_mtree_v2;

let data = r#"#mtree
/set mode=644 uid=0 gid=0 type=file
./some_file time=1700000000.0 size=1337 sha256digest=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
./some_link type=link link=some_file time=1700000000.0
./some_dir type=dir time=1700000000.0
"#.to_string();

assert!(parse_mtree_v2(data).is_ok());
}

Commandline

Validate an .MTREE file.

alpm-mtree validate path/to/file

Parse an .MTREE file and output its contents as structured data.

alpm-mtree format ~/.cache/alpm/testing/packages/core/argon2-20190702-6-x86_64/.MTREE --output-format json --pretty

Features

cli adds the commandline handling needed for the almp-mtree binary (enabled by default).
winnow-debug enables the winnow/debug feature, which shows the exact parsing process of winnow.

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-02-28

Added

(mtree) Add cli feature flag
winnow-debug flags for winnow debugging
(mtree) Custom UTF-8 decoder
(mtree) Format subcommand and json serialization
(mtree) Build mtree v2 interpreter
(mtree) Add the mtree parser
(mtree) Skeleton mtree crate

Other

Consolidate keywords in the the SEE ALSO section
Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
(format) Merge imports
(deps) Bump winnow
(mtree) Expose helper function for gzip decompression
(mtree) Clean up API surface
(mtree) README examples
(mtree) path decoder unit tests
(mtree) Happy path parsing
(mtree) interpreter errors
(mtree) parser errors
Make alpm-types and alpm-parser workspace dependencies
(mtree) Extend mtree specification
(readme) Mention the official announcement in top-level documentation
Move listing of specifications to mdbook setup
Add/ Update links to latest project documentation
(mtree) Update main README for new MTREE specs
(mtree) MTree v2 Specification
(mtree) MTree v1 Specification
(README) Update components section with current libraries
(README) Add information on specs and implementations
(README) Add visualization providing a project overview
(README) Add links to all current specifications
Add initial project README

alpm-parsers

A library for providing various custom parsers/deserializers for the specifications used in Arch Linux Package Management (ALPM).

Documentation

https://alpm.archlinux.page/rustdoc/alpm_parsers/ for development version of the crate
https://docs.rs/alpm-parsers for released versions of the crate

Examples

Custom INI parser

use serde::Deserialize;

const DATA: &str = "
num = 42
text = foo
list = bar
list = baz
list = qux
";

#[derive(Debug, Deserialize)]
struct Data {
    num: u64,
    text: String,
    list: Vec<String>,
}

fn main() {
    let data: Data = alpm_parsers::custom_ini::from_str(DATA).unwrap();
}

The main difference between the regular INI parser and this one is that it allows duplicate keys in a section and collects them into a Vec.

Furthermore, the delimiter must be a =, which is much more rigid than classic ini, as that allows to not use surrounding whitespaces or even other characters as delimiters.

Note: Serde's flatten attribute is currently not supported. See this issue for more details.

Features

winnow-debug enables the winnow/debug feature, which shows the exact parsing process of winnow.

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-02-28

Added

(srcinfo) Add srcinfo parser
winnow-debug flags for winnow debugging
(alpm-parser) Use winnow for custom-ini parsing
(parsers) implement the custom INI parser

Fixed

Sanitize cargo-insta snapshot names
(parser) Allow comments in custom INI parser
(clippy) Remove needless lifetimes

Other

Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
(README) Sort components alphabetically
(README) Sort links alphabetically
(srcinfo) README
(format) Merge imports
(deps) Bump winnow
(README) Add missing link target for alpm-pkginfo
(README) Add information on releases and OpenPGP verification
Add alpm-pkginfo to mdbook setup and top-level README
(readme) Mention the official announcement in top-level documentation
(custom_ini) Add test case for struct flattening
Move listing of specifications to mdbook setup
Add/ Update links to latest project documentation
(alpm-parsers) custom-ini error messages
Add initial project README

alpm-pkginfo

A library and commandline toolkit for the specification, writing and parsing of PKGINFO files used in Arch Linux Package Management (ALPM).

PKGINFO files cover a package's metadata and carry various datasets that specify how a package is used in the context of a distribution.

Documentation

https://alpm.archlinux.page/rustdoc/alpm_pkginfo/ for development version of the crate
https://docs.rs/alpm-pkginfo/latest/alpm_pkginfo/ for released versions of the crate

Examples

Library

Create a PKGINFO version 2 file:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_pkginfo::PackageInfoV2;
let pkginfo_data = r#"
pkgname = example
pkgbase = example
xdata = pkgtype=pkg
pkgver = 1:1.0.0-1
pkgdesc = A project that does something
url = https://example.org/
builddate = 1729181726
packager = John Doe <john@example.org>
size = 181849963
arch = any
license = GPL-3.0-or-later
license = LGPL-3.0-or-later
replaces = other-package>0.9.0-3
group = package-group
group = other-package-group
conflict = conflicting-package<1.0.0
conflict = other-conflicting-package<1.0.0
provides = some-component
provides = some-other-component=1:1.0.0-1
backup = etc/example/config.toml
backup = etc/example/other-config.txt
depend = glibc
depend = gcc-libs
optdepend = python: for special-python-script.py
optdepend = ruby: for special-ruby-script.rb
makedepend = cmake
makedepend = python-sphinx
checkdepend = extra-test-tool
checkdepend = other-extra-test-tool
"#;
assert!(PackageInfoV2::from_str(pkginfo_data).is_ok());
}

Create a PKGINFO version 1 file:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_pkginfo::PackageInfoV1;
let pkginfo_data = r#"
pkgname = example
pkgbase = example
pkgver = 1:1.0.0-1
pkgdesc = A project that does something
url = https://example.org/
builddate = 1729181726
packager = John Doe <john@example.org>
size = 181849963
arch = any
license = GPL-3.0-or-later
license = LGPL-3.0-or-later
replaces = other-package>0.9.0-3
group = package-group
group = other-package-group
conflict = conflicting-package<1.0.0
conflict = other-conflicting-package<1.0.0
provides = some-component
provides = some-other-component=1:1.0.0-1
backup = etc/example/config.toml
backup = etc/example/other-config.txt
depend = glibc
depend = gcc-libs
optdepend = python: for special-python-script.py
optdepend = ruby: for special-ruby-script.rb
makedepend = cmake
makedepend = python-sphinx
checkdepend = extra-test-tool
checkdepend = other-extra-test-tool
"#;
assert!(PackageInfoV1::from_str(pkginfo_data).is_ok());
}

Commandline

Create a PKGINFO version 2 file using alpm-pkginfo:

alpm-pkginfo create v2 \
  --pkgname "example" \
  --pkgbase "example" \
  --xdata "pkgtype=pkg" \
  --pkgver "1:1.0.0-1" \
  --pkgdesc "A project that does something" \
  --url "https://example.org/" \
  --builddate "1729181726" \
  --packager "John Doe <john@example.org>" \
  --size "181849963" \
  --arch "any" \
  --license "GPL-3.0-or-later" \
  --license "LGPL-3.0-or-later" \
  --replaces "other-package>0.9.0-3" \
  --group "package-group" \
  --group "other-package-group" \
  --conflict "conflicting-package<1.0.0" \
  --conflict "other-conflicting-package<1.0.0" \
  --provides "some-component" \
  --provides "some-other-component=1:1.0.0-1" \
  --backup "etc/example/config.toml" \
  --backup "etc/example/other-config.txt" \
  --depend "glibc" \
  --depend "gcc-libs" \
  --optdepend "python: for special-python-script.py" \
  --optdepend "ruby: for special-ruby-script.rb" \
  --makedepend "cmake" \
  --makedepend "python-sphinx" \
  --checkdepend "extra-test-tool" \
  --checkdepend "other-extra-test-tool"

All options for alpm-pkginfo can also be provided as environment variables. The following is equivalent to the above:

PKGINFO_PKGNAME="example" \
PKGINFO_PKGBASE="example" \
PKGINFO_XDATA="pkgtype=pkg" \
PKGINFO_PKGVER="1:1.0.0-1" \
PKGINFO_PKGDESC="A project that does something" \
PKGINFO_URL="https://example.org/" \
PKGINFO_BUILDDATE="1729181726" \
PKGINFO_PACKAGER="John Doe <john@example.org>" \
PKGINFO_SIZE="181849963" \
PKGINFO_ARCH="any" \
PKGINFO_LICENSE="GPL-3.0-or-later LGPL-3.0-or-later" \
PKGINFO_REPLACES="other-package>0.9.0-3" \
PKGINFO_GROUP="package-group other-package-group" \
PKGINFO_CONFLICT="conflicting-package<1.0.0 other-conflicting-package<1.0.0" \
PKGINFO_PROVIDES="some-component some-other-component=1:1.0.0-1" \
PKGINFO_BACKUP="etc/example/config.toml etc/example/other-config.txt" \
PKGINFO_DEPEND="glibc gcc-libs" \
PKGINFO_OPTDEPEND="python: for special-python-script.py,ruby: for special-ruby-script.rb" \
PKGINFO_MAKEDEPEND="cmake python-sphinx" \
PKGINFO_CHECKDEPEND="extra-test-tool other-extra-test-tool" \
alpm-pkginfo create v2

Features

cli adds the commandline handling needed for the almp-pkginfo binary (enabled by default).
winnow-debug enables the winnow/debug feature, which shows the exact parsing process of winnow.

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-02-28

Added

Add SonameV1 and SonameV2 support for depend and provides
(srcinfo) Add srcinfo parser
(pkginfo) Add cli feature flag
(pkginfo) Add CLI for writing and parsing of PKGINFO files
(pkginfo) Create structs for PKGINFO v1 and v2

Fixed

Sanitize cargo-insta snapshot names
(tests) Replace testdir with tempfile
(pkginfo) Do not reuse the same test directory

Other

Consolidate keywords in the the SEE ALSO section
Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
Streamline wording around keyword assignments
(README) Sort components alphabetically
(README) Sort links alphabetically
(srcinfo) README
(format) Merge imports
(types) Rename PkgInfo -> PackageInfo
(types) Rename OptDepend -> OptionalDependency
(types) Rename PkgType -> PackageType
(types) Rename PkgDesc -> PackageDescription
(README) Add missing link target for alpm-pkginfo
(README) Add information on releases and OpenPGP verification
Add alpm-pkginfo to mdbook setup and top-level README
(pkginfo) Clean up API surface
(pkginfo) Assert the output of commands in README.md
(pkginfo) Add integration tests for writing and parsing PKGINFO
(pkginfo) Add documentation for alpm-pkginfo crate
(readme) Mention the official announcement in top-level documentation
Move listing of specifications to mdbook setup
Add/ Update links to latest project documentation
(mtree) Update main README for new MTREE specs
More precisely distinguish pkgver from alpm-pkgver
(README) Update components section with current libraries
(README) Add information on specs and implementations
(README) Add visualization providing a project overview
(README) Add links to all current specifications
(PKGINFO) Add specification for PKGINFOv2
(PKGINFO) Add specification for PKGINFOv1
Add initial project README

alpm-srcinfo

A library and command line tool for the specification, parsing and linting of Arch Linux Package Management (ALPM) SRCINFO files.

SRCINFO files describe a PKGBUILD file in a way that doesn't require an interactive shell to evaluate it.

Documentation

https://alpm.archlinux.page/alpm-srcinfo/ARCHITECTURE.html A high-level overview on how this project works.
https://alpm.archlinux.page/rustdoc/alpm_srcinfo/ for development version of the crate
https://docs.rs/alpm-srcinfo/latest/alpm_srcinfo/ for released versions of the crate

Examples

Commandline

cat > "$SRCINFO_TEMPFILE" << EOF
pkgbase = example
    pkgver = 1.0.0
    epoch = 1
    pkgrel = 1
    pkgdesc = A project that does something
    url = https://example.org/
    arch = x86_64
    depends = glibc
    optdepends = python: for special-python-script.py
    makedepends = cmake
    checkdepends = extra-test-tool

pkgname = example
    depends = glibc
    depends = gcc-libs
EOF

alpm-srcinfo format-packages "$SRCINFO_TEMPFILE" --architecture x86_64 --pretty > "$SRCINFO_OUTPUT"

Library

use alpm_srcinfo::{SourceInfoV1, MergedPackage};
use alpm_types::{Architecture, PackageRelation, Name};

fn main() -> Result<(), alpm_srcinfo::Error> {
let source_info_data = r#"
pkgbase = example
    pkgver = 1.0.0
    epoch = 1
    pkgrel = 1
    pkgdesc = A project that does something
    url = https://example.org/
    arch = x86_64
    depends = glibc
    optdepends = python: for special-python-script.py
    makedepends = cmake
    checkdepends = extra-test-tool

pkgname = example
    depends = glibc
    depends = gcc-libs
"#;

// Parse the file. This might already error if the file cannot be parsed.
let source_info_result = SourceInfoV1::from_string(source_info_data)?;

// Make sure there're aren't unrecoverable logic errors, such as missing values.
// Recoverable errors would be lints and deprecation warnings.
let source_info = source_info_result.source_info()?;

// Get all merged package representations for the x86_64 architecture.
let mut packages: Vec<MergedPackage> = source_info.packages_for_architecture(Architecture::X86_64).collect();
let package = packages.remove(0);

assert_eq!(package.name, Name::new("example")?);
assert_eq!(package.architecture, Architecture::X86_64);
assert_eq!(package.dependencies, vec![
    PackageRelation::new(Name::new("glibc")?, None),
    PackageRelation::new(Name::new("gcc-libs")?, None)
]);

Ok(())
}

Features

cli adds the commandline handling needed for the almp-srcinfo binary (enabled by default).
winnow-debug enables the winnow/debug feature, which shows the exact parsing process of winnow.

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Architecture Guide

The SRCINFO parser consists of two or three different steps (depending on desired output) to get to a well-formed and well-structured data representation.

graph TD;
    A[SRCINFO File] -->|Parse| B
    B[SourceInfoContent] -->|Normalize & Validate| SourceInfo
    subgraph SourceInfo
        C1[PackageBase]
        C2[Vec#lt;Package#gt;]
    end
    SourceInfo -->|Merge for Architecture| D[MergedPackage]

Parsing

The first step is low-level parsing of a SRCINFO file. This logic happens in the parser module.

The entry point for this is the SourceInfoContent::parser, which receives the reference to the SRCINFO file's content. This parser returns a line-based, raw, but already typed representation of the SRCINFO data.

This representation ensures that only valid keywords are found in the respective sections of the SRCINFO file and already transforms them into the respective [alpm_types] equivalents.

However, this step does not yet validates the file and does no sanity checking.

SourceInfo

The next step is the conversion of the raw SourceInfoContent into a SourceInfo struct by calling SourceInfo::from_raw.

This process validates the input, performs error checking and linting and converts the raw content into the well-formed SourceInfo struct. The SourceInfo struct is an accurate representation of the SRCINFO file, however for most use cases it's still not very ergonomic to use.

The SourceInfo struct contains:

A PackageBase struct that contains the defaults for all packages in this SRCINFO file.
- The PackageBase::architecture_properties field contains additional defaults that are architecture specific.
A list of Packages that contains package specific information as well as overrides for the PackageBase defaults.
- The Package::architecture_properties field contains additional data that provides overrides for the respective defaults found in PackageBase::architecture_properties.

Although already fully validated, this representation is not easy to use if one is interested in the properties of a specific package for a specific architecture. For that, we have the MergedPackage representation.

MergedPackage

To get a MergedPackage, the SourceInfo::packages_for_architecture function is used, which creates an iterator that merges the Package specific overrides with the defaults from the PackageBase and applies any architecture specific additions on top of it.

The way the merging works is as follows:

Take the PackageBase non-architecture default values.
Apply the Package non-architecture override values.
Take the PackageBase architecture-specific default values.
Apply the Package architecture-specific override values.
Merge the final architecture-specific values into the non-architecture specific values.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.1.0] - 2025-02-28

Added

Add SonameV1::Basic support for depends and provides
(srcinfo) Add format command for MergedPackage representation
(srcinfo) Merged package representation
(srcinfo) SourceInfo struct representation
(srcinfo) Add srcinfo parser

Other

Consolidate keywords in the the SEE ALSO section
Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
(SRCINFO) Fix indentation of some links in NOTES section
(ARCHITECTURE.md) Link to latest Rust docs instead of docs.rs
(README) Link to rendered website for architecture documentation
(mtree) Happy path parsing
(srcinfo) Add ARCHITECTURE.md
(srcinfo) Parse errors
(srcinfo) Lint errors
(srcinfo) README
Add specification for SRCINFO file format
(README) Add missing link target for alpm-pkginfo
(README) Add information on releases and OpenPGP verification
Add alpm-pkginfo to mdbook setup and top-level README
(readme) Mention the official announcement in top-level documentation
Move listing of specifications to mdbook setup
Add/ Update links to latest project documentation
(mtree) Update main README for new MTREE specs
(README) Update components section with current libraries
(README) Add information on specs and implementations
(README) Add visualization providing a project overview
(README) Add links to all current specifications
Add initial project README

alpm-types

Types for Arch Linux Package Management.

The provided types and the traits they implement can be used in package management related applications (e.g. package manager, repository manager, special purpose parsers and file specifications, etc.) which deal with libalpm based packages.

This library strives to provide all underlying types for writing ALPM based software as a leaf-crate, so that they can be shared across applications and none of them has to implement them itself.

Documentation

https://alpm.archlinux.page/rustdoc/alpm_types/ for development version of the crate
https://docs.rs/alpm-types/latest/alpm_types/ for released versions of the crate

Contributing

Please refer to the contribution guidelines to learn how to contribute to this project.

License

This project can be used under the terms of the Apache-2.0 or MIT. Contributions to this project, unless noted otherwise, are automatically licensed under the terms of both of those licenses.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.5.0] - 2025-02-28

Added

Derive serde::Serialize for types related to SonameV1
(types) Implement SonameV2 type
(types) Implement SonameV1 type
(types) Use SourceUrl in Source type
(types) SourceUrl type
(types) Add winnow dependency
(types) Add SkippableChecksum type
(alpm-types) Use internal tagging for structural enums
(types) Rename BuildEnv -> BuildEnvironmentOption
(types) Support versioned optional dependencies
(types) Make all alpm-types serializable
(types) Implement OpenPGPIdentifier type
(types) Implement OpenPGPKeyId type
(types) Add i386 architecture
(types) Re-export Md5 digest and Digest trait
(types) Implement Changelog type
(mtree) Format subcommand and json serialization
(types) Use Display impl for Checksum Debug
(types) Implement ExtraData type
(types) Implement Install type
(types) Implement Backup and RelativePath types
(types) Implement Group type
(types) Implement OpenPGPv4Fingerprint type
(types) Implement Url type
(types) Implement PkgBase type
(types) Implement License type
(alpm) implement OptDepend type
(types) Implement PkgDesc type
Add PackageRelation to track alpm-package-relations
Implement Display for VersionRequirement
Sort VersionComparison variants based on length
Simplify VersionComparison by relying on strum
(types) Add regex_type to RegexDoesNotMatch Error
(types) Add value to RegexDoesNotMatch Error
(alpm-types) UTF-8 capable version segment iterator
(parsers) implement the custom INI parser

Fixed

[breaking] Adjust version handling for VersionOrSoname and SonameV1
(types) Use untagged enum for serialization
(types) Allow uppercase characters for package name
(types) Allow 0 as value for Pkgrel
(alpm-types) Make BuildTool version architecture optional
(test) allow underscore in build option
Adapt documentation links to workspace locations
Use automatic instead of bare links to documentation
Properly export macro to ensure visibility
Insert empty line after list in documentation

Other

(url) Simplify the FromStr implementation of SourceUrl
Consolidate keywords in the the SEE ALSO section
(package-relation) Update specification to include soname dependencies
(types) Add alpm-sonamev2 specification
(types) Add alpm-sonamev1 specification
Switch to rustfmt style edition 2024
(cargo) Declare rust-version in the workspace not per crate
Streamline wording around keyword assignments
Add specification for ALPM package source checksum
Add specification for ALPM package source
Extend package relations with architecture specific examples
Add specification for split packages
(format) Merge imports
(types) Rename MakePkgOption -> MakepkgOption
(types) Rename Pkgver -> PackageVersion
(types) Rename Pkgrel -> PackageRelease
(types) Rename OptDepend -> OptionalDependency
(types) Rename PkgType -> PackageType
(types) Rename PkgDesc -> PackageDescription
(types) Rename PkgBase -> PackageBaseName
(types) Rename StartDir -> StartDirectory
(types) Rename BuildDir -> BuildDirectory
(package-relation) Update specification about versioned optional dependencies
(install) Add specification for .INSTALL files
(types) Change Name::new parameter from String to &str
(types) Use consistent 'Errors' section in doc comments
(types) Avoid unwrapping in code examples
(types) Link to makepkg.conf manpage for MakePkgOption
(types) Add missing documentation
(types) Update the Checksum documentation
(types) Remove incomplete type examples from README.md
(types) Allow easier conversion from ParseIntError to alpm_types::Error
(types) Use consistent doctests and comments for path module
Add/ Update links to latest project documentation
Make strum a workspace dependency
(alpm-types) Document Version::from_str()
(types) Move Packager type to openpgp module
(deps) Move testresult to workspace dependencies
(name) implement AsRef for Name
Add specification for package groups
Add specification for meta packages
(types) Use lowercase serialization for Architecture
(types) Add type aliases for checksum digests
(types) Provide a better API for creating package sources
(types) Derive Copy and Eq where possible
(types) Use consistent FromStr parameter
(types) Use consistent constructors
(types) Rename BuildToolVer to BuildToolVersion
(types) Add type aliases for AbsolutePath
(types) Add type aliases for MakePkgOption
(types) Add type aliases for i64
(version) Split buildtoolver tests
(version) Split version tests
(version) Split pkgrel tests
(version) Split pkgver tests
(version) Split version requirement tests
(version) Split version comparison tests
(error) remove MD5 checksum type
(error) use more generalized error types
(error) document the error variants
(error) add newline between variants
(specification) Add specification for package versions
(specification) Add specification for package names
(specification) Add specification for package relations
(specification) Add specification for architecture definitions
(specification) Add specification for comparison operators
(pkgversion) Simplify tests
(alpm-types) Pkgver comparison
(alpm-types) Merge Imports
Use strum macros via feature
(alpmy-types) Document the version cmp
(workspace) update deployed documentation links
(workspace) use shared workspace metadata
Add specification for epoch as alpm-epoch
Add specification for pkgrel as alpm-pkgrel
Add specification for pkgver as alpm-pkgver
(workspace) move more dependencies to workspace
Bump MSRV to 1.70.0
Unify and bump workspace dependencies
Do not run doc test for private method
Add cargo-machete metadata for md-5 crate
Apply rustfmt configuration to codebase
Adapt alpm-types cargo configuration to workspace
(license) Relicense project as Apache-2.0 OR MIT
Parse version number with differing components

0.4.0 - 2023-11-17

Bug Fixes

(Cargo.toml) Update MSRV to 1.67.1 - (66d3e47) - David Runge
(deps) update rust crate regex to 1.10.2 - (bf3423b) - renovate
(deps) update rust crate strum_macros to 0.25.2 - (47f9071) - renovate
(deps) update rust crate strum to 0.25.0 - (e988113) - renovate
Increase the MSRV to 1.65.0 as let..else is in use - (21bd1ca) - David Runge
make version types' fields public - (3fe4b5d) - Xiretza
make *Size field public - (302362c) - Xiretza
Epoch: take &str instead of String - (df875ae) - Xiretza
do not allow arbitrary first characters in version strings - (ce1e923) - Xiretza
simplify BuildOption parsing - (e07b675) - Xiretza
derive PartialEq implementation for Version - (0cc94e8) - Xiretza
simplify Version parsing - (959a694) - Xiretza
avoid unnecessary string allocations in Version Display - (6813580) - Xiretza
Relicense README under the terms of GFDL-1.3-or-later. - (58494dc) - David Runge

Continuous Integration

Verify that the advertised MSRV can be used. - (cd08b09) - David Runge
Add renovate.json - (9adf80a) - renovate
Actually publish the documentation. - (483a19d) - David Runge
Publish development documentation on archlinux.page - (220c487) - David Runge
Do not run semver check if commits lead to no change in version - (980cafa) - David Runge
Do not store artifacts for build job - (0b7e894) - David Runge
Split checks into separate jobs and do not rely on script anymore. - (d888106) - David Runge
Use default before_script instead of extending from .prepare job - (b51bbf6) - David Runge
Only run cargo semver-checks if there are commits requiring a new version - (ae15fc0) - David Runge

Documentation

Add information on where to find documentation. - (78d6271) - David Runge
Clarify licensing of documentation contribution. - (ffdb0f0) - David Runge
Add GFDL-1.3-or-later license - (b74f1fd) - David Runge
Add links to mailing list and IRC channel to contributing guidelines - (7ba5841) - David Runge
Add security policy - (3cf22d2) - David Runge

Features

add #![forbid(unsafe_code)] - (7451249) - Xiretza
add more BuildOption tests - (08c22a5) - Xiretza

Miscellaneous Chores

(deps) update rust crate proptest to 1.4.0 - (0ac0208) - renovate
(deps) update rust crate rstest to 0.18.1 - (61e083f) - renovate
Upgrade dependencies - (9b3c2b2) - David Runge

Refactoring

Replace chrono with time - (e3b8922) - Óscar García Amor

0.3.0 - 2023-06-11

Continuous Integration

Enable releasing to crates.io via CI - (e74334a) - David Runge

Documentation

Add example for Filename, Source and SourceLocation to README - (e3df355) - David Runge
Add example for VersionComparison and VersionRequirement to README - (b9ef3c5) - David Runge
No longer manually break long lines in README and contributing guidelines - (af3fea2) - David Runge

Features

Derive Clone for BuildTool - (32d9315) - David Runge
Derive Clone for PkgType - (83bbed5) - David Runge
Derive Clone for Installed - (8968d7b) - David Runge
Derive Clone for SchemaVersion - (679f03d) - David Runge
Derive Clone for BuildToolVer - (05a510f) - David Runge
Derive Clone for Architecture - (75a50c0) - David Runge
Add from strum::ParseError for Error - (0b682e1) - David Runge
Add default Error variant for generic issues. - (e6f6a64) - David Runge
add Source type - (8853d34) - Xiretza
add VersionComparison and VersionRequirement types - (1f493ae) - Xiretza
make Version Clone - (67b5fcc) - Xiretza
Add Checksum type to generically support checksum algorithms - (f1a6b57) - David Runge

Miscellaneous Chores

Deprecate Md5Sum in favor of Checksum - (50f6f74) - David Runge

Tests

Guard against breaking semver using cargo-semver-checks - (757ac72) - David Runge

0.2.0 - 2023-06-01

Bug Fixes

(SchemaVersion) Use semver:Version as SemverVersion to prevent name clash - (1725d10) - David Runge
Sort Error variants alphabetically - (19ba3ed) - David Runge
Use String for initialization where possible - (b693cfc) - David Runge
Remove implementations of Deref - (1011148) - David Runge
Apply NewType pattern for all types wrapping one other type - (883526f) - David Runge

Documentation

(BuildDir) Add example in README. - (a0eee64) - David Runge
Fix all code examples in README. - (1b87592) - David Runge
Split examples into sections based on modules - (f4e929a) - David Runge
Add documentation for Error::InvalidVersion and fix for SchemaVersion - (ad7eaac) - David Runge
Reference 'deny' at the CONTRIBUTING.md - (15c7352) - Leonidas Spyropoulos

Features

(Version) Add method to create Version with Pkgrel - (25b1001) - David Runge
Add StartDir type - (c2e02b9) - David Runge
Add Installed type - (9b3c92b) - David Runge
Implement BuildToolVer type - (6276f82) - David Runge
Derive Architecture from Ord and PartialOrd to allow comparison. - (d9eae8d) - David Runge
Include README.md as top-level documentation - (ab8d882) - David Runge
Add Version type - (967cdc8) - David Runge
Implement BuildDir type - (b50c34e) - Leonidas Spyropoulos
Use cargo deny instead of only cargo audit in CI and tests - (c28c48f) - David Runge
Add BuildOption, BuildEnv and PackageOption types - (a22506b) - David Runge
Add BuildTool type to describe a buildtool name - (a67b54f) - David Runge
Use Newtype pattern for Name type and use Ord and PartialOrd macros - (66e744a) - David Runge
Add Packager type - (be30773) - David Runge
Add SchemaVersion type - (10fc69a) - David Runge

Miscellaneous Chores

(lib) Sort imports by std/external/alphabetically. - (55dfadf) - David Runge

Refactoring

Move environmen related types to separate module - (5442732) - David Runge
Move package related types to separate module - (860ecb6) - David Runge
Move system related types to separate module - (28b3662) - David Runge
Move checksum related types to separate module - (1eec013) - David Runge
Move date related types to separate module - (a15dafb) - David Runge
Move size related types to separate module - (e194bc1) - David Runge
Move name related types to separate module - (9314901) - David Runge
Move path related types to separate module - (b14ba8b) - David Runge
Move version related types to separate module - (078c77b) - David Runge

0.1.0 - 2023-04-04

Continuous Integration

Add check scripts and Gitlab CI integration - (a301b04) - David Runge

Documentation

correct path for quick-check.sh - (06c36ee) - Leonidas Spyropoulos

Features

Limit chrono features to avoid audit RUSTSEC-2020-0071 - (a32127f) - Leonidas Spyropoulos
Implement Md5sum type - (6ab68a8) - Leonidas Spyropoulos
Increase MSRV to 1.60.0 - (150c878) - David Runge
Implement Name type - (335d13c) - David Runge
Implement PkgType - (540746d) - David Runge
Use rstest to parametrize tests - (44b7644) - David Runge
Use thiserror to remove Error boilerplate - (14620dd) - David Runge
Replace enum boilerplate with strum - (d6fc661) - David Runge
Add initial types (Architecture, BuildDate, CompressedSize, InstalledSize) - (2deba0f) - David Runge

Miscellaneous Chores

Publish to crates.io locally (not from CI) - (a0e6b54) - David Runge
Change CI scripts to LGPL-3.0-or-later - (8995c51) - David Runge

File format specifications

Specifications for various file formats are provided in the context of the components that make use of them and are located in a component's resources/specification/ directory.

The specifications are provided as specially formatted markdown files which can be rendered to section 5 manpages.

Several versions of specifications may exist side-by-side, but only the latest version is actively supported. Legacy versions of specifications may be deprecated and removed as needed, if they hinder further development.

NAME

alpm-install-scriptlet – a custom install script for ALPM based packages.

DESCRIPTION

An optional shell script that defines custom actions to be performed during the installation, upgrade, or removal of a package.

The shell functions are executed in the root (/) of the system, so all paths inside of it must be absolute.

Such files are located at the root of ALPM packages and are named .INSTALL.

General Format

An alpm-install-scriptlet may contain zero or more specific shell functions that define actions for different package lifecycle events. All of the functions are optional and only those necessary for a given package may be included.

The script may be written in a shell language that supports the -c commandline option and calling named functions with additional arguments from the interpreter's commandline interface.

Note that the shell interpreter used by package management software to run the script is defined globally (e.g. per distribution). No shebang is used in the script and the decision on which shell to use for running it is not based on a package's metadata, but instead typically set at the distribution or system level. This implies that the shell interpreter cannot be changed on a per-package basis.

Functions

The available functions are listed below. They accept one or two arguments which are package versions, provided as alpm-package-version.

pre_install

Executed before a package is installed, with the new package version as its argument.

post_install

Executed after a package is installed, with the new package version as its argument.

pre_upgrade

Executed before a package is upgraded, with the following arguments:

New package version
Old package version

post_upgrade

Executed after a package is upgraded, with the following arguments:

New package version
Old package version

pre_remove

Executed before a package is removed, with the old package version as its argument.

post_remove

Executed after a package is removed, with the old package version as its argument.

EXAMPLES

Example of specifying an install script in the PKGBUILD file:

install=example.install

Example of a basic example.install script:

pre_install() {
    echo "Preparing to install package version $1"
}

post_install() {
    echo "Package version $1 installed"
}

pre_upgrade() {
    echo "Preparing to upgrade from version $2 to $1"
}

post_upgrade() {
    echo "Upgraded from version $2 to $1"
}

pre_remove() {
    echo "Preparing to remove package version $1"
}

post_remove() {
    echo "Package version $1 removed"
}

NAME

ALPM-MTREE - Package directory hierarchy description format.

DESCRIPTION

The mtree format is a textual format that describes the hierarchy and metadata of files in a directory.

mtree is a well-known format that can, for example, be used for installation instructions or to verify files' metadata and the hierarchy of a directory.

The ALPM-MTREE format adheres to the official mtree specification. However, .MTREE files used in the context of ALPM packages only use a subset of the official mtree format that makes sense in the scope of packaging.

Properties

.MTREE files that're generated by makepkg only contain the following properties:

type
uid
gid
mode
time
size
md5
sha256
link

Furthermore, as mtree files are used in the scope of Arch Linux packaging and always relate to files inside of Arch Linux packages. Due to this, all paths inside an ALPM-MTREE must be relative to the package, except link destinations, which may point outside of a package.

Path Type Property

In contrast to all available types in mtree, ALPM-MTREE only allows three file types:

dir A directory
file A file
link A symbolic link

The other types are forbidden, as they should not be included in package.

Required Fields by File Type

ALPM-MTREE requires specific values to be set for certain file types, which is something mtree doesn't enforce by spec.

The dir path type requires the following properties to be set:

path
uid
gid
mode
time

The file path type requires the following properties to be set:

path
uid
gid
mode
size
md5_digest
sha256_digest
time

The link path type requires the following properties to be set:

path
uid
gid
mode
link
time

Usage in Pacman

In Pacman ALPM-MTREE files are solely used to verify that installed files are identical to the original files without having to keep the original package around. .MTREE files are implicitly generated and included when creating packages via makepkg. The gzip-compressed .MTREE file is located in the root of ALPM based packages

Versioning

The ALPM-MTREE format exists in multiple versions. The information in this document is for version 2, which is the current version. It has been introduced with the release of pacman 6.1.0 on 2024-03-04.

Changes since the last version

The md5 field is no longer generated, effectively making this a breaking change.

EXAMPLES

#mtree
/set type=file uid=0 gid=0 mode=644
./.BUILDINFO time=1696727741.0 size=5574 sha256digest=708be566788a6a2712bcd40425d93761569ede07371781374edb1f22e2a3eb96
./.PKGINFO time=1696727741.0 size=830 sha256digest=3aa17bec02b34c157e7c739c62e0e37a9d19f1459d404d7c6f2c14c6008127cd
/set mode=755 type=dir
./usr time=1731613789.0
./usr/bin time=1731613789.0
./usr/bin/resolvconf time=1731613789.0 mode=777 type=link link=resolvectl

Generation

ALPM's mtree files are generated by calling:

bsdtar \
  --format=mtree \
  --options='!all,use-set,type,uid,gid,mode,time,size,sha256,link' \
  $folder

Usages

In the context of ALPM and pacman, the mtree file's main purpose is to provide a performant way of getting a package's file metadata without having to extract and read the whole package.

This data is then used to verify installed files on the target system against the original files from the package. Take a look at pacman's query check functionality for more detail.

NAME

ALPM-MTREE - Package directory hierarchy description format.

DESCRIPTION

The mtree format is a textual format that describes the hierarchy and metadata of files in a directory.

mtree is a well-known format that can, for example, be used for installation instructions or to verify metadata of files and the hierarchy of a directory.

Properties

.MTREE files that're generated by makepkg only contain the following properties:

type
uid
gid
mode
time
size
md5
sha256
link

.MTREE files are used in the scope of ALPM based packages and usually relate to files inside of those respective packages. Due to this, all paths provided in an ALPM-MTREE must be relative to the package root, with the exception of link destinations, which may also represent absolute paths.

Path Type Property

In contrast to all available types in mtree, ALPM-MTREE only allows three file types:

dir A directory
file A file
link A symbolic link

Other file types must not be used, as they represent hardware specific, or ad hoc types, that should not be included in a package.

Required Fields by File Type

ALPM-MTREE requires specific values to be set for certain file types, which is something mtree doesn't enforce by specification.

The dir path type requires the following properties to be set:

path
uid
gid
mode
time

The file path type requires the following properties to be set:

path
uid
gid
mode
size
md5_digest
sha256_digest
time

The link path type requires the following properties to be set:

path
uid
gid
mode
link
time

Usage in Pacman

Versioning

The ALPM-MTREE format exists in multiple versions. The information in this document is for version 1, which is outdated. The ALPM-MTREE version 1 format has been introduced with the release of pacman 4.6.0 on 2012-04-30.

EXAMPLES

#mtree
/set type=file uid=0 gid=0 mode=644
./.BUILDINFO time=1696727741.0 size=5574 md5digest=04a85103d4780101c710a297aae33837 sha256digest=708be566788a6a2712bcd40425d93761569ede07371781374edb1f22e2a3eb96
./.PKGINFO time=1696727741.0 size=830 md5digest=bde30355e5b95a86c59afbd149cc28da sha256digest=3aa17bec02b34c157e7c739c62e0e37a9d19f1459d404d7c6f2c14c6008127cd
set mode=755 type=dir
./usr time=1731613789.0
./usr/bin time=1731613789.0
./usr/bin/resolvconf time=1731613789.0 mode=777 type=link link=resolvectl
```

## Generation

ALPM's mtree files are generated by calling:

```sh
bsdtar \
  --format=mtree \
  --options='!all,use-set,type,uid,gid,mode,time,size,md5,sha256,link' \
  $folder

Usages

In the context of ALPM and pacman, the mtree file's main purpose is to provide a performant way of getting a package's file metadata without having to extract and read the whole package.

This data is then used to verify installed files on the target system against the original files from the package. Take a look at pacman's query check functionality for more detail.

NAME

ALPM-MTREE - Package directory hierarchy description format.

DESCRIPTION

The mtree format is a textual format that describes the hierarchy and metadata of files in a directory.

mtree is a well-known format that can, for example, be used for installation instructions or to verify files' metadata and the hierarchy of a directory.

Properties

.MTREE files that're generated by makepkg only contain the following properties:

type
uid
gid
mode
time
size
md5
sha256
link

Path Type Property

In contrast to all available types in mtree, ALPM-MTREE only allows three file types:

dir A directory
file A file
link A symbolic link

The other types are forbidden, as they should not be included in package.

Required Fields by File Type

ALPM-MTREE requires specific values to be set for certain file types, which is something mtree doesn't enforce by spec.

The dir path type requires the following properties to be set:

path
uid
gid
mode
time

The file path type requires the following properties to be set:

path
uid
gid
mode
size
md5_digest
sha256_digest
time

The link path type requires the following properties to be set:

path
uid
gid
mode
link
time

Usage in Pacman

Versioning

Changes since the last version

The md5 field is no longer generated, effectively making this a breaking change.

EXAMPLES

#mtree
/set type=file uid=0 gid=0 mode=644
./.BUILDINFO time=1696727741.0 size=5574 sha256digest=708be566788a6a2712bcd40425d93761569ede07371781374edb1f22e2a3eb96
./.PKGINFO time=1696727741.0 size=830 sha256digest=3aa17bec02b34c157e7c739c62e0e37a9d19f1459d404d7c6f2c14c6008127cd
/set mode=755 type=dir
./usr time=1731613789.0
./usr/bin time=1731613789.0
./usr/bin/resolvconf time=1731613789.0 mode=777 type=link link=resolvectl

Generation

ALPM's mtree files are generated by calling:

bsdtar \
  --format=mtree \
  --options='!all,use-set,type,uid,gid,mode,time,size,sha256,link' \
  $folder

Usages

In the context of ALPM and pacman, the mtree file's main purpose is to provide a performant way of getting a package's file metadata without having to extract and read the whole package.

This data is then used to verify installed files on the target system against the original files from the package. Take a look at pacman's query check functionality for more detail.

NAME

BUILDINFO - Information on package build environments for ALPM based packages (version 2).

DESCRIPTION

The BUILDINFO format is a textual format that describes a package's build environment. Such files are located at the root of ALPM packages, are named .BUILDINFO and are usually used to reproduce the environment in which a package has been build. For further information refer to Arch Linux's reproducible builds effort[1].

The BUILDINFO format exists in multiple versions. The information in this document is for version 2, which is the current version and has been introduced with the release of pacman 6.0.0 on 2021-05-20.

Changes since the last version

The new keywords buildtool and buildtoolver have been added to track the package name, version and architecture of the tool used to setup the build environment for a package.

General Format

A BUILDINFO file consists of a series of lines, each providing information on an aspect of the build environment of a package, or the file format itself. Leading whitespace is always ignored.

Unless noted otherwise, the information contained in a BUILDINFO file is considered to be covered by the set of the 95 printable ASCII characters.

Keywords

Each line encodes information that represents one keyword assignment. All keyword assignments consist of a key from the following list immediately followed by a whitespace, an '=' sign, another whitespace and a value.

By default, exactly one keyword assignment must be present per keyword in a BUILDINFO. As exception to this rule, the keywords buildenv, options and installed may be provided zero or more times.

format

The BUILDINFO file format version. The value must be a plain positive integer. This must be 2 for BUILDINFO version 2.

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

The base name of the package. This keyword reflects the name of the sources from which the package is built. If the sources of the package are used to build a single package, the value is the same as that of pkgname. If the sources of the package are used to build several packages, the value may differ from that of pkgname (see PKGBUILD PACKAGE SPLITTING for further information). The value is covered by the same rules as that of pkgname (e.g. example).

pkgver

The full version of the package. Note, that this is not to be confused with alpm-pkgver, which only represents a subset of this keyword! The value is an alpm-package-version, either in full or in full with epoch form (e.g. 1.0.0-1 or 1:1.0.0-1, respectively).

pkgarch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

pkgbuild_sha256sum

The hex representation of the SHA-256 checksum of the PKGBUILD used to build the package. The value must be covered by the set of hexadecimal characters and must be 64 characters long (e.g. 946d8362de3cebe3c86765cb36671a1dfd70993ac73e12892ac7ac5e6ff7ef95).

packager

The User ID of the entity, that built the package. The value is meant to be used for identity lookups and represents an OpenPGP User ID[2]. As such, the value is a UTF-8-encoded string, that is conventionally composed of a name and an e-mail address, which aligns with the format described in RFC 2822[3] (e.g. John Doe <john@example.org>).

builddate

The date at which the build of the package started. The value must be numeric and represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

builddir

The absolute directory path in which the package has been built by the build tool (e.g. makepkg). The value is a UTF-8-encoded string and must represent a valid absolute directory (e.g. /builddir).

startdir

The directory from which makepkg was executed. The value is a UTF-8-encoded string and must represent a valid absolute directory (e.g. /startdir).

buildtool

The package name of the tool used to set up the build environment. This helps the Arch Linux's Reproducible Builds effort to reproduce the environment in which a package has been built. The value must be a valid package name as described in pkgname.

buildtoolver

The full version of the buildtool used to set up the build environment. The value may take one of two forms:

An alpm-package-version in full or in full with epoch form (e.g. 1.0.0-1 or 1:1.0.0-1, respectively), directly followed by a '-' sign, directly followed by an alpm-architecture (e.g. 1.0.0-1-any or 1:1.0.0-1-any, respectively).. This format is commonly used by Arch Linux's build tools.
An alpm-package-version in minimal or minimal with epoch form (e.g. 1.0.0 or 1:1.0.0, respectively). This format is commonly used by makepkg.

buildenv

A build environment used by the package build tool (i.e. makepkg, defined in BUILDENV of makepkg.conf) when building the package. This keyword may be assigned zero or more times. The value must be a unique word, optionally prefixed by a single '!', which indicates the negation of the environment (e.g. color or !color).

options

An option used by the package build tool (i.e. makepkg, defined in OPTIONS of makepkg.conf) when building the package. This keyword may be assigned zero or more times. The value must be a unique word, optionally prefixed by a single '!', which indicates the negation of the option (e.g. debug or !debug).

installed

The information about an installed package during build time of the package. This keyword may be assigned zero or more times. The value represents a composite string, composed of an alpm-package-name, directly followed by a '-' sign, directly followed by an alpm-package-version (in full or in full in epoch form), directly followed by a '-' sign, followed by an alpm-architecture (e.g. example-1:1.0.0-1-x86_64).

EXAMPLES

format = 2
pkgname = example
pkgbase = example
pkgver = 1:1.0.0-1
pkgarch = any
pkgbuild_sha256sum = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
packager = John Doe <john@example.org>
builddate = 1729181726
builddir = /build
startdir = /startdir/
buildtool = devtools
buildtoolver = 1:1.2.1-1-any
buildenv = !color
buildenv = check
options = !strip
options = staticlibs
installed = other-package-1:0.5.0-3-any
installed = package2-2.1.0-6-x86_64

NOTES

Arch Linux's Reproducible Builds effort

https://wiki.archlinux.org/title/Reproducible_builds
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822

NAME

BUILDINFO - Information on package build environments for ALPM based packages (version 1).

DESCRIPTION

The BUILDINFO format exists in multiple versions. The document describes version 1, which is a legacy version and has been introduced with the release of pacman 5.1.0 on 2018-05-28. For the latest specification, refer to BUILDINFO.

General Format

A BUILDINFO file consists of a series of lines, each providing information on an aspect of the build environment of a package, or the file format itself. Leading whitespace is always ignored.

Unless noted otherwise, the information contained in a BUILDINFO file is considered to be covered by the set of the 95 printable ASCII characters.

Keywords

format

The BUILDINFO file format version. The value must be a plain positive integer. This must be 1 for BUILDINFO version 1.

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

pkgver

pkgarch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

pkgbuild_sha256sum

packager

builddate

The date at which the build of the package started. The value must be numeric and represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

builddir

buildenv

options

installed

EXAMPLES

format = 1
pkgname = example
pkgbase = example
pkgver = 1:1.0.0-1
pkgarch = any
pkgbuild_sha256sum = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
packager = John Doe <john@example.org>
builddate = 1729181726
builddir = /build
buildenv = !color
buildenv = check
options = !strip
options = staticlibs
installed = other-package-1:0.5.0-3-any
installed = package2-2.1.0-6-x86_64

NOTES

Arch Linux's Reproducible Builds effort

https://wiki.archlinux.org/title/Reproducible_builds
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822

NAME

BUILDINFO - Information on package build environments for ALPM based packages (version 2).

DESCRIPTION

Changes since the last version

The new keywords buildtool and buildtoolver have been added to track the package name, version and architecture of the tool used to setup the build environment for a package.

General Format

A BUILDINFO file consists of a series of lines, each providing information on an aspect of the build environment of a package, or the file format itself. Leading whitespace is always ignored.

Unless noted otherwise, the information contained in a BUILDINFO file is considered to be covered by the set of the 95 printable ASCII characters.

Keywords

format

The BUILDINFO file format version. The value must be a plain positive integer. This must be 2 for BUILDINFO version 2.

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

pkgver

pkgarch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

pkgbuild_sha256sum

packager

builddate

The date at which the build of the package started. The value must be numeric and represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

builddir

startdir

The directory from which makepkg was executed. The value is a UTF-8-encoded string and must represent a valid absolute directory (e.g. /startdir).

buildtool

buildtoolver

The full version of the buildtool used to set up the build environment. The value may take one of two forms:

An alpm-package-version in full or in full with epoch form (e.g. 1.0.0-1 or 1:1.0.0-1, respectively), directly followed by a '-' sign, directly followed by an alpm-architecture (e.g. 1.0.0-1-any or 1:1.0.0-1-any, respectively).. This format is commonly used by Arch Linux's build tools.
An alpm-package-version in minimal or minimal with epoch form (e.g. 1.0.0 or 1:1.0.0, respectively). This format is commonly used by makepkg.

buildenv

options

installed

EXAMPLES

format = 2
pkgname = example
pkgbase = example
pkgver = 1:1.0.0-1
pkgarch = any
pkgbuild_sha256sum = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
packager = John Doe <john@example.org>
builddate = 1729181726
builddir = /build
startdir = /startdir/
buildtool = devtools
buildtoolver = 1:1.2.1-1-any
buildenv = !color
buildenv = check
options = !strip
options = staticlibs
installed = other-package-1:0.5.0-3-any
installed = package2-2.1.0-6-x86_64

NOTES

Arch Linux's Reproducible Builds effort

https://wiki.archlinux.org/title/Reproducible_builds
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822

NAME

PKGINFO - Information on ALPM based packages (version 2).

DESCRIPTION

The PKGINFO format is a textual format that describes package metadata. Such files are located at the root of ALPM packages and are named .PKGINFO. They are used e.g. by package managers to evaluate and present the context for a package within its ecosystem. Use-cases include the representation of common metadata and the relation to other packages.

The PKGINFO format exists in multiple versions. The information in this document is for version 2, which is the current version and has been introduced with the release of pacman 6.1.0 on 2024-03-04.

General Format

A PKGINFO file consists of a series of lines, each providing information on an aspect of a package. Lines starting with a '#' sign are comments and are always ignored. Leading whitespace is always ignored.

Unless noted otherwise, the information contained in a PKGINFO file is considered to be covered by the set of the 95 printable ASCII characters[1].

Changes since the last version

The new keyword xdata has been added to track extra data for a package.

Keywords

By default, exactly one keyword assignment must be present per keyword in a PKGINFO. As exception to this rule, the keywords license, replaces, group, conflict, provides, backup, depend, optdepend, makedepend and checkdepend may be provided zero or more times. As additional exception, the keyword xdata is provided one or more times.

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

xdata

The extra data associated with the package. This keyword must be assigned once to define a specific value, but may be provided several times after that to provide further extra data. The value is a UTF-8-encoded string, that represents another key-value pair, delimited by a '=' sign (e.g. key=value).

A PKGINFO must contain an xdata keyword assignment that defines a pkgtype assignment in its value (e.g. pkgtype=pkg). The valid pkgtype values are debug (for debug packages), pkg (for single packages), src (for source packages) and split (for split packages).

Additional xdata keyword assignments may be provided following the general rules around formatting of its values.

pkgver

pkgdesc

The description of the package. The value is a UTF-8 string, zero or more characters long (e.g. A project used for something). No specific rules about the value exist, but it is suggested to be "short" and to not contain the package name (see pkgname).

url

The URL for the project of the package. The value is a valid URL or an empty string (e.g. https://example.org).

builddate

The date at which the build of the package started. The value must be numeric and must represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

packager

The User ID of the entity that built the package. The value is meant to be used for identity lookups and represents an OpenPGP User ID[2]. As such, the value is a UTF-8-encoded string, that is conventionally composed of a name and an e-mail address, which aligns with the format described in RFC 2822[3] (e.g. John Doe <john@example.org>).

size

The size of the (uncompressed and unpacked) package contents in bytes. The value is a non-negative integer representing the absolute size of the contents of the package, with multiple hardlinked files counted only once (e.g. 181849963).

arch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

license

A license that applies for the package. This keyword may be assigned zero or more times. The value represents a license identifier, which is a string of non-zero length (e.g. GPL). Although no specific restrictions are enforced for the value aside from its length, it is highly recommended to rely on SPDX license expressions (e.g. GPL-3.0-or-later or Apache-2.0 OR MIT). See SPDX License List[4] for further information.

replaces

Another virtual component or package, that the package replaces upon installation. This keyword may be assigned zero or more times. The value is an alpm-package-relation of type replacement (e.g. example or example=1.0.0).

group

An arbitrary string, that denotes a distribution-wide group the package is in. Groups are made use of e.g. by package managers to group packages and allow to bulk install them, or by other software to display information on these related packages. This keyword may be assigned zero or more times. The value is represented by a UTF-8 string. Although it is possible to use a UTF-8 string, it is highly recommended to rely on the pkgname format for the value instead, as package managers may use group to install an entire group of packages.

conflict

Another virtual component or package, that the package conflicts with. This keyword may be assigned zero or more times. The value is an alpm-package-relation of type conflict (e.g. example or example=1.0.0).

provides

Another virtual component or package, that the package provides. This keyword may be assigned zero or more times. The value is an alpm-package-relation of type provision (e.g. example or example=1.0.0).

backup

A relative file path of a file in the package, that denotes a file for the package manager to keep backups for in case it changes or is deleted during a package update action (see pacman '.pacnew' and '.pacsave' files). This keyword may be assigned zero or more times. The value must be a valid relative Unix file path (e.g. etc/package.conf).

depend

A run-time dependency of the package (virtual component or package). This keyword may be assigned zero or more times. The value is an alpm-package-relation of type run-time dependency (e.g. example or example=1.0.0).

optdepend

An optional dependency of the package (virtual component or package). This keyword may be assigned zero or more times. The value is an alpm-package-relation of type optional dependency (e.g. example or example: this is a description).

makedepend

A build time dependency of the package (virtual component or package). This keyword may be assigned zero or more times. The value is an alpm-package-relation of type build dependency (e.g. example or example=1.0.0).

checkdepend

A dependency for running tests of the package's upstream project. This keyword may be assigned zero or more times. The value is an alpm-package-relation of type test dependency (e.g. example or example=1.0.0).

EXAMPLES

pkgname = example
pkgbase = example
xdata = pkgtype=pkg
pkgver = 1:1.0.0-1
pkgdesc = A project that does something
url = https://example.org
builddate = 1729181726
packager = John Doe <john@example.org>
size = 181849963
arch = any
license = GPL-3.0-or-later
license = LGPL-3.0-or-later
replaces = other-package>0.9.0-3
group = package-group
group = other-package-group
conflict = conflicting-package<1.0.0
conflict = other-conflicting-package<1.0.0
provides = some-component
provides = some-other-component=1:1.0.0-1
backup = etc/example/config.toml
backup = etc/example/other-config.txt
depend = glibc
depend = gcc-libs
optdepend = python: for special-python-script.py
optdepend = ruby: for special-ruby-script.rb
makedepend = cmake
makedepend = python-sphinx
checkdepend = extra-test-tool
checkdepend = other-extra-test-tool

NOTES

printable ASCII characters

https://en.wikipedia.org/wiki/ASCII#Printable_characters
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822
SPDX License List

https://spdx.org/licenses/

NAME

PKGINFO - Information on ALPM based packages (version 1).

DESCRIPTION

The PKGINFO format exists in multiple versions. This document describes version 1, which is a legacy version and has been introduced with the release of pacman 5.1.0 on 2018-05-28. For the latest specification, refer to PKGINFO.

General Format

Unless noted otherwise, the information contained in a PKGINFO file is considered to be covered by the set of the 95 printable ASCII characters[1].

Keywords

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

pkgver

pkgdesc

url

The URL for the project of the package. The value is a valid URL or an empty string (e.g. https://example.org).

builddate

The date at which the build of the package started. The value must be numeric and must represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

packager

size

arch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

license

replaces

group

conflict

provides

backup

depend

optdepend

makedepend

checkdepend

EXAMPLES

pkgname = example
pkgbase = example
pkgver = 1:1.0.0-1
pkgdesc = A project that does something
url = https://example.org
builddate = 1729181726
packager = John Doe <john@example.org>
size = 181849963
arch = any
license = GPL-3.0-or-later
license = LGPL-3.0-or-later
replaces = other-package>0.9.0-3
group = package-group
group = other-package-group
conflict = conflicting-package<1.0.0
conflict = other-conflicting-package<1.0.0
provides = some-component
provides = some-other-component=1:1.0.0-1
backup = etc/example/config.toml
backup = etc/example/other-config.txt
depend = glibc
depend = gcc-libs
optdepend = python: for special-python-script.py
optdepend = ruby: for special-ruby-script.rb
makedepend = cmake
makedepend = python-sphinx
checkdepend = extra-test-tool
checkdepend = other-extra-test-tool

NOTES

printable ASCII characters

https://en.wikipedia.org/wiki/ASCII#Printable_characters
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822
SPDX License List

https://spdx.org/licenses/

NAME

PKGINFO - Information on ALPM based packages (version 2).

DESCRIPTION

General Format

Unless noted otherwise, the information contained in a PKGINFO file is considered to be covered by the set of the 95 printable ASCII characters[1].

Changes since the last version

The new keyword xdata has been added to track extra data for a package.

Keywords

pkgname

The name of the package. The value is an alpm-package-name (e.g. example).

pkgbase

xdata

Additional xdata keyword assignments may be provided following the general rules around formatting of its values.

pkgver

pkgdesc

url

The URL for the project of the package. The value is a valid URL or an empty string (e.g. https://example.org).

builddate

The date at which the build of the package started. The value must be numeric and must represent the seconds since the Epoch, aka. 'Unix time' (e.g. 1729181726).

packager

size

arch

The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and '_' (e.g. x86_64 or any).

license

replaces

group

conflict

provides

backup

depend

optdepend

makedepend

checkdepend

EXAMPLES

pkgname = example
pkgbase = example
xdata = pkgtype=pkg
pkgver = 1:1.0.0-1
pkgdesc = A project that does something
url = https://example.org
builddate = 1729181726
packager = John Doe <john@example.org>
size = 181849963
arch = any
license = GPL-3.0-or-later
license = LGPL-3.0-or-later
replaces = other-package>0.9.0-3
group = package-group
group = other-package-group
conflict = conflicting-package<1.0.0
conflict = other-conflicting-package<1.0.0
provides = some-component
provides = some-other-component=1:1.0.0-1
backup = etc/example/config.toml
backup = etc/example/other-config.txt
depend = glibc
depend = gcc-libs
optdepend = python: for special-python-script.py
optdepend = ruby: for special-ruby-script.rb
makedepend = cmake
makedepend = python-sphinx
checkdepend = extra-test-tool
checkdepend = other-extra-test-tool

NOTES

printable ASCII characters

https://en.wikipedia.org/wiki/ASCII#Printable_characters
OpenPGP User ID

https://openpgp.dev/book/certificates.html#user-ids
RFC 2822

https://www.rfc-editor.org/rfc/rfc2822
SPDX License List

https://spdx.org/licenses/

NAME

SRCINFO - Information on sources of ALPM based packages.

DESCRIPTION

The SCRINFO format is a textual format that describes package source metadata. Such files are named .SRCINFO and located at the root of source repositories from which ALPM based packages are built. They are created from PKGBUILD files to allow safe metadata parsing in scenarios where using bash is not an option. The SRCINFO format is used by applications such as repository management software and custom web frontends to evaluate and present the source information of packages.

General Format

A SRCINFO file consists of a series of lines, each providing information on an aspect of the sources of one or several packages (see alpm-split-package for information on split packages). Lines starting with a '#' sign are treated as comments and are always ignored. Empty lines are always ignored. Leading whitespace is always ignored.

Unless noted otherwise, the information contained in a SRCINFO file is considered to be covered by the set of the 95 printable ASCII characters[1].

The file format distinguishes between section headers introducing specific sections and keyword assignments that can be used in those sections. Each line encodes information that either represents one section header or one keyword assignment.

The SRCINFO format requires the definition of a single pkgbase and one or more pkgname sections. While the pkgbase section contains metadata shared by all packages built from a PKGBUILD, the pkgname sections are used to declare package metadata and provide overrides that are specific for each respective package.

Section headers

All section headers consist of a key, immediately followed by a whitespace, an '=' sign, another whitespace and a value.

The section header for a pkgbase section must use the word 'pkgbase' as key and an alpm-package-name as value. Exactly one such section header must exist in a SRCINFO file at the beginning of the file.

The section header for a pkgname section must use the word 'pkgname' as key and an alpm-package-name as value. At least one such section header must exist in a SRCINFO file (one for each package built from a PKGBUILD), but only after a pkgbase section header.

Sections

The pkgbase section must at least contain assignments for the pkgver and pkgrel keywords, and may otherwise also contain all other known keyword assignments. Keyword assignments present in this section also apply to all pkgname sections.

A pkgname section may have zero or more keyword assignments. It must not contain assignments for the epoch, pkgver, pkgrel, or validpgpkeys keywords, nor any keyword assignments representing build or test dependency declarations (see alpm-package-relation for details), source declarations (see alpm-package-source for details) or checksum declarations (see alpm-package-source-checksum for details). Keyword assignments in a pkgname section only apply to the specific package that the section describes. More specifically, all keyword assignments in a pkgname section are used to unset, extend or override the keyword assignments found in the pkgbase section. The following rules apply:

A keyword that has been previously defined in the pkgbase section and may be used in a pkgname section can be
- unset by assigning an empty value to it (e.g. the pkgbase section defines depends = bash and the pkgname section defines depends =), or
- overridden by defining it again (e.g. the pkgbase section defines depends = bash and the pkgname section defines depends = zsh).
All keywords that allow multiple assignments and that may be used in a pkgname section can be extended by first adding all keyword assignments found in the pkgbase section and afterwards adding further keyword assignments in a pkgname section (e.g. the pkgbase section defines depends = bash and the pkgname section defines depends = bash and depends = bash-completion).

Further rules may apply depending on keyword.

Keywords

All keyword assignments are defined as a key from the following list immediately followed by a whitespace, an '=' sign, another whitespace and a value.

By default, exactly one keyword assignment may be present per keyword in a SRCINFO. As exception to this rule, the keywords arch, backup, checkdepends, conflicts, depends, groups, license, makedepends, optdepends, options, provides, replaces, as well as the source related keywords noextract, source, validpgpkeys, b2sums, md5sums, sha1sums, sha224sums, sha256sums, sha384sums and sha512sums may be provided zero or more times.

By default keyword assignments apply to all targeted alpm-architectures. Some keywords may also be provided in architecture-specific ways by appending an '_' sign, directly followed by an alpm-architecture (all except any) - see each keyword section for details. These architecture-specific keyword assignments only apply to the architecture they target.

pkgdesc

The description of the package. This keyword assignment may be provided zero or one times in the pkgbase and/or in each pkgname section. The value is a UTF-8 string, zero or more characters long (e.g. A project used for something). No specific rules about the value exist, but it is suggested to be "short" and to not contain the package name (see alpm-package-name).

pkgver

The pkgver package version component for the package(s) (see alpm-pkgver for further information on the expected value). This keyword assignment must be provided once, exclusively in the pkgbase section.

The value is an alpm-pkgver (e.g. 1.0.0 or 1:1.0.0).

pkgrel

The pkgrel package version component for the package(s) (see alpm-pkgrel for further details on the expected value).

This keyword assignment must be provided once, exclusively in the pkgbase section.

epoch

The optional epoch package version component for the package(s) (see alpm-epoch for further details on the expected value).

This keyword assignment may be provided zero or one time, exclusively in the pkgbase section.

url

The URL for the project of the package. This keyword assignment may be provided zero or one times in the pkgbase and/or in each pkgname section.

The value is a valid URL or an empty string (e.g. https://example.org).

install

The name of an alpm-install-scriptlet that is used for pre and post actions when installing, upgrading or uninstalling a package. This keyword assignment may be provided zero or one times in the pkgbase and/or in each pkgname section.

The value must be a UTF-8 string, that represents a relative file path (e.g. scriptlet.install).

changelog

The name of file containing changelog information for a package. This keyword assignment may be provided zero or one times in the pkgbase and/or in each pkgname section.

The value must be a UTF-8 string, that represents a relative file path (e.g. pkg.changelog).

arch

An architecture that applies for a pkgname section. This keyword assignment may be provided one or more times in the pkgbase and zero or more times in each pkgname section.

The value is an alpm-architecture (e.g. x86_64 or any). The following rules apply, if this keyword is used multiple times:

each value must be unique
if the value any is used, no other value can be used alongside it, as it implies that a pkgname may be used on any architecture (which logically excludes being used only on a specific architecture)

groups

An arbitrary string, that denotes a distribution-wide group the package is in (see alpm-package-group). Groups are used e.g. by package managers to group packages and allow to bulk install them, or by other software to display information on these related packages.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is represented by a UTF-8 string. Although it is possible to use a UTF-8 string, it is highly recommended to rely on the alpm-package-name format for the value instead, as package managers may use groups to install an entire group of packages.

license

A license that applies for the package(s).

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value represents a license identifier, which is a string of non-zero length (e.g. GPL). Although no specific restrictions are enforced for the value aside from its length, it is highly recommended to rely on SPDX license expressions (e.g. GPL-3.0-or-later or Apache-2.0 OR MIT). See SPDX License List[5] for further information.

checkdepends

A dependency for running tests of the package's upstream project. An architecture-specific checkdepends may be specified using a keyword consisting of 'checkdepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. checkdepends_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. The value is an alpm-package-relation of type test dependency (e.g. example or example=1.0.0).

makedepends

A build time dependency of the package (virtual component or package). An architecture-specific makedepends may be specified using a keyword consisting of 'makedepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. makedepends_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. The value is an alpm-package-relation of type build dependency (e.g. example or example=1.0.0).

depends

A run-time dependency of the package (virtual component or package). An architecture-specific depends may be specified using a keyword consisting of 'depends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. depends_aarch64.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is an alpm-package-relation of type run-time dependency (e.g. example or example=1.0.0).

optdepends

An optional dependency of the package (virtual component or package). An architecture-specific optdepends may be specified using a keyword consisting of 'optdepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. optdepends_aarch64.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is an alpm-package-relation of type optional dependency (e.g. example or example: this is a description).

provides

Another virtual component or package, that the package provides. An architecture-specific provides may be specified using a keyword consisting of 'provides', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. provides_aarch64.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is an alpm-package-relation of type provision (e.g. example or example=1.0.0).

conflicts

Another virtual component or package, that the package conflicts with. An architecture-specific conflicts may be specified using a keyword consisting of 'conflicts', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. conflicts_aarch64.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is an alpm-package-relation of type conflict (e.g. example or example=1.0.0).

replaces

Another virtual component or package, that the package replaces upon installation. An architecture-specific replaces may be specified using a keyword consisting of 'replaces', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. replaces_aarch64.

This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value is an alpm-package-relation of type replacement (e.g. example or example=1.0.0).

noextract

A local source file name (see alpm-package-source) of a file that should not be extracted during package building. Each value must represent the valid local file name of an existing source keyword assignment (e.g. source = https://example.org/project-1.0.0.tar.gz and noextract = project-1.0.0.tar.gz). A file matching the provided filename is not automatically extracted during package building, even if it is a compressed file (e.g. example.tar.gz or example.zip). An architecture-specific noextract may be specified using a keyword consisting of 'noextract', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. noextract_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section.

options

An option used by the package build tool (i.e. makepkg, defaults are defined in OPTIONS of makepkg.conf) when building the package. This keyword assignment may be provided zero or more times either in the pkgbase or in a pkgname section.

The value must be a unique word, optionally prefixed by a single '!', which indicates the negation of the option (e.g. debug or !debug). If the keyword assignment is used in a pkgname section, the value of the first occurrence may be empty, which indicates, that for the respective package none of the options defined in the pkgbase section apply.

backup

A relative file path of a file in a given package, that denotes a file for the package manager to keep backups for in case it changes or is deleted during a package update action (see pacman '.pacnew' and '.pacsave' files). This keyword assignment may be provided zero or more times in the pkgbase as well as in each pkgname section. The value must be a valid relative Unix file path (e.g. etc/package.conf).

source

A (remote or local) source used in the packaging process of the package(s) (see alpm-package-source for further details on the allowed value), that are automatically extracted if they represent compressed files (unless a noextract value matching the file name exists). An architecture-specific source may be specified using a keyword consisting of 'source', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. source_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section.

validpgpkeys

An OpenPGP fingerprint[2] which may be used for the validation of OpenPGP signatures[3] created for one or more alpm-package-sources (i.e. a source keyword assignment).

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. It must be used at least once if

one alpm-package-source value makes use of the signed URL fragment
or if there is one alpm-package-source ending with .sig, that equals another without that file ending
or if there is one alpm-package-source ending with .sign, that matches another without that file ending and all compression algorithm specific file endings (e.g. .xz or .zst) removed

The value is a 40 char long hexadecimal string (e.g 0123456789abcdef0123456789abcdef01234567). Although possible, it is strongly discouraged to use the non-unique, legacy OpenPGP Key ID[4] representation, a 16 char long hexadecimal string (e.g. 89abcdef01234567)

md5sums

An MD5[6] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific md5sums may be specified using a keyword consisting of 'md5sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. md5sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many md5sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the md5sums keyword assignments (i.e. the first md5sums keyword assignment provides data for the first source keyword assignment, etc.).

sha1sums

A SHA-1[7] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific sha1sums may be specified using a keyword consisting of 'sha1sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. sha1sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many sha1sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the sha1sums keyword assignments (i.e. the first sha1sums keyword assignment provides data for the first source keyword assignment, etc.).

sha224sums

A SHA-224[8] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific sha224sums may be specified using a keyword consisting of 'sha224sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. sha224sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many sha224sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the sha224sums keyword assignments (i.e. the first sha224sums keyword assignment provides data for the first source keyword assignment, etc.).

sha256sums

A SHA-256[8] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific sha256sums may be specified using a keyword consisting of 'sha256sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. sha256sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many sha256sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the sha256sums keyword assignments (i.e. the first sha256sums keyword assignment provides data for the first source keyword assignment, etc.).

sha384sums

A SHA-384[8] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific sha384sums may be specified using a keyword consisting of 'sha384sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. sha384sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many sha384sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the sha384sums keyword assignments (i.e. the first sha384sums keyword assignment provides data for the first source keyword assignment, etc.).

sha512sums

A SHA-512[8] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific sha512sums may be specified using a keyword consisting of 'sha512sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. sha512sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many sha512sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the sha512sums keyword assignments (i.e. the first sha512sums keyword assignment provides data for the first source keyword assignment, etc.).

b2sums

A BLAKE2[9] hash digest of a file provided by name in a source value, or the special string 'SKIP' (see alpm-package-source-checksum for further details on the allowed value). An architecture-specific b2sums may be specified using a keyword consisting of 'b2sums', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. b2sums_aarch64.

This keyword assignment may be provided zero or more times, exclusively in the pkgbase section. If it is used, the SRCINFO must contain as many b2sums keyword assignments as there are source keyword assignments (the same applies for the architecture-specific variant of this keyword). The ordering of accompanying source keyword assignments dictate the ordering of the b2sums keyword assignments (i.e. the first b2sums keyword assignment provides data for the first source keyword assignment, etc.).

EXAMPLES

Split packages, extending, overriding and unsetting of keywords

pkgbase = example
  pkgdesc = An example package
  pkgver = 1.0.0
  pkgrel = 1
  epoch = 1
  url = https://example.org
  arch = any
  license = GPL-3.0-or-later
  checkdepends = extra-test-tool
  checkdepends = other-extra-test-tool
  makedepends = cmake
  makedepends = python-sphinx
  depends = glibc
  depends = gcc-libs
  source = https://example.org/example-1.0.0.tar.gz
  sha512sums = 8b41e1b78ad11521113c52ff182a1b8e0a195754aa527fcd00a411620b46f20ffffb8088ccf85497121ad4499e0845b876f6dd6640088a2f0b2d8a600bdf4c0c
  b2sums = cb79bf658b69dff0acf721232455a461598dd26ed42047bd0362e7fbd796093145a694c1a6bcdcf5bf7f866d78f009c14bf456be0f944283829a6e33cedf2aef

pkgname = example
  # overrides the pkgdesc for the example package
  pkgdesc = A project that does something
  groups = package-group
  # extends the license for the example package
  license = GPL-3.0-or-later
  license = LGPL-3.0-or-later
  optdepends = python: for special-python-script.py
  optdepends = example-docs: for documentation
  provides = some-component
  conflicts = conflicting-package<1.0.0
  replaces = other-package>0.9.0-3
  backup = etc/example/config.toml

pkgname = example-docs
  # overrides the pkgdesc for the example-docs package
  pkgdesc = A project that does something - documentation
  # overrides the license for the example-docs package
  license = CC-BY-SA-4.0
  # unsets the dependencies for the example-docs package
  depends =

The above example represents a SRCINFO file that describes two split packages (see alpm-split-package for more details). Both pkgname sections override the pkgdesc keyword assignment. The first pkgname section additionally extends the license keyword specification from the pkgbase section and adds further package-specific keyword assignments (e.g. replaces, groups, conflicts, provides, backup, optdepends). The second pkgname section overrides the license keyword assignment and unsets the depends keyword assignment.

Package data, per architecture

The following minimal PKGBUILD defines a package for two alpm-architectures.

pkgname=example
pkgver=0.1.0
pkgrel=1
pkgdesc="An example package"
arch=(x86_64 aarch64)
url="https://example.org"
license=(GPL-3.0-or-later)
depends=(bash)
depends_x86_64=(zsh)

package() {
  pkgdesc+=" - extra info"
  depends_x86_64+=(nushell)
  depends_aarch64=(sh)
}

This PKGBUILD is represented by the following SRCINFO:

pkgbase = example
  pkgdesc = An example package
  pkgver = 0.1.0
  pkgrel = 1
  url = https://example.org
  arch = x86_64
  arch = aarch64
  license = GPL-3.0-or-later
  depends = bash
  depends_x86_64 = zsh

pkgname = example
  pkgdesc = An example package - extra info
  depends_x86_64 = zsh
  depends_x86_64 = nushell
  depends_aarch64 = sh

Depending on targeted alpm-architecture, the package data will differ when fully resolving all keywords.

For aarch64:

pkgdesc = An example package - extra info
pkgver = 0.1.0
pkgrel = 1
url = https://example.org
arch = aarch64
license = GPL-3.0-or-later
depends = bash
depends = sh

For x86_64:

pkgdesc = An example package - extra info
pkgver = 0.1.0
pkgrel = 1
url = https://example.org
arch = x86_64
license = GPL-3.0-or-later
depends = bash
depends = zsh
depends = nushell

NOTES

printable ASCII characters

https://en.wikipedia.org/wiki/ASCII#Printable_characters
OpenPGP fingerprint

https://openpgp.dev/book/certificates.html#fingerprint
OpenPGP signatures

https://openpgp.dev/book/signing_data.html
OpenPGP Key ID

https://openpgp.dev/book/glossary.html#term-Key-ID
SPDX License List

https://spdx.org/licenses/
MD5

https://en.wikipedia.org/wiki/MD5
SHA-1

https://en.wikipedia.org/wiki/SHA-1
SHA-2

https://en.wikipedia.org/wiki/SHA-2
BLAKE2

https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2

Concept specifications

Specifications for common fields, composite types and concepts are provided by the alpm-types component in its resources/specification/ directory.

The specifications are provided as specially formatted markdown files which can be rendered to section 7 manpages.

NAME

architecture - architecture definition for ALPM based packages.

DESCRIPTION

The architecture format is a custom string format that contains CPU instruction set architectures[1] and further identifiers and is used for representing the architecture of ALPM based packages. This format is used in build scripts or file formats for package metadata (e.g. in PKGBUILD, BUILDINFO, PKGINFO) to describe the architecture of a package, or the architecture of dependency packages.

The architecture format comprises values defined by convention. The values are custom keywords, most of which are derived directly from CPU instruction set architectures[1] or specific microarchitectures.

The architecture value must be covered by the set of alphanumeric characters and '_'.

EXAMPLES

The below architecture values all relate to specific CPU instruction set architectures[1] or microarchitectures and can be used to specify a package architecture. This usually means that packages of a specific architecture can only be used in a particular context.

"any"

A package can be used on any hardware as its contents are not specific to any architecture.

"x86_64"

A package can only be used on hardware compatible with the x86-64[2] instruction set version 1 and above (see x86-64 microarchitecture levels[3]).

"x86_64_v2"

A package can only be used on hardware compatible with the x86-64[2] instruction set version 2 and above (see x86-64 microarchitecture levels[3]).

"x86_64_v3"

A package can only be used on hardware compatible with the x86-64[2] instruction set version 3 and above (see x86-64 microarchitecture levels[3]).

"x86_64_v4"

A package can only be used on hardware compatible with the x86-64[2] instruction set version 4 and above (see x86-64 microarchitecture levels[3]).

"i686"

A package can only be used on hardware compatible with the IA-32[4] instruction set version 6 (aka. P6[5], or 'i686'). This architecture is considered legacy.

"i486"

A package can only be used on hardware compatible with the IA-32[4] instruction set version 4 (aka. i486[6]). This architecture is considered legacy.

"pentium4"

A package can only be used on hardware compatible with the Pentium 4[7] microarchitecture. This architecture is considered legacy.

"armv7"

A package can only be used on hardware compatible with the ARMv7 architecture family[8]. This architecture is considered legacy.

"armv8"

A package can only be used on hardware compatible with the ARMv8 architecture family[9].

"aarch64"

A package can only be used on hardware compatible with the AArch64[10] (64-bit execution state of the ARM architecture family[11]).

"riscv64"

A package can only be used on hardware compatible with the 64-bit variant of the RISC-V[12] instruction set architecture (ISA[13]).

"loong64"

A package can only be used on hardware compatible with the 64-bit variant of the LoongArch[14] instruction set architecture (ISA[13]).

NOTES

CPU instruction set architectures

https://en.wikipedia.org/wiki/Comparison_of_instruction_set_architectures#Instruction_sets
x86-64

https://en.wikipedia.org/wiki/X86-64
x86-64 microarchitecture levels

https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels
IA-32

https://en.wikipedia.org/wiki/IA-32
P6

https://en.wikipedia.org/wiki/P6_(microarchitecture)
i486

https://en.wikipedia.org/wiki/I486
pentium4

https://en.wikipedia.org/wiki/Pentium_4
ARMv7 architecture family

https://en.wikipedia.org/wiki/ARM_architecture_family#32-bit_architecture
ARMv8 architecture family

https://en.wikipedia.org/wiki/ARM_architecture_family#Armv8
AArch64

https://en.wikipedia.org/wiki/AArch64
ARM architecture family

https://en.wikipedia.org/wiki/ARM_architecture_family
RISC-V

https://en.wikipedia.org/wiki/RISC-V
ISA

https://en.wikipedia.org/wiki/Instruction_set_architecture
LoongArch

https://en.wikipedia.org/wiki/Loongson#LoongArch

NAME

comparison - comparison statements for ALPM based packages.

DESCRIPTION

The comparison format is a version comparison format, that is used for representing version comparison statements for ALPM based packages in a composite comparison expression. This format is used in build scripts or file formats for package metadata (e.g. in PKGBUILD or PKGINFO) to describe version bounds for a package relation.

A comparison statement uses one of the following comparison operators to specify a version bound relation:

< (less than)
<= (less than or equal to)
= (equal to)
>= (greater than or equal to)
> (greater than)

Composite comparison expressions

Composite comparison expressions consist of an alpm-package-name, directly followed by a comparison operator, directly followed by an alpm-package-version.

Matching comparison expressions

Name matching is performed based on a full string match using the alpm-package-name component of the composite comparison expression.

Version comparison is performed based on components of a composite version string (see e.g. alpm-epoch, alpm-pkgver and alpm-pkgrel). As alpm-package-version offers several forms, this allows for matching a variety of scenarios.

When providing the full or full with epoch form of the alpm-package-version format, it matches exactly one specific release of a package version. When providing the minimal or minimal with epoch form of the alpm-package-version format, it matches any release of a package version.

Depending on comparison operator, the given match towards alpm-package-name and alpm-package-version is narrow (i.e. =), wide with lower bound (i.e. >, >=) or wide with upper bound (i.e. <, <=).

EXAMPLES

The below composite comparison expressions can be matched by a package named example in specific versions:

"example<1.0.0"

A version less than '1.0.0' (e.g. '0.8.0-1').

"example<=1.0.0"

A version less than or equal to '1.0.0' (e.g. '0.8.0-1' or '1.0.0-3').

"example<=1.0.0-1"

A version less than or equal to '1.0.0-1' (e.g. '0.8.0-1' or '1.0.0-1', but '1.0.0-2' does not work).

"example=1.0.0"

Any version '1.0.0' (e.g. '1.0.0-1' or '1.0.0-2', etc.).

"example=1.0.0-1"

The version '1.0.0-1'.

"example=1:1.0.0-1"

The version '1:1.0.0-1'.

"example>=1.0.0"

A version greater than or equal to '1.0.0' (e.g. '1.0.0-1' or '1.1.0-1').

"example>1.0.0"

A version greater than '1.0.0' (e.g. '1.1.0-1' or '1:1.0.0-1').

NAME

epoch - version prefix to enforce a higher version consideration for ALPM based packages.

DESCRIPTION

The epoch format is a version format, that is used as prefix to pkgver in a composite version string. This format is used in build scripts or file formats for package data description or reproduction to indicate, that a composite version is to be considered newer than one without or a lower epoch component. This enables package maintainers to release downgraded versions of a package if needed.

The epoch value is represented by a non-negative integer and is considered to default to '0' if unset.

When used in a composite version string, epoch is directly followed by a ':' sign and the pkgver.

If two composite version strings are sorted, they are first sorted based on their epoch component and only afterwards based on their pkgver component.

As general rule, the sorting precedence is: epoch > pkgver.

EXAMPLES

The explicit 1 epoch component in the right hand composite version string overrules the implicit 0 epoch component of the left hand composite version string. Since the epoch takes precedence, 1:0.9.0 is considered "newer" than 1.0.0 even though the upstream version represented by the pkgver component is older.

"1.0.0" < "1:0.9.0"

Composite version strings with the same pkgver component are also sorted according to their epoch component first.

"1:1.0.0" < "2:1.0.0"

NAME

meta package - an ALPM based package that solely defines package relations.

DESCRIPTION

Meta packages refer to ALPM based packages that do not provide files, but instead only define package relations. They are used for defining the required package relations of an abstract scenario or use-case (e.g. "packages for a minimum system installation" or "all packages needed for a special development environment").

Meta packages are handled like any other ALPM based package by a package manager and require their various package relations upon installation. A -meta suffix may be used in the alpm-package-name to more easily distinguish meta packages from other packages.

EXAMPLES

The following PKGBUILD example defines a meta package, that upon installation pulls in the bash and gcc-libs packages:

pkgname=example-meta
pkgver=0.1.0
pkgrel=1
pkgdesc="A meta package example"
arch=(any)
url="https://archlinux.org"
license=('GPL-3.0-or-later')
depends=(
  bash
  gcc-libs
)

NAME

package - a package based on Arch Linux Package Management (ALPM) concepts.

DESCRIPTION

ALPM based packages refer to (optionally compressed) tar archives that contain package files. Package files encompass mandatory metadata files as well as optional scripts and data files.

Package files are created from package sources (i.e. PKGBUILD) using package build software (e.g. makepkg). For Arch Linux specific package build software refer to devtools and pkgctl.

Package management software (e.g. pacman) relies on metadata files and scripts for the purpose of dependency resolution and installation. Data files can be installed on compatible target systems using package management software.

FORMAT

Uncompressed ALPM based package files follow the following naming scheme:

An alpm-package-name directly followed by a '-' sign, directly followed by an alpm-package-version (in the full or full with epoch form), directly followed by a '-' sign, directly followed by an alpm-architecture, directly followed by the string '.pkg.tar', e.g.:

example-1.0.0-1-any.pkg.tar
example-1.0.0-1-x86_64.pkg.tar

Compression

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:

.bz2 for bzip2 compression (e.g. example-1.0.0-1-x86_64.pkg.tar.bz2)
.gz for gzip compression (e.g. example-1.0.0-1-x86_64.pkg.tar.gz)
.lz for lzip compression (e.g. example-1.0.0-1-x86_64.pkg.tar.lz)
.lz4 for lz4 compression (e.g. example-1.0.0-1-x86_64.pkg.tar.lz4)
.lrz for lrzip compression (e.g. example-1.0.0-1-x86_64.pkg.tar.lrz)
.lzo for lzop compression (e.g. example-1.0.0-1-x86_64.pkg.tar.lzo)
.xz for xz compression (e.g. example-1.0.0-1-x86_64.pkg.tar.xz)
.Z for compression based on adaptive Lempel-Ziv coding (e.g. example-1.0.0-1-x86_64.pkg.tar.Z), see the compress command
.zst for zstd compression (e.g. example-1.0.0-1-x86_64.pkg.tar.zst)

Handling of compression technologies is specific to the package build tool. Refer to COMPRESSBZ2, COMPRESSGZ, COMPRESSLRZ, COMPRESSLZ, COMPRESSLZ4, COMPRESSLZO, COMPRESSXZ, COMPRESSZ, COMPRESSZST and PKGEXT in makepkg.conf for compression options and package extensions used in makepkg.

Digital signatures

Digital signatures can be created for package files.

Currently, only OpenPGP detached signatures over the package file are supported. Detached signatures carry the same name as the package file for which they are created, with an additional .sig suffix (e.g. example-1.0.0-1-x86_64.pkg.tar.zst.sig is the digital signature for a package file example-1.0.0-1-x86_64.pkg.tar.zst).

The contents of an ALPM based package are distinguished between metadata, scripts and data files.

Metadata

The following files must be present at the root of an ALPM based package:

.BUILDINFO: a BUILDINFO file
.MTREE: an ALPM-MTREE file
.PKGINFO: a PKGINFO file

The above files provide relevant metadata for the installation, upgrade and uninstallation of packages on a target system (see alpm-package-relation for details on dependency resolution), as well as reproducibly building a bit-by-bit identical package from the same sources (see reproducible builds[2]).

Scripts

Optionally, an alpm-install-scriptlet named .INSTALL may be present at the root of an ALPM based package.

Data

Zero or more data files may be present in an ALPM based package (refer to alpm-meta-package for details on why packages may not contain any data files).

All existing data files of a package are extracted to the root directory[3] of a target system upon installation of the package.

No specific rules exist on which data files (and directories) are allowed as contents of a package, but it is advisable to adhere to common standards such as the systemd File Hierarchy Requirements[4] and/or the Filesystem Hierarchy Standard[5] and by default have all files and directories be owned by root. In conclusion, it is best practice to never package files in directories that contain user data (e.g. below /home).

More specific guidelines around the validation of data files in packages are subject to the implementer's discretion (e.g. a distribution using ALPM).

EXAMPLES

The following example PKGBUILD defines the package example which only creates a single data file (plus the directories in which it is located):

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

Assuming makepkg is used to build a package from above PKGBUILD and is configured to use zstd for compression, the resulting package file is called example-1.0.0-1-any.pkg.tar.zst.

The package file contents can be examined as follows:

$ 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

NOTES

OpenPGP detached signatures

https://openpgp.dev/book/signing_data.html#detached-signatures
reproducible builds

https://reproducible-builds.org/
root directory

https://en.wikipedia.org/wiki/Root_directory
systemd File Hierarchy Requirements

https://systemd.io/SYSTEMD_FILE_HIERARCHY_REQUIREMENTS/
Filesystem Hierarchy Standard

https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard

NAME

package group - package grouping for ALPM based packages.

DESCRIPTION

Package groups describe arbitrary grouping for ALPM based packages. They are used in build scripts or file formats for package metadata (e.g. in PKGBUILD, PKGINFO or SRCINFO) to describe the groups a package belongs to. Package groups can be used for a number of reasons (e.g. "a group of all providers of a feature", "a group of all text editors") and no specific guidelines exist. Software such as package managers can rely on package groups to list grouped packages and install as well as uninstall them in bulk.

The value is represented by a UTF-8 string (e.g. my-group or my-other-group). Although it is possible to use a UTF-8 string, it is recommended limit the value to the alpm-package-name format. Package managers may use a package group to install an entire group of packages and group names containing special characters or whitespaces may be confusing to users.

Visibility of groups

Package groups solely exist as package metadata and any package can be in zero or more of them. In the context of package management, package groups represent identifiers, that are visible across available package repositories, as they are defined by their members.

Caveats when relying on groups for installation

Package groups can be used by package managers to bulk install all ALPM based packages that are currently members of a given group. Although in effect similar to meta packages when it comes to the bulk installation of packages, package groups are not package relations and are solely defined as a grouping mechanism! When further packages are added to a given group, this does not result in them being installed automatically, as package management software merely evaluates the members of a group during a given installation action. Aside from reinstalling all members of a group, there is no mechanism to stay in sync with the current members of a package group.

EXAMPLES

The following PKGBUILD example defines a package that belongs to the group my-group. Note that the created package carries the group name in its metadata (see PKGINFO for details).

pkgname=group-example
pkgver=0.1.0
pkgrel=1
pkgdesc="A package example"
arch=(any)
url="https://archlinux.org"
license=('GPL-3.0-or-later')
groups=(my-group)
depends=(bash)

package() {
  install -vdm 755 "$pkgdir/usr/share/doc/$pkgname/"
  touch "$pkgdir/usr/share/doc/$pkgname/test.txt"
}

NAME

package name - package and virtual component names for ALPM based packages.

DESCRIPTION

The package name format represents package and component names for ALPM based packages. This format is used in build scripts or file formats for package metadata (e.g. in PKGBUILD, PKGINFO, SRCINFO, alpm-repo-desc, or alpm-lib-desc) to describe package or component names, and package relations.

While the package name format is mostly used to describe existing packages, it can also be used to name entirely virtual components. A virtual component is specified implicitly using an alpm-package-relation.

The value must be covered by the set of alphanumeric characters and '@', '.', '_', '+', '-', but it must not start with '-' or '.' (e.g. example is valid).

EXAMPLES

"package-name"

NAME

package relation - package relationships for ALPM based packages.

DESCRIPTION

Package relations describe relationships between ALPM based packages for various scenarios. They are used in build scripts or file formats for package metadata (e.g. in PKGBUILD, PKGINFO or SRCINFO) to describe relationships of packages to other packages. Software such as package managers or package build software rely on package relations to resolve dependency graphs, e.g. when installing or uninstalling packages.

Packages and virtual components

Any package relation may contain an alpm-package-name, which may be used to refer to an existing package or a virtual component. Virtual components do not represent the names of existing packages, but instead a component that is implicitly defined by package metadata. With the help of package relations, virtual components are defined and used similarly to names of existing packages (see EXAMPLES for further information).

Sonames

A package relation of type provision or run-time dependency may contain an alpm-soname that represents a hard dependency based on a specific shared object in a package. They are used to encode compatibility guarantees between ELF[1] and shared object files with the help of soname[2] data (see EXAMPLES for further information).

Architecture specific use

Package relations may be used in contexts that can describe multiple alpm-architectures at the same time. For these situations, architecture-specific identifiers are available and may be used.

Types of package relations

The definition of a package relation is bound to a set of types. Which keywords and what data structures are used for each type depends on the context they are used in.

Run-time dependency

A run-time dependency of a package. This package relation specifies a hard requirement (another package, optionally in a specific version), that must be present when using a given package.

The value for a run-time dependency is either an alpm-package-name, an alpm-comparison or an alpm-soname (e.g. example, example>=1.0.0, or lib:libexample.so.1, respectively).

In PKGBUILD files zero or more run-time dependencies of a package are specified using the depends array. Architecture-specific run-time dependencies may be specified using an array named 'depends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. depends_aarch64.
In PKGINFO files the depend keyword is used to specify a run-time dependency.
In SRCINFO files the depends keyword is used to specify a run-time dependency. An architecture-specific run-time dependency may be specified using a keyword consisting of 'depends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. depends_aarch64.

Build dependency

A build-time dependency of a package. This package relation specifies a build requirement (another package, optionally in a specific version), that must be present when building a given package.

The value for a build dependency is either an alpm-package-name or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more build-time dependencies of a package are specified using the makedepends array. Architecture-specific build dependencies may be specified using an array named 'makedepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. makedepends_aarch64.
In PKGINFO files the makedepend keyword is used to specify a build-time dependency.
In SRCINFO files the makedepends keyword is used to specify a build-time dependency. An architecture-specific build dependency may be specified using a keyword consisting of 'makedepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. makedepends_aarch64.

Test dependency

A package dependency, that is only required when running the tests of the package. This package relation specifies a test requirement (another package, optionally in a specific version), that must be present when running the tests of a given package.

The value for a test dependency is either an alpm-package-name or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more test dependencies of a package are specified using the checkdepends array. Architecture-specific test dependencies may be specified using an array named 'makedepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. checkdepends_aarch64.
In PKGINFO files the checkdepend keyword is used to specify a test dependency.
In SRCINFO files the checkdepends keyword is used to specify a test dependency. An architecture-specific test dependency may be specified using a keyword consisting of 'checkdepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. checkdepends_aarch64.

Optional dependency

A package dependency, that provides optional functionality for a package but is otherwise not required during run-time. This package relation specifies a requirement (another package with optional version constraints and an optional description) that is only needed to enable optional functionality of a given package.

The value for an optional dependency can be one of the following:

An alpm-package-name (e.g., example) or an alpm-comparison (e.g., example>=1.2.3)
An alpm-package-name or alpm-comparison followed by a : sign, a whitespace, and a UTF-8-formatted description string that specifies the reason for the optional dependency (e.g., example: for feature X or example>=1.2.3: for feature X). Note that newline (\n) and carriage return (\r) control characters are not allowed in the description string.

In PKGBUILD files zero or more optional dependencies of a package are specified using the optdepends array. Architecture-specific optional dependencies may be specified using an array named 'optdepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. optdepends_aarch64.
In PKGINFO files the optdepend keyword is used to specify an optional dependency.
In SRCINFO files the optdepends keyword is used to specify an optional dependency. An architecture-specific optional dependency may be specified using a keyword consisting of 'optdepends', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. optdepends_aarch64.

Provision

This package relation specifies a component name (an alpm-package-name, a virtual component, or an alpm-soname) that is provided by a given package. The use of a provision allows for scenarios in which e.g. several packages provide the same component, allowing package managers to provide a choice.

The value for a provision is either an alpm-package-name, an alpm-comparison, or an alpm-soname (e.g. example, example>=1.0.0, or lib:libexample.so.1, respectively).

In PKGBUILD files zero or more provisions are specified using the provides array. Architecture-specific provisions may be specified using an array named 'provides', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. provides_aarch64.
In PKGINFO files the provides keyword is used to specify a provision.
In SRCINFO files the provides keyword is used to specify a provision. An architecture-specific provision may be specified using a keyword consisting of 'provides', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. provides_aarch64.

Conflict

This package relation specifies a component name (which may also be a package name), that a given package conflicts with. A conflict is usually used to ensure that package managers are not able to install two packages, that provide the same files.

The value for a conflict is either an alpm-package-name or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more conflicts are specified using the conflicts array. Architecture-specific conflicts may be specified using an array named 'conflicts', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. conflicts_aarch64.
In PKGINFO files the conflict keyword is used to specify a conflict.
In SRCINFO files the conflicts keyword is used to specify a conflict. An architecture-specific conflict may be specified using a keyword consisting of 'conflicts', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. conflicts_aarch64.

Replacement

A package relation that specifies which other component or package a given package replaces upon installation. The feature is used e.g. by package managers to replace existing packages or virtual components if they are e.g. renamed or superseded by another project offering the same functionality.

The value for a replacement is either an alpm-package-name or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more replacements are specified using the replaces array. Architecture-specific replacements may be specified using an array named 'replaces', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. replaces_aarch64.
In PKGINFO files the replaces keyword is used to specify a conflict.
In SRCINFO files the replaces keyword is used to specify a conflict. An architecture-specific replacement may be specified using a keyword consisting of 'replaces', directly followed by an '_' sign, directly followed by an alpm-architecture (all alpm-architectures except any can be used), e.g. replaces_aarch64.

EXAMPLES

Provisions as virtual components

Mail servers working with the SMTP protocol can usually be used in several scenarios (e.g. as SMTP forwarder or server). It is commonplace to have packages that only require one of these scenarios. Given the mail server package my-mailserver, which represents a full mail server solution, it is therefore useful to define provisions for it (e.g. introducing the virtual components smtp-forwarder and smtp-server). Another mail server package - minimal-mailserver - can only be used as SMTP forwarder, so defining only one provision (i.e. introducing the virtual component smtp-forwarder) is possible.

Other packages may now depend on these virtual components, instead of one specific mail server: Given the monitoring package my-monitoring, which allows sending out monitoring mails using a local SMTP forwarder, a run-time dependency can be defined for it to depend on the virtual component smtp-forwarder.

This scenario enables a package manager to provide the user with the choice to rely on one of the providers of smtp-forwarder (i.e. my-mailserver or minimal-mailserver).

Dependencies using sonames

Some packages provide shared object files that ELF[1] files in other packages may dynamically link against.

For example, the package example may contain the following files:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

Here, the shared object file /usr/lib/libexample.so.1.0.0 encodes the soname[2] libexample.so.1.

Following the alpm-soname specification, lib:libexample.so.1 can be added as a provision to the PKGINFO file of the example package, if the library lookup directory /usr/lib is represented by the prefix lib.

Afterwards, another example package called application may contain the ELF[1] file /usr/bin/application, which dynamically links against the shared object /usr/lib/libexample.so.1 contained in the example package. The ELF[1] file encodes this requirement by relying on the soname[2] libexample.so.1.

Following the alpm-soname specification, lib:libexample.so.1 can be added as a run-time dependency to the PKGINFO file of the application package, if the library lookup directory /usr/lib is represented by the prefix lib and the shared object encoding the libexample.so.1 soname[2] (here /usr/lib/libexample.so.1.0.0) is present in the lookup directory.

Note: For legacy behavior of alpm-soname refer to alpm-sonamev1.

NOTES

ELF

https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
soname

https://en.wikipedia.org/wiki/Soname

NAME

package source - local or remote source data used for building an ALPM based package.

DESCRIPTION

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.

In PKGBUILD files a package source is defined by adding an entry to the source array. Alternatively, an array named source, directly followed by an underscore character ("_"), directly followed by an alpm-architecture (all except any) - may be used to define a source for a specific architecture (e.g. source_aarch64).

In SRCINFO files a package source is defined by assigning a value to the source keyword. 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).

Local

Local sources are defined using relative file paths (e.g. my-file.txt).

When 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). 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 PKGBUILD. This way all local source files can be tracked in a Version Control System (VCS).

Remote

Remote sources may be retrieved using various protocols, all of which 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), several VCS protocols such as bzr, fossil, git, hg and svn are understood and can be used to retrieve specific versions of remote sources.

By default, the name of the remote object defines the final local source name (e.g. 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 to repo/ - see renaming for details).

The VCS protocols expose differing optional functionalities for retrieving specific remote content. This functionality is accessed using URL fragments in the source URL.

bzr

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

bzr+https://example.org/trunk#revision=123

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.:

fossil+https://example.org/repo#branch=my-branch
fossil+https://example.org/repo#commit=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
fossil+https://example.org/repo#tag=1.0.0

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.:

git+https://example.org/repo#branch=my-branch
git+https://example.org/repo#commit=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
git+https://example.org/repo#tag=1.0.0

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.:

hg+https://example.org/repo#branch=my-branch
git+https://example.org/repo#revision=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
git+https://example.org/repo#tag=1.0.0

svn

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

svn+https://example.org/repo#revision=r123

Signature verification

OpenPGP signature verification [3] is supported when using certain types of package sources. 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 a 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.

A pair of local or static remote sources, that define a file and an accompanying detached signature file (e.g. example-1.0.0.tar.gz with example-1.0.0.tar.gz.sig, or example-1.0.0.tar.gz with example-1.0.0.tar.gz.asc, or example-1.0.0.tar.gz with example-1.0.0.tar.sign) are an indication for the need of an OpenPGP signature verification.

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).

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.

Renaming

In PKGBUILD and SRCINFO files, remote sources can be renamed. Using a target name, directly followed by '::', directly followed by the remote source name (e.g. source-1.0.0.tar.gz::https://example.com/1.0.0.tar.gz or project::git+https://git.example.com/project.git).

The renaming functionality differs between static protocols (e.g. https) and VCS protocols (e.g. git): In the former case the target name is a file and in the latter a directory (e.g. project-1.0.0.tar.gz::https://example.org/project-v1.0.0.tar.gz renames to the file project-1.0.0.tar.gz while other-name::git+https://example.org/repo#tag=v1.0.0 renames to the directory other-name/).

Extraction

By default, local and remote sources are automatically extracted by package build software such as makepkg, if (after renaming) the final source file name ending matches a known extension (e.g. .tar.gz).

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.

EXAMPLES

Local and static remote sources with renaming

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

The above PKGBUILD example defines a package source setup, in which the remote source is renamed and a local, compressed source is not extracted but instead used as is. Further, the local source custom-data.tar.gz is verified using the (assumed) detached signature file custom-data.tar.gz.sig using OpenPGP signature verification with a certificate that has the fingerprint 6d96270004515a0486bb7f76196a72b40c55a47f. The following SRCINFO file is generate from the PKGBUILD:

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

Local and VCS remote sources with renaming

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

The above PKGBUILD example defines a package source setup, in which the git based remote source is renamed and a local, compressed source is not extracted but instead used as is. 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.

The following SRCINFO file is generate from the PKGBUILD:

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

NOTES

file URI scheme

https://en.wikipedia.org/wiki/File_URI_scheme

URL

https://en.wikipedia.org/wiki/URL

OpenPGP signature verification

https://openpgp.dev/book/verification.html

OpenPGP certificates

https://openpgp.dev/book/certificates.html

OpenPGP fingerprints

https://openpgp.dev/book/certificates.html#fingerprint

NAME

package source checksum - a checksum to verify the integrity of a package source used for building an ALPM based package.

DESCRIPTION

ALPM based packages may be built using package sources and for each of them at least one valid package source checksum must exist to be able to verify the integrity of the source.

Analogous to package sources, package source checksums may be specified in a generic or an architecture-specific way.

The value of a package source checksum is either the output of a hash function[1], or the special string 'SKIP', which indicates that no checksum verification should be done for a given source.

The following hash functions[1] are supported:

MD5[2]
SHA-1[3]
SHA-224 (part of the SHA-2 [4] family)
SHA-256 (part of the SHA-2 [4] family)
SHA-384 (part of the SHA-2 [4] family)
SHA-512 (part of the SHA-2 [4] family)
BLAKE2[5]

If several package source checksums exist for a package source, they must use distinct hash functions (e.g. SHA-512 and BLAKE2). The number of package source checksums in each hash function category must always match the number of available package sources.

In PKGBUILD files a package source checksum is defined by adding a value to one of the following arrays:

md5sums (hash function: MD5)
sha1sums (hash function: SHA-1)
sha224sums (hash function: SHA-224)
sha256sums (hash function: SHA-256)
sha384sums (hash function: SHA-384)
sha512sums (hash function: SHA-512)
b2sums (hash function: BLAKE2)

Each array exclusively accepts output of the respective hash function or the special string 'SKIP' as value.

Alternatively, any of the above array names, directly followed by an underscore character ("_"), directly followed by an alpm-architecture (all except any) may be used to define a source checksum for a specific architecture (e.g. b2sums_aarch64).

In SRCINFO files a package source checksum is defined by assigning one of the following keywords a value:

md5sums (hash function: MD5)
sha1sums (hash function: SHA-1)
sha224sums (hash function: SHA-224)
sha256sums (hash function: SHA-256)
sha384sums (hash function: SHA-384)
sha512sums (hash function: SHA-512)
b2sums (hash function: BLAKE2)

Each keyword assignment exclusively accepts output of the respective hash function or the special string 'SKIP' as value.

Alternatively, any of the above keywords, directly followed by an underscore character ("_"), directly followed by an alpm-architecture (all except any) may be used to define a source checksum for a specific architecture (e.g. b2sums_aarch64).

EXAMPLES

Remote source with checksums

The above PKGBUILD example defines a package source setup in which a remote source is verified using a SHA-512 and a BLAKE2 hash. The checksum verification for the OpenPGP signature is skipped using the SKIP string.

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
)
source=($pkgname-$pkgver.tar.gz::https://download.example.org/$pkgname-v$pkgver.tar.gz{,.sig})
sha512sums=(
  0cf9180a764aba863a67b6d72f0918bc131c6772642cb2dce5a34f0a702f9470ddc2bf125c12198b1995c233c34b4afd346c54a2334c350a948a51b6e8b4e6b6
  'SKIP'
)
b2sums=(
  d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77
  'SKIP'
)
validpgpkeys=(988881ADC9FC3655077DC2D4D757D480B5EA0E11)

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

package(){
  meson install -C build --destdir "$pkgdir"
}

The PKGBUILD is represented by the following SRCINFO:

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
    source = example-0.1.0.tar.gz::https://download.example.org/example-v0.1.0.tar.gz
    sha512sums = 0cf9180a764aba863a67b6d72f0918bc131c6772642cb2dce5a34f0a702f9470ddc2bf125c12198b1995c233c34b4afd346c54a2334c350a948a51b6e8b4e6b6
    sha512sums = SKIP
    b2sums = d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77
    b2sums = SKIP

pkgname = example

Remote source with checksums for several architectures

The below PKGBUILD example defines a package source setup in which two remote sources are verified using a SHA-512 and a BLAKE2 hash each. One source is exclusively used on the x86_64 and the other exclusively on the aarch64 architecture.

pkgname=example
pkgver=0.1.0
pkgrel=1
pkgdesc="A package example"
arch=(
  aarch64
  x86_64
)
url="https://example.org"
license=(GPL-3.0-or-later)
makedepends=(meson)
depends=(
  gcc-libs
  glibc
)
source_aarch64=(
  $pkgname-$pkgver.tar.gz::https://download.example.org/$pkgname-aarch64-v$pkgver.tar.gz
)
source_x86_64=(
  $pkgname-$pkgver.tar.gz::https://download.example.org/$pkgname-x86_64-v$pkgver.tar.gz
)
sha512sums_aarch64=(
  cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063
)
sha512sums_x86_64=(
  0cf9180a764aba863a67b6d72f0918bc131c6772642cb2dce5a34f0a702f9470ddc2bf125c12198b1995c233c34b4afd346c54a2334c350a948a51b6e8b4e6b6
)
b2sums_aarch64=(
  a69cc58858cb37cf8da7f83f55c23f171ee3c59be76ad7edcf01dec36fd9d0104bb433cd863ee3f0b6a10a336cf2400688c57fd99392dc01c4585d8725547e8c
)
b2sums_x86_64=(
  d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77
)

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

package(){
  meson install -C build --destdir "$pkgdir"
}

The following SRCINFO is generated from the PKGBUILD:

pkgbase = example
    pkgdesc = A package example
    pkgver = 0.1.0
    pkgrel = 1
    url = https://example.org
    arch = aarch64
    arch = x86_64
    license = GPL-3.0-or-later
    makedepends = meson
    depends = gcc-libs
    depends = glibc
    source_aarch64 = example-0.1.0.tar.gz::https://download.example.org/example-aarch64-v0.1.0.tar.gz
    sha512sums_aarch64 = cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063
    b2sums_aarch64 = a69cc58858cb37cf8da7f83f55c23f171ee3c59be76ad7edcf01dec36fd9d0104bb433cd863ee3f0b6a10a336cf2400688c57fd99392dc01c4585d8725547e8c
    source_x86_64 = example-0.1.0.tar.gz::https://download.example.org/example-x86_64-v0.1.0.tar.gz
    sha512sums_x86_64 = 0cf9180a764aba863a67b6d72f0918bc131c6772642cb2dce5a34f0a702f9470ddc2bf125c12198b1995c233c34b4afd346c54a2334c350a948a51b6e8b4e6b6
    b2sums_x86_64 = d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77

pkgname = example

NOTES

hash function

https://en.wikipedia.org/wiki/Hash_function

MD5

https://en.wikipedia.org/wiki/MD5

SHA-1

https://en.wikipedia.org/wiki/SHA-1

SHA-2

https://en.wikipedia.org/wiki/SHA-2

BLAKE2

https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2

NAME

package version - package versions for ALPM based packages.

DESCRIPTION

The package version format represents version information for ALPM based packages. This format is used in build scripts or file formats for package metadata (e.g. in PKGBUILD, PKGINFO, SRCINFO, alpm-repo-desc, or alpm-lib-desc) to describe package versions, or component versions as part of a package relation.

The value is represented by a composite version string, which may consist of several components (alpm-epoch, alpm-pkgver, alpm-pkgrel). Various forms of composite version strings exist, but they are only used in specific contexts.

Full

The value for this form consists of an alpm-pkgver, directly followed by a '-' sign, directly followed by an alpm-pkgrel (e.g. 1.0.0-1). This alpm-package-version form is used in various scenarios, such as:

package filenames
package-relation expressions
- replaces, conflict, provides, depend, makedepend and checkdepend in PKGINFO files
pkgver in BUILDINFO files
pkgver in PKGINFO files
as part of buildtoolver in BUILDINFOv2 files
as part of installed in BUILDINFO files

Full with epoch

The value for this form consists of an alpm-epoch, directly followed by a ':' sign, directly followed by an alpm-pkgver, directly followed by a '-' sign, directly followed by an alpm-pkgrel (e.g. 1:1.0.0-1). This alpm-package-version form is used in various scenarios, such as:

package filenames
package-relation expressions
- replaces, conflict, provides, depend, makedepend and checkdepend in PKGINFO files
pkgver in BUILDINFO files
pkgver in PKGINFO files
as part of buildtoolver in BUILDINFOv2 files
as part of installed in BUILDINFO files

Minimal

The value for this form consists of an alpm-pkgver (e.g. 1.0.0). This alpm-package-version form is used in various scenarios, such as:

package-relation expressions
- replaces, conflicts, provides, depends, makedepends and checkdepends in PKGBUILD files
- replaces, conflict, provides, depend, makedepend and checkdepend in PKGINFO files
pkgver in PKGBUILD files
pkgver in SRCINFO files
as part of buildtoolver in BUILDINFOv2 files

Minimal with epoch

The value for this form consists of an alpm-epoch, directly followed by a ':' sign, directly followed by an alpm-pkgver (e.g. 1:1.0.0). This alpm-package-version form is used in various scenarios, such as:

as part of package-relation expressions
- replaces, conflicts, provides, depends, makedepends and checkdepends in PKGBUILD files
- replaces, conflict, provides, depend, makedepend and checkdepend in PKGINFO files
pkgver in PKGBUILD files
pkgver in SRCINFO files
as part of buildtoolver in BUILDINFOv2 files

EXAMPLES

"1.0.0-1"

A full package version.

"1:1.0.0-1"

A full package version with epoch.

"1.0.0"

A minimal package version.

"1:1.0.0"

A minimal package version with epoch.

NAME

pkgrel - version postfix to enforce a higher version consideration for ALPM based packages.

DESCRIPTION

The pkgrel format is a version format, that is used as postfix to pkgver in a composite version string. This format is used in build scripts or file formats for package data description or reproduction to indicate, that a composite version (e.g. BUILDINFO's pkgver) is to be considered newer than one with a lower value pkgrel component. This functionality is used in the context of distributions to release new builds of upstream software based on an upstream release of the same version. For each rebuild, the pkgrel value is incremented by '1'. Once the upstream version represented by pkgver is incremented, the pkgrel is reset to '1'.

The pkgrel value must consist of one or more numeric digits, optionally followed by a period (.) and one or more additional numeric digits. The default value when using pkgrel is '1'.

When used in a composite version string, pkgver is directly followed by a '-' sign and the pkgrel.

Compositive version strings with the same pkgver component are sorted according to their pkgrel, but epoch may be used to set higher ordering nevertheless. Hence, the sorting precedence is: epoch > pkgver > pkgrel.

EXAMPLES

Compositive version strings with the same pkgver component are sorted according to their pkgrel component.

"1.0.0-1" < "1.0.0-2"
"1.0.0-1" < "1.0.0-1.0"
"1.0.0-1.0" < "1.0.0-2.0"

An explicit epoch component is always considered before the pkgver and pkgrel components in a composite version string.

"1:1.0.0-1" > "1.0.0-2"

NAME

pkgver - upstream version information for ALPM based packages.

DESCRIPTION

The pkgver format is a version format, that is used for representing upstream version information. This format is used in build scripts or file formats for package data description or reproduction.

A pkgver value is represented by a string, consisting of ASCII characters, excluding the ':', '/', '-' or any whitespace characters. The pkgver value must be at least one character long, and must not start with a '.' sign. If an upstream version contains an invalid character, it is advised to replace it with a valid one or to remove it.

EXAMPLES

"1.0.0"

"1.0.0alpha"

NAME

split package - an ALPM based package that is built along other packages from the same package sources.

DESCRIPTION

Split packages refer to two or more ALPM based packages that are built from the same package sources. These types of packages can be created for arbitrary reasons, e.g.:

split different types of functionality (e.g. one package providing the graphical user interface and another the terminal user interface of a project)
split out specific documentation (e.g. developer documentation is not useful for all users)
various functionalities of a project are optional, are e.g. provided as plugins and can be enabled by installing additional split packages

Split packages built from the same package sources share some PKGINFO package metadata (i.e. pkgbase, pkgver, makedepends), while other metadata may be set specifically per individual split package.

All PKGINFOv2 files for split packages define one xdata value of pkgtype=split, indicating that the metadata describes a split package.

Split packages are handled like any other ALPM based package by a package manager and require their various package relations upon installation.

EXAMPLES

The following PKGBUILD example defines two split packages, that share example-split as (virtual - without any actual package of that name) pkgbase:

pkgbase=example-split
pkgname=(example-a example-b)
pkgver=0.1.0
pkgrel=1
pkgdesc="A split package example"
arch=(any)
url="https://archlinux.org"
license=(GPL-3.0-or-later)
makedepends=(
  meson
)
depends=(
  bash
  gcc-libs
)

package_example-a(){
  pkgdesc+=" - A"
  license+=(LGPL-2.1-or-later)
  depends+=(bash-completions)
}

package_example-b(){
  pkgdesc+=" - B"
  depends=(zsh)
}

NAME

soname - representation and use of soname data in ALPM based packaging.

DESCRIPTION

Sonames[1] are a mechanism to ensure binary compatibility between shared objects and their consumers (i.e. other ELF[2] files). More specifically, soname[1] data is encoded in the SONAME field of the dynamic section in shared object files and usually denotes specific information on the version of the object file. ELF[2] files may dynamically link against specific versions of shared objects and declare this dependency with the help of the NEEDED field in their dynamic section.

Strings representing soname information can be used in alpm-package-relations of type provision and run-time dependency to allow for strict package dependency setups based on ABI compatibility.

The alpm-soname format exists in multiple versions. The information in this document is for version 2, which is the current version, supersedes alpm-sonamev1 and has been introduced with the release of pacman 6.1.0 on 2024-03-04.

FORMAT

The representation of soname information exclusively takes place in file formats that may contain dynamic, build environment specific data, such as PKGINFO.

In these files soname data is referred to using the the following format, consisting of data derived from the location of a shared object file, as well as information encoded in it: A prefix string, directly followed by a ':', directly followed by a soname (e.g. lib:libexample.so.1).

Here, the prefix string lib denotes the use name (arbitrarily defined on a distribution level and used by package build tools such as makepkg) for a lookup directory (e.g. /usr/lib) in which the shared object file is found. Refer to LIB_DIRS in makepkg.conf for how prefix assignments work in makepkg.

The soname represents data found in the dynamic section of a shared object file (see readelf for details). Depending on whether the soname data is used in an alpm-package-relation of type provision or of type run-time dependency this refers to the SONAME or the NEEDED field in the dynamic section, respectively.

USAGE

A package can depend on a specific soname with the help of an alpm-package-relation of type run-time dependency, if another package provides this exact soname in their alpm-package-relation of type provision.

More specifically, a soname dependency of one package is based on the soname data of a shared object file provided by one of its dependency packages.

A package build tool (e.g. makepkg) automatically derives soname information from ELF[2] files in the build environment based on the following rules:

If the package that is built provides a shared object in one of the configured lookup directories, the value of the SONAME field in the dynamic section of the ELF[2] file is extracted. Together with the prefix assigned to the given lookup directory this data is added as a provision to the PKGINFO data for the package (e.g. provides = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib).
If the package that is built produces an ELF[2] file that dynamically links against a shared object available in the build environment, the value of the NEEDED field in the dynamic section of the ELF[2] file that is linked against is extracted. If a package containing the shared object file that encodes the soname data is present in the build environment and the package's PKGINFO data exposes this fact in an alpm-package-relation of type provision (i.e. provides = lib:libexample.so.1), this data is made use of. Together with the prefix assigned to the given lookup directory of the shared object file that provides the needed soname, this data is added as a run-time dependency to the PKGINFO data for the package being built (e.g. depend = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib).

For implementers it is strongly suggested to make this behavior configurable, as soname detection may fail or rely on soname data that may not be advisable under certain conditions. See OPTIONS of makepkg.conf for details on the autodeps feature and LIB_DIRS of makepkg.conf for details on prefix and lookup directory definitions for makepkg.

EXAMPLES

The following examples demonstrate how to expose and use soname information in ALPM-based packaging.

The examples assume building with makepkg with the autodeps feature enabled. Further, the LIB_DIRS array in makepkg.conf is expected to prefix the lookup directory /usr/lib with lib.

Providing a soname

The following example PKGBUILD for a package named example is used to build and install an upstream project that contains a shared object.

pkgname=example
pkgver=1.0.0
pkgrel=1
pkgdesc="An example library"
arch=(x86_64)
url="https://example.org/library.html"
license=(MIT)
depends=(glibc)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

This example assumes that the project results in installing the following files to the filesystem:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

Here, the file /usr/lib/libexample.so.1.0.0 encodes the soname libexample.so.1. Further, this examples assumes that the directory /usr/lib is assigned to the prefix lib.

After building from source, the resulting package file for example contains the following PKGINFO file:

pkgname = example
pkgver = 1.0.0-1
pkgdesc = An example library
url = https://example.org/library.html
builddate = 1729181726
packager = Your Name <your.name@example.org>
size = 181849963
arch = x86_64
license = MIT
provides = lib:libexample.so.1
depend = glibc

Depending on a soname

The following PKGBUILD for a package named application is used to build an upstream project that depends on the example package from the previous example. More specifically, the resulting package depends on the shared object libexample.so which is provided by the example package.

pkgname=application
pkgver=1.0.0
pkgrel=1
pkgdesc="An example application"
arch=(x86_64)
url="https://example.org/application.html"
license=(MIT)
depends=(glibc)
depends=(example)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

After building from source, the resulting package file for application contains the following PKGINFO file:

pkgname = application
pkgver = 1.0.0-1
pkgdesc = An example application
url = https://example.org/application.html
builddate = 1729181726
packager = Your Name <your@email.com>
size = 181849963
arch = x86_64
license = MIT
depend = glibc
depend = example
depend = lib:libexample.so.1

NOTES

soname

https://en.wikipedia.org/wiki/Soname
ELF

https://en.wikipedia.org/wiki/Executable_and_Linkable_Format

NAME

soname - representation and use of soname data in ALPM based packaging.

DESCRIPTION

The alpm-soname format exists in multiple versions. This document describes version 1, which is a legacy version and has been removed with the release of pacman 6.1 on 2024-03-04. For the latest specification, refer to alpm-soname.

FORMAT

The representation of soname information depends on in which ALPM file format they occur in.

File formats, that represent static package source data (i.e. PKGBUILD and SRCINFO) are distinguished from those that represent dynamic package build environment data (i.e. PKGINFO).

The SRCINFO (and by extension also the PKGBUILD) file format is used to represent static data about package sources and should therefore only refer to the basic form of alpm-sonamev1. The basic form is defined as the name of the shared object file in which soname data is encoded (e.g. libexample.so).

The PKGINFO file format may contain dynamic, build environment specific data. In these files soname data may be referred to using the unversioned or the explicit form (both contain information derived from the targeted shared object file).

The unversioned form is defined as the name of a shared object file, directly followed by an '=' sign, directly followed by a shared object's (unversioned) soname string, directly followed by a '-' sign, directly followed by the ELF architecture format of the shared object file (e.g. libexample.so=libexample.so-64). Refer to readelf for further information on how to extract relevant fields such as SONAME or NEEDED from the dynamic section of an ELF[2] file.

The explicit form is defined as the name of a shared object file, directly followed by an '=' sign, directly followed by a version string, directly followed by a '-' sign, directly followed by the ELF architecture format (e.g. libexample.so=1-64). The version string represents the current interface number of the library interface version[3] that is encoded as part of the soname by the developer of the shared object (e.g. 1 in libexample.so.1). Refer to readelf for further information on how to extract relevant fields such as SONAME or NEEDED from the dynamic section of an ELF[2] file.

The ELF architecture format is a number derived from the Class field of the ELF header of an ELF[2] file. For the 32-bit format it is 32, for the 64-bit format it is 64. Refer to readelf for further information on how to extract the ELF header from an ELF[2] file.

When using the name of a shared object file, this always refers to the least specific file name. If for example the following files exist on a system:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

Then the symlink libexample.so is the least specific file name, while libexample.so.1.0.0 would refer to the actual ELF[2] file.

Note: While technically possible, it is strongly discouraged to use unversioned or explicit form in PKGBUILD or SRCINFO! This is because it requires manual handling of dynamically changing soname data in the static package source file formats and those may be out of sync with the actual, explicit data derived from the build environment.

Note: Both basic and explicit forms of the alpm-sonamev1 format overlap with the alpm-package-name and composite comparison expressions as defined in the alpm-comparison format, respectively. Due to this ambiguity it is essential to use the alpm-sonamev1 forms in the respective correct file formats or ideally switch to a later version of the alpm-soname format altogether.

USAGE

More specifically, a soname dependency of one package is based on the soname data of a shared object file provided by one of its dependency packages.

A package build tool (e.g. makepkg) automatically derives soname information for ELF[2] files in the build environment based on the following rules:

If the package that is built contains a shared object file and the name of that shared object file (i.e. the basic form) is present as an alpm-package-relation of type provision in the package's PKGBUILD file (e.g. provides=(libexample.so)), then relevant data from the SONAME field in the dynamic section of the targeted ELF[2] file is extracted.
- If the soname data contains a version, it is extracted together with the ELF architecture format of the file to construct the explicit form. It is added instead of the basic form to the alpm-package-relation of type provision in the PKGINFO file of the package (e.g. provides = libexample.so=1-64).
- If the soname data does not contain a version, the entire soname together with the ELF architecture format of the file is used to construct the unversioned form. It is added instead of the basic form to the alpm-package-relation of type provision in the PKGINFO file of the package (e.g. provides = libexample.so=libexample.so-64).
If the package that is built contains an ELF[2] file that dynamically links against a shared object available in the build environment and the name of that shared object file (i.e. the basic form) is present as an alpm-package-relation of type run-time dependency in the package's PKGBUILD file (e.g. depends=(libexample.so)), then relevant soname data from the NEEDED fields in the dynamic section of the ELF[2] file is extracted for those specific shared objects.
- All soname data that contains a version is extracted together with the ELF architecture format of the ELF[2] file and is used to construct the explicit form. It is matched against the alpm-package-relation of type provision in the PKGINFO data of the packages available in the build environment. If one matches, the explicit form instead of the basic form is added to the alpm-package-relation of type run-time dependency in the PKGINFO file of the package that is being built (e.g. depend = libexample.so=1-64).
- All soname data that does not contain a version is extracted in its entirety, together with the ELF architecture format of the ELF[2] file and is used to construct the unversioned form. It is matched against the alpm-package-relation of type provision in the PKGINFO data of the packages available in the build environment. If one matches, the unversioned form instead of the basic form is added to the alpm-package-relation of type run-time dependency in the PKGINFO file of the package that is being built (e.g. depend = libexample.so=1-64).

EXAMPLES

Providing a soname

The following example PKGBUILD for a package named example is used to build and install an upstream project, which provides a shared object named libexample.so.

pkgname=example
pkgver=1.0.0
pkgrel=1
pkgdesc="An example library"
arch=(x86_64)
url="https://example.org/library.html"
license=(MIT)
depends=(glibc)
provides=(libexample.so)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

The following SRCINFO file can be generated from the above PKGBUILD file:

pkgbase = example
	pkgdesc = An example library
	pkgver = 1.0.0
	pkgrel = 1
	arch = x86_64
	url = https://example.org/library.html
	license = MIT
  depends = glibc
	provides = libexample.so
	source = https://example.org/example-1.0.0.tar.gz
	sha256sums = 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
pkgname = example

This example assumes that the project results in installing the following files to the filesystem:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

Here, the file /usr/lib/libexample.so.1.0.0 encodes the soname libexample.so.1.

After building from source, the resulting package file for example contains the following PKGINFO file:

pkgname = example
pkgver = 1.0.0-1
pkgdesc = An example library
url = https://example.org/library.html
builddate = 1729181726
packager = Your Name <your.name@example.org>
size = 181849963
arch = x86_64
license = MIT
provides = libexample.so=1-64
depend = glibc

Depending on a soname

The following PKGBUILD for a package named application is used to build an upstream project that depends on the example package from the previous example. More specifically, the resulting package depends on the shared object libexample.so which is provided by the example package.

In the PKGBUILD the run-time dependency on the libexample.so shared object is added in the package function instead of in the global run-time dependency declaration, while the example package is declared as global build dependency. This is because multiple sonames of the same name but of different ELF architecture format may exist (consider e.g. the explicit forms libexample.so=1-32 and libexample.so=1-64). If libexample.so was exposed as global run-time dependency, a build tool may accidentally pull in the wrong package containing a libexample.so due to the existing structural overlap between alpm-sonamev1 and alpm-package-relation!

pkgname=application
pkgver=1.0.0
pkgrel=1
pkgdesc="An example application"
arch=(x86_64)
url="https://example.org/application.html"
license=(MIT)
depends=(glibc)
makedepends=(example)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)

build() {
  make -C $pkgname-$pkgver
}

package() {
  depends+=(example libexample.so)
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

The following SRCINFO file can be generated from the above PKGBUILD file:

pkgbase = application
    pkgdesc = An example application
    pkgver = 1.0.0
    pkgrel = 1
    arch = x86_64
    url = https://example.org/application.html
    license = MIT
    depends = glibc
    depends = example
    depends = libexample.so
    makedepends = example
    source = https://example.org/application-1.0.0.tar.gz
    sha256sums = b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
pkgname = application

After building from source, the resulting package file for application contains the following PKGINFO file:

pkgname = application
pkgver = 1.0.0-1
pkgdesc = An example application
url = https://example.org/application.html
builddate = 1729181726
packager = Your Name <your@email.com>
size = 181849963
arch = x86_64
license = MIT
depend = glibc
depend = example
depend = libexample.so=1-64

NOTES

soname

https://en.wikipedia.org/wiki/Soname
ELF

https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
library interface version

https://www.gnu.org/software/libtool/manual/html_node/Versioning.html

NAME

soname - representation and use of soname data in ALPM based packaging.

DESCRIPTION

FORMAT

The representation of soname information exclusively takes place in file formats that may contain dynamic, build environment specific data, such as PKGINFO.

USAGE

More specifically, a soname dependency of one package is based on the soname data of a shared object file provided by one of its dependency packages.

A package build tool (e.g. makepkg) automatically derives soname information from ELF[2] files in the build environment based on the following rules:

If the package that is built provides a shared object in one of the configured lookup directories, the value of the SONAME field in the dynamic section of the ELF[2] file is extracted. Together with the prefix assigned to the given lookup directory this data is added as a provision to the PKGINFO data for the package (e.g. provides = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib).
If the package that is built produces an ELF[2] file that dynamically links against a shared object available in the build environment, the value of the NEEDED field in the dynamic section of the ELF[2] file that is linked against is extracted. If a package containing the shared object file that encodes the soname data is present in the build environment and the package's PKGINFO data exposes this fact in an alpm-package-relation of type provision (i.e. provides = lib:libexample.so.1), this data is made use of. Together with the prefix assigned to the given lookup directory of the shared object file that provides the needed soname, this data is added as a run-time dependency to the PKGINFO data for the package being built (e.g. depend = lib:libexample.so.1, if the prefix for /usr/lib is lib and the shared object file encoding the soname libexample.so.1 is present in /usr/lib).

EXAMPLES

The following examples demonstrate how to expose and use soname information in ALPM-based packaging.

Providing a soname

The following example PKGBUILD for a package named example is used to build and install an upstream project that contains a shared object.

pkgname=example
pkgver=1.0.0
pkgrel=1
pkgdesc="An example library"
arch=(x86_64)
url="https://example.org/library.html"
license=(MIT)
depends=(glibc)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

This example assumes that the project results in installing the following files to the filesystem:

/usr/lib/libexample.so -> libexample.so.1
/usr/lib/libexample.so.1 -> libexample.so.1.0.0
/usr/lib/libexample.so.1.0.0

Here, the file /usr/lib/libexample.so.1.0.0 encodes the soname libexample.so.1. Further, this examples assumes that the directory /usr/lib is assigned to the prefix lib.

After building from source, the resulting package file for example contains the following PKGINFO file:

pkgname = example
pkgver = 1.0.0-1
pkgdesc = An example library
url = https://example.org/library.html
builddate = 1729181726
packager = Your Name <your.name@example.org>
size = 181849963
arch = x86_64
license = MIT
provides = lib:libexample.so.1
depend = glibc

Depending on a soname

pkgname=application
pkgver=1.0.0
pkgrel=1
pkgdesc="An example application"
arch=(x86_64)
url="https://example.org/application.html"
license=(MIT)
depends=(glibc)
depends=(example)
source=("https://example.org/$pkgname-$pkgver.tar.gz")
sha256sums=(b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c)

build() {
  make -C $pkgname-$pkgver
}

package() {
  make DESTDIR="$pkgdir" install -C $pkgname-$pkgver
}

After building from source, the resulting package file for application contains the following PKGINFO file:

pkgname = application
pkgver = 1.0.0-1
pkgdesc = An example application
url = https://example.org/application.html
builddate = 1729181726
packager = Your Name <your@email.com>
size = 181849963
arch = x86_64
license = MIT
depend = glibc
depend = example
depend = lib:libexample.so.1

NOTES

soname

https://en.wikipedia.org/wiki/Soname
ELF

https://en.wikipedia.org/wiki/Executable_and_Linkable_Format

API documentation

Contributing

These are the contributing guidelines for the alpm project.

Development takes place at https://gitlab.archlinux.org/archlinux/alpm/alpm.

Writing code

This project is written in Rust and formatted using the nightly rustfmt version. The linking is performed via mold.

All contributions are linted using clippy and spell checked using codespell. The dependencies are linted with cargo-deny and unused dependencies are detected using cargo-machete. License identifiers and copyright statements are checked using reuse. Toml files are formatted via [taplo-cli].

Various just targets are used to run checks and tests. shellcheck is used to check the just targets for correctness. In order to review the snapshot changes in tests, you can use cargo-insta.

Code examples in READMEs is tested via tangler. Links in markdown files or doc blocks are tested via lychee.

To get all of the necessary tools installed on Arch Linux, run just install-pacman-dev-packages. To setup Rust for this project run just install-rust-dev-tools. Both can also be done in one fell swoop via just dev-install.

To aide in development, it is encouraged to configure git to follow this project's guidelines:

just configure-git

This just command takes care of a few things:

Configure git to sign commits for this repository using OpenPGP.
Install the relevant git pre-commit and git pre-push hooks.
Install the git prepare-commit-msg hook to automatically add a signoff section to the commit message.

Testing

We run nextest for fast execution of unit and integration tests. just test calls cargo nextest as well as just test-docs, which runs the doc tests as nextest isn't capable of doing that yet.

The just test-coverage command creates a cobertura code coverage report and an HTML report. Both are written to target/llvm-cov/, which utilizes the llvm-tools-preview component. The just test-coverage doc additionally includes doc tests into the coverage report. However, this is still an unstable nightly-only feature.

Writing specifications

Specifications for technology of this project are written in markdown documents in the context of a component, that serves as its reference implementation. The specifications are located in the component's resources/specification/ directory and must end on .5.md or .7.md, so that they can be used as section 5 or section 7 man pages, respectively.

Specification versioning

A new specification version must be created, if fields of an existing specification are altered (e.g. a field is removed, added or otherwise changed semantically).

By default, given an example specification named topic and given only one version of topic exists, there would only be a document named topic.7.md. If the need for version two of topic arises, the document is renamed to topicv1.7.md, a new file named topicv2.7.md is used for the new version and a symlink from the generic specification name to the most recent version (here topic.7.md -> topicv2.7.md) is created. Versioned specifications additionally must clearly state the specification version number they are addressing in the NAME and DESCRIPTION section of the document.

New (versions of) specifications must be accompanied by examples and code testing those examples.

The examples and code testing those examples must be kept around for legacy and deprecated specifications to guarantee backwards compatibility.

Writing commit messages

To ensure compatibility and automatic creation of semantic versioning compatible releases the commit message style follows conventional commits.

The commit messages are checked by just run-pre-push-hook via the following tools: cocogitto & committed.

Follow these rules when writing commit messages:

The subject line should be capitalized and should not end with a period.
The total length of the line should not exceed 72 characters.
The commit body should be in the imperative mood.
Avoid using the crate name as the commit scope. (e.g. feat(alpm-types)) The changelog entries will be generated for the associated crate accordingly using release-plz and git-cliff.

Here is an example of a good commit message:

feat(parser): Enhance error handling in parser

Improve error handling by adding specific error codes and messages
to make debugging easier and more informative. This update enhances
parsing accuracy and provides more context for handling parsing errors.

Signed-off-by: John Doe <john@archlinux.org>

Merging changes

Changes to the project are proposed and reviewed using merge requests and merged by the developers of this project using fast-forward merges.

Creating releases

Releases are created by the developers of this project using release-plz by running (per package in the workspace):

just prepare-release <package>

Changed files are added in a pull request towards the default branch.

Once the changes are merged to the default branch a tag is created and pushed for the respective package:

just release <package>

The crate is afterwards automatically published on https://crates.io using a pipeline job.

License

All code contributions fall under the terms of the Apache-2.0 and MIT.

Configuration file contributions fall under the terms of the CC0-1.0.

Documentation contributions fall under the terms of the CC-BY-SA-4.0.

Specific license assignments and attribution are handled using REUSE.toml. Individual contributors are all summarized as "ALPM Contributors". For a full list of individual contributors, refer to git log --format="%an <%aE>" | sort -u.

Security Policy

Supported Versions

We release patches for security vulnerabilities. Currently, only the most recent release of a crate is eligible for receiving such patches.

Reporting a Vulnerability

Please report (suspected) security vulnerabilities on the issue tracker as a confidential issue with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue.

We will respond as quickly as possible after you open an issue. However, please note that this project is maintained by volunteers, so response times may vary. If the issue is confirmed as a vulnerability, we will open a Security Advisory and acknowledge your contributions as part of it.

This project follows a coordinated vulnerability disclosure (CVD) with a 90-day disclosure policy, meaning reported vulnerabilities will be addressed within 90 days before public disclosure.

ALPM Scripts

This crate contains development integration for testing and interacting with Arch Linux Package Management. Currently supported features:

Download current live data from an Arch Linux Mirror.
Test existing parsers against downloaded data.

Documentation

https://alpm.archlinux.page/rustdoc/dev_scripts/ for development version of the crate

Prerequisites

rsync for package and database downloads.
tar to extract packages.
git
A registered Arch Linux GitLab account and a configured environment to pull from it via ssh.
Disk space (around ~100GB). Especially the package download is quite big:
- packages: ~90GB
- databases: ~1GB
- pkg-src-repositories: ~3GB

Workflow

As an example, this is how you would test the .BUILDINFO validation:

Sync all current packages to a cache location. This implicitly extracts their metadata for use in tests. Successive calls sync the local cache directory with the remote state.
```
cargo run -- test-files download packages
```
Validate the current metadata in the local cache:
```
cargo run -- test-files test build-info
```

You can use the --repository flag for specifying repositories. The available package repositories are core, extra and multilib.

Tests against live data

The test-files subcommand of the scripts binary downloads live data from Arch mirrors and Arch's GitLab to test the parser binaries on them.

Providing test integration for all file types is in scope of this crate, as soon as components for them exist.

Currently the following file types are supported:

ALPM-DB-DESC
ALPM-DB-FILES
ALPM-MTREE
ALPM-REPO-DESC
ALPM-REPO-FILES
BUILDINFO
PKGINFO
SRCINFO

Download

There are three different data sources, which can be downloaded individually:

Mirror Databases

Calling test-files download databases downloads the current repository sync databases from a given mirror and extracts them. The default destination is ~/.cache/alpm/testing/databases. A dedicated folder will be created for each package repository.

Mirror Packages

Calling test-files download packages downloads the current packages from a given mirror and extracts all metadata files from them. The default destination is ~/.cache/alpm/testing/packages. A dedicated folder will be created for each package repository.

Packages Source Repository

Calling test-files download pkg-src-repositories downloads the package source repositories for all active packages and extracts all package metadata files from them. The default destination is ~/.cache/alpm/testing/pkgsrc.

Testing

To run the parser tests for a specific file type run test-files test $FILE_TYPE. For instance: test-files test build-info.

Depending on which file type you want to test, you need to download the respective data first.

test-files download databases will contain the following file types:

desc
files

test-files download packages will contain the following file types:

.INSTALL
.BUILDINFO
.MTREE
.PKGINFO

test-files download pkg-src-repositories will contain the following file type:

.SRCINFO

An overview of existing and actively maintained projects in the ALPM ecosystem.

Projects

Official

Name	Description	Languages
devtools	Tools for Arch Linux package maintainers	Shell
pacman-contrib	Contributed scripts and tools for pacman systems	Multiple

Community

Name	Description	Languages
expac	Data extraction tool for alpm databases	C
paccat	Print pacman package files	Rust
pkgfile	ALPM .files metadata explorer	C++ Python

AUR helpers

Various AUR helpers make use of libalpm to query the package database.

Media

Community

Discussion around the ALPM project takes place on the arch-projects mailing list and in #alpm on oftc.net (also available via matrix). Constructive feedback, contributions, as well as user support are welcome.