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.

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-mtree: a library and commandline interface to work with .MTREE and mtree files
alpm-buildinfo: a library and commandline interface to work with BUILDINFO files
alpm-parsers: a library for providing various custom parsers/deserializers for file types used in ALPM
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.

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::BuildInfoV1;
let buildinfo_data = r#"format = 1
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
"#;

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

Commandline

Create a BUILDINFO version 1 file using alpm-buildinfo:

alpm-buildinfo create v1 \
    --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 \

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" \
alpm-buildinfo create v1

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.

alpm-mtree

Documentation

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.

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.

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.

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

Examples

System

Known CPU architectures are represented by the Architecture enum. You can create members e.g. from str:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_types::Architecture;

assert_eq!(Architecture::from_str("aarch64"), Ok(Architecture::Aarch64));
}

Checksum

Checksums are implemented generically for a set of supported algorithms:

Blake2b512
Md5 (WARNING: Use of this algorithm is highly discouraged, because it is cryptographically unsafe)
Sha1 (WARNING: Use of this algorithm is highly discouraged, because it is cryptographically unsafe)
Sha224
Sha256
Sha384
Sha512

NOTE: Contrary to makepkg/pacman, this crate does not support using cksum-style CRC-32 as it is non-standard (different implementations throughout libraries) and cryptographically unsafe.

The above algorithms are reexported in the digests module of this crate, so that users do not have to add the blake2, md-5, sha1, or sha2 crates themselves and can solely rely on alpm-types.

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_types::{digests::Blake2b512, Checksum};

let checksum = Checksum::<Blake2b512>::calculate_from("foo\n");

let digest = vec![
    210, 2, 215, 149, 29, 242, 196, 183, 17, 202, 68, 180, 188, 201, 215, 179, 99, 250, 66,
    82, 18, 126, 5, 140, 26, 145, 14, 192, 91, 108, 208, 56, 215, 28, 194, 18, 33, 192, 49,
    192, 53, 159, 153, 62, 116, 107, 7, 245, 150, 92, 248, 197, 195, 116, 106, 88, 51, 122,
    217, 171, 101, 39, 142, 119,
];
assert_eq!(checksum.inner(), digest);
assert_eq!(
    format!("{}", checksum),
    "d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77",
);

// create checksum from hex string
let checksum = Checksum::<Blake2b512>::from_str("d202d7951df2c4b711ca44b4bcc9d7b363fa4252127e058c1a910ec05b6cd038d71cc21221c031c0359f993e746b07f5965cf8c5c3746a58337ad9ab65278e77").unwrap();
assert_eq!(checksum.inner(), digest);
}

Date

The date when a package has been built is represented using the BuildDate struct, which tracks this in seconds since the epoch.

Apart from creating BuildDate from i64 or str, it can also be created from DateTime<Utc>:

#![allow(unused)]
fn main() {
use time::OffsetDateTime;
use alpm_types::{FromOffsetDateTime, BuildDate};

let datetime = BuildDate::from_offset_datetime(OffsetDateTime::from_unix_timestamp(1).unwrap());
assert_eq!(1, datetime);
}

Env

The options available in a build environment are tracked using BuildEnv:

#![allow(unused)]
fn main() {
use alpm_types::BuildEnv;

let option = BuildEnv::new("foo").unwrap();
assert_eq!(option.on(), true);
assert_eq!(option.name(), "foo");
}

A package installed to an environment can be described using Installed:

#![allow(unused)]
fn main() {
use alpm_types::InstalledPackage;
use std::str::FromStr;

assert!(InstalledPackage::from_str("foo-1:1.0.0-1-any").is_ok());
assert!(InstalledPackage::from_str("foo-1:1.0.0-1-foo").is_err());
assert!(InstalledPackage::from_str("foo-1:1.0.0-any").is_err());
}

The options used for packaging are tracked using PackageOption:

