.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "7" ""
.SH NAME
.LP
alpm-repo - \fBA\fRrch \fBL\fRinux \fBP\fRackage \fBM\fRanagement (ALPM) based package repositories.
.SH DESCRIPTION
.LP
Package repositories are directories containing an \fBalpm-repo-db\fR and zero or more \fBalpm-package\fR files and the respective digital signatures of each.
An \fBalpm-repo-db\fR provides metadata on the specific packages that are currently considered to be part of the package repository.
The name of the \fBalpm-repo-db\fR must be the same as that of the package repository (a valid \fBalpm-repo-name\fR).
.PP
Package repositories are usually provided centrally and exposed publicly on web servers.
As such, they may be mirrored in several different locations, synchronizing contents from the central location to distribute load and to make their contents available world wide.
.PP
The state and contents of a package repository are maintained using package repository management software (e.g. \fBdbscripts\fR[1] which relies on \fBrepo-add\fR).
.PP
Package management software (e.g. \fBpacman\fR) relies on one or more package repositories to install and upgrade software on a system.
.SS
Repository databases
.LP
The role of an \fBalpm-repo-db\fR is to define which of the \fBalpm-package\fR files in an \fBalpm-repo\fR are currently considered to be part of the package repository.
Although multiple versions of a given \fBalpm-package\fR may be present as file in an \fBalpm-repo\fR only one of them can be tracked as \fIthe current\fR in an \fBalpm-repo-db\fR.
.PP
In the following example repository named \f(CRrepo\fR, multiple versions of a package named \f(CRexample-package\fR exist, but only one of them is present in the \fBalpm-repo-db\fR (e.g. version \f(CR1.0.1-1\fR):
.LP
.EX
\&.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── example-package-1.0.0-2-x86_64.pkg.tar.zst
├── example-package-1.0.0-2-x86_64.pkg.tar.zst.sig
├── example-package-1.0.1-1-x86_64.pkg.tar.zst
├── example-package-1.0.1-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
Package management software, that downloaded the latest version of the \fBalpm-repo-db\fR is only aware of \f(CRexample-package\fR in version \f(CR1.0.1-1\fR.
.PP
A package management system, that still has a copy of an older version of the \fBalpm-repo-db\fR is only aware of earlier versions of \f(CRexample-package\fR (e.g. \f(CR1.0.0-1\fR or \f(CR1.0.0-2\fR).
For the download of those older versions to work, these specific \fBalpm-package\fR files have to be kept in the \fBalpm-repo\fR for an unspecified amount of time.
Note, that there is currently no specified default on how long package repositories are obligated to keep old versions.
However, they should always contain the packages specified in their current \fBalpm-repo-db\fR.
.SS
Maintaining a repository
.LP
Repository management software is used to add, remove and update the contents of a package repository.
Before modifying the \fBalpm-repo-db\fR to manifest the current state, the software should e.g. ensure that:
.IP "\(bu" 3
the targeted \fBalpm-package\fR files and digital signatures exist and can be verified,
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
there is no duplicate \fBalpm-package\fR entry,
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
an already existing \fBalpm-package\fR entry is updated or removed,
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
required run-time dependencies (see \fBalpm-package-relation\fR) for a new or updated \fBalpm-package\fR are present (or will be present when adding several package files),
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
when removing an \fBalpm-package\fR, it is no longer required as run-time dependency for another package in the repository (unless that package is also removed)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
each \fBalpm-package\fR file can be traced back to a known \fBalpm-source-repo\fR.
.SS
Efficient handling of contents
.LP
The \fIcurrent state\fR of a package repository can be imagined as \fIa view\fR onto the set of all packages (and their respective versions) present in an \fBalpm-repo\fR.
Ideally, this \fIview\fR represents a consistent, functional subset of all \fBalpm-package\fR files present in a repository.
.PP
Several requirements can be extracted from the sections on \fBrepository databases\fR and \fBmaintaining a repository\fR and have to be kept in mind when maintaining a package repository:
.IP "\(bu" 3
Old versions of package files need to be kept around for an unspecified amount of time.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
Changes to the repository must be atomic.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
All files made available by the latest version of an \fBalpm-repo-db\fR must be available for download.
.LP
For repository management software it is therefore pivotal to efficiently handle the files in a repository and only make a new version of the \fBalpm-repo-db\fR available once required files are available and necessary checks for them have passed.
.PP
To allow for files to be added and removed from a repository in a near-instantaneous manner, they can be made available via symlinks.
For this purpose, all \fBalpm-package\fR files and their respective digital signatures may be added in a pool directory.
The \fBalpm-package\fR files in a package repository are then merely symlinks to files in the pool directory, e.g.:
.LP
.EX
\&.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst -> ../../../pool/example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig -> ../../../pool/example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── example-package-1.0.0-2-x86_64.pkg.tar.zst -> ../../../pool/example-package-1.0.0-2-x86_64.pkg.tar.zst
├── example-package-1.0.0-2-x86_64.pkg.tar.zst.sig -> ../../../pool/example-package-1.0.0-2-x86_64.pkg.tar.zst.sig
├── example-package-1.0.1-1-x86_64.pkg.tar.zst -> ../../../pool/example-package-1.0.1-1-x86_64.pkg.tar.zst
├── example-package-1.0.1-1-x86_64.pkg.tar.zst.sig -> ../../../pool/example-package-1.0.1-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
Using this approach, the addition or removal of files in a repository or the move of files between different repositories is very light in terms of resources.
Here, the resources required for an atomic change to the state of a repository are mostly defined by the checks required for the transaction and updating the metadata of the \fBalpm-repo-db\fR.
.PP
Similarly, when updating the metadata in an \fBalpm-repo-db\fR, it is advisable to first create updated versions of the two supported database \fIvariants\fR (and optional digital signatures for them) in a temporary location in the \fBalpm-repo\fR and only then move all files to their target location simultaneously.
.SH SEE ALSO
.LP
\fBalpm-package\fR(7), \fBalpm-package-relation\fR(7), \fBalpm-repo-db\fR(7), \fBalpm-repo-name\fR(7), \fBalpm-source-repo\fR(7), \fBpacman\fR(8), \fBrepo-add\fR(8)
.SH NOTES
.IP "1." 3
\fBdbscripts\fR
.IP
.UR https://gitlab.archlinux.org/archlinux/dbscripts
.UE
.IP "2." 3
\fBOpenPGP signatures\fR
.IP
.UR https://openpgp.dev/book/signing_data.html#detached-signatures
.UE