#![allow(unused)]
fn main() {
use alpm_types::PackageOption;

let option = PackageOption::new("foo").unwrap();
assert_eq!(option.on(), true);
assert_eq!(option.name(), "foo");
}

Size

The compressed size of a package is represented by CompressedSize which tracks the size in bytes and can also be created from str:

#![allow(unused)]
fn main() {
use alpm_types::CompressedSize;
use std::str::FromStr;

assert_eq!(CompressedSize::from_str("1"), Ok(1));
}

The installed size of a package is represented by InstalledSize which tracks the size in bytes and can also be created from str:

#![allow(unused)]
fn main() {
use alpm_types::InstalledSize;
use std::str::FromStr;

assert_eq!(InstalledSize::from_str("1"), Ok(1));
}

Name

The name for a package is restricted to a specific set of characters. You can create Name directly or from str, which yields a Result:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_types::{Error, Name};

assert_eq!(Name::from_str("test-123@.foo_+"), Name::new("test-123@.foo_+".to_string()));
assert!(Name::from_str(".foo").is_err());
}

Path

The build directory of a package build environment can be described using BuildDir:

#![allow(unused)]
fn main() {
use alpm_types::BuildDir;
use std::str::FromStr;

let builddir = BuildDir::from_str("/build").unwrap();
assert_eq!("/build", format!("{}", builddir));
}

The start directory of a package build environment can be described using StartDir:

#![allow(unused)]
fn main() {
use alpm_types::StartDir;
use std::str::FromStr;

let startdir = StartDir::from_str("/start").unwrap();
assert_eq!("/start", format!("{}", startdir));
}

Pkg

The authors of packages are identified using the Packager type, which describes a User ID (name and valid email):

#![allow(unused)]
fn main() {
use alpm_types::Packager;
use std::str::FromStr;

let packager = Packager::from_str("Foobar McFooface <foobar@mcfooface.org>").unwrap();
assert_eq!("Foobar McFooface", packager.name());
assert_eq!("foobar@mcfooface.org", packager.email().to_string());
}

Package types are distinguished using the PkgType enum. Its variants can be constructed from str:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use alpm_types::PkgType;

assert_eq!(PkgType::from_str("pkg"), Ok(PkgType::Package));
}

Source

Sources of a package can be described using Source:

#![allow(unused)]
fn main() {
use std::str::FromStr;
use std::path::Path;
use alpm_types::Source;

let source = Source::from_str("foopkg-1.2.3.tar.gz::https://example.com/download").unwrap();
assert_eq!(source.filename().unwrap(), Path::new("foopkg-1.2.3.tar.gz"));

let Source::Url { url, ..} = source else { panic!() };
assert_eq!(url.host_str(), Some("example.com"));

let source = Source::from_str("renamed-source.tar.gz::test.tar.gz").unwrap();
assert_eq!(source.filename().unwrap(), Path::new("renamed-source.tar.gz"));

let Source::File { location, .. } = source else { panic!() };
assert_eq!(location, Path::new("test.tar.gz"));
}

Version

The version and CPU architecture of a build tool is tracked using BuildToolVersion:

#![allow(unused)]
fn main() {
use alpm_types::BuildToolVersion;
use std::str::FromStr;

let buildtoolver = BuildToolVersion::from_str("1.0.0-1-any").unwrap();

assert_eq!("1.0.0-1-any", format!("{}", buildtoolver));
}

Schemas of compound types (e.g. those used to describe .BUILDINFO or .PKGINFO files) need a schema version to version their features. This is what SchemaVersion is for:

#![allow(unused)]
fn main() {
use alpm_types::SchemaVersion;
use std::str::FromStr;

let version = SchemaVersion::from_str("1.0.0").unwrap();

assert_eq!("1.0.0", format!("{}", version));
}

The handling of package versions is covered by the Version type (which consists of an optional Epoch, Pkgver and an optional Pkgrel). Its vercmp() method implementation is compatible with that of libalpm/pacman's vercmp.

#![allow(unused)]
fn main() {
use alpm_types::Version;
use std::str::FromStr;

let version = Version::from_str("1.0.0").unwrap();

assert_eq!("1.0.0", format!("{}", version));

let version_a = Version::from_str("1.0.0").unwrap();
let version_b = Version::from_str("1.1.0").unwrap();

assert_eq!(Version::vercmp(&version_a, &version_b), -1);

// create a Version that is guaranteed to have a Pkgrel
assert!(Version::with_pkgrel("1.0.0-1").is_ok());
assert!(Version::with_pkgrel("1.0.0").is_err());
}

Version comparisons can be made using VersionComparison and VersionRequirement:

#![allow(unused)]
fn main() {
use alpm_types::{Version, VersionComparison, VersionRequirement};
use std::str::FromStr;

let requirement = VersionRequirement::from_str(">=1.5-1").unwrap();
assert_eq!(requirement.comparison, VersionComparison::GreaterOrEqual);
assert_eq!(requirement.version, Version::from_str("1.5-1").unwrap());
assert!(requirement.is_satisfied_by(&Version::from_str("1.5-3").unwrap()));
}

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.

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 7] 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-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 in the scope of ALPM only use a subset of all fields supported by the official mtree:

use-set
type
uid
gid
mode
time
size
sha256
link

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

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 has been removed, 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
./usr time=1731613789.0 type=dir
./usr/bin time=1731613789.0 type=dir
./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.

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 all fields supported by the official mtree format:

use-set
type
uid
gid
mode
time
size
md5
sha256
link

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
./usr time=1731613789.0 type=dir
./usr/bin time=1731613789.0 type=dir
./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.

The ALPM-MTREE format adheres to the official mtree specification. However mtree files in the scope of ALPM only use a subset of all fields supported by the official mtree:

use-set
type
uid
gid
mode
time
size
sha256
link

Changes since the last version

The md5 field has been removed, 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
./usr time=1731613789.0 type=dir
./usr/bin time=1731613789.0 type=dir
./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

The information encoded on each line is represented by a single keyword definition. Each such definition consists of a key from the following list immediately followed by a whitespace, an '=' sign, another whitespace and a value.

By default, the below keyword definitions must be used once per 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 definition may be provided 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 definition may be provided 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 definition may be provided 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

By default, the below keyword definitions must be used once per 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 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

By default, the below keyword definitions must be used once per 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

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

Each line encodes information that represents one keyword definition. All keyword definitions 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 definition 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 definition must be provided 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 definition 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 definitions 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definition may be provided 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 definitions 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/

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

Every package relation contains 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).

Types of package relations

The definition of a package relation is bound to a set of types. The keyword definition for each type depends on the context it is 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 or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more run-time dependencies of a package are specified using the depends array.
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.

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

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

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 and an optional description), that is only needed for optional functionality of a given package.

The value for an optional dependency is either an alpm-package-name or an alpm-package-name directly followed by a ':' sign, a whitespace and a UTF-8-formatted description string that specifies a reason for the optional dependency for the given package (e.g. example or example: for feature X).

In PKGBUILD files zero or more optional dependencies of a package are specified using the optdepends array.
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.

Provision

This package relation specifies a component name (an alpm-package-name or a virtual component), 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 or an alpm-comparison (e.g. example or example>=1.0.0).

In PKGBUILD files zero or more provisions are specified using the provides array.
In PKGINFO files the provides keyword is used to specify a provision.
In SRCINFO files the provides keyword is used to specify a provision.

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.
In PKGINFO files the conflict keyword is used to specify a conflict.
In SRCINFO files the conflicts keyword is used to specify a conflict.

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.
In PKGINFO files the replaces keyword is used to specify a conflict.
In SRCINFO files the replaces keyword is used to specify a conflict.

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

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 is represented by a positive integer, or a positive integer directly followed by a '.' sign and another positive integer. 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"

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"

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.

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.

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.

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
```

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