NAME

pakfire-archive-format - Information about the Pakfire Archive Format

DESCRIPTION

This page describes the archive format that Pakfire is using.

An archive contains the files that belong to a package in addition to some package metadata and scriptlets.

PACKAGE FORMAT

Pakfire Archives are based on the POSIX.1-2001 tar format with compression on top of it.

tar is being used across the industry for decades and offers storing files and metadata in an easy to process format.

Inside the tarball, Pakfire creates some files with metadata which will be read by the software in order to extract any necessary package metadata. Any files that belong to the package must be appended after the metadata.

In a Pakfire Archive, the first file must be name "pakfire-format" and contain the format number as an integer. This will allow the software to identify which version of the format is being used, should there be any changes.

Following the "pakfire-format" file, there must a file called ".PKGINFO" which contains the package metadata.

In a package, "pakfire-format" and ".PKGINFO" are the only files that are mandatory. Any other metadata or payload is optional.

PACKAGE METADATA

The package metadata is being stored in the ".PKGINFO" format and encoded in JSON as it is fast to parse and a versatile format that can be easily extended.

The package format must at least contain the following data:

name

The name of the package.

evr

EVR is short for epoch, version & release.

arch

The architecture this package was built for, "noarch", or "src".

uuid

A random UUID, that uniquely identifies this package.

size

The size of all files after extraction.

In addition to that, further information may be supplied:

summary

A short one-liner that describes the package.

description

A longer text that describes the package.

groups

Packages might be part of a group.

url

An URL to the website where this package has been obtained from.

license

The license this package is under.

dependencies

Package dependencies. See below.

Build information is being provided in the "build" dictionary:

pakfire

The version of Pakfire that created this archive.

host

The host this archive was created on.

time

The time in seconds since epoch when this archive was created.

Example Package Metadata

PACKAGE DEPENDENCIES

Packages can have dependencies which define relationships with other packages.

The most common use-case for this is to ensure certain packages that are required by a package are installed, but there are further applications, too. For more details, see pakfire-deps(5).

Dependencies are encoded in a JSON array/list of strings and named as follows:

requires

For "Requires". For source packages, these are also called "Build Dependencies".

provides

For "Provides".

conflicts

For "Conflicts".

obsoletes

For "Obsoletes".

recommends

For "Recommends".

suggests

For "Suggests".

supplements

For "Supplements".

enhances

For "Enhances".

FILE METADATA

Instead of shipping a separate filelist as part of the package metadata as it was done in earlier versions of the archive, any file metadata is contained in the tar header of each file. This metadata is as follows:

Path

The path of the file (without a leading slash).

Mode

Which includes:

  • The type of the file (e.g. regular file, directory, symlink, device node, etc.).

  • The permissions of the file.

Size

The size of the file.

User/Group

The owner/group of the file as a string (e.g. "root").

Creation/Modification Time

Timestamps when the file was created/last modified.

For device nodes:

  • The major/minor number of the device node.

Pakfire uses extended attributes for storing further proprietary metadata, such as:

PAKFIRE.digests

Regular files have one or multiple digests computed which are being stored with the file. Those are stored in Pakfire’s local database in order to perform integrity checks.

SCRIPTLETS

Scriptlets are small programs which are executed when a package is installed, uninstalled, or updated. They can perform some basic tasks required for the package to be useable, or cleanup some temporary data.

They must be stored at the beginning of the archive in the ".scriptlets" directory and must be named according to their action. They shall not have any extra file metadata.

COMPRESSION

It is important that packages are as small as possible to avoid wasting any disk space and to provide fast downloads.

Therefore, we use Zstandard with the highest compression option (22) to compress all packages as it provides a great compression ratio as well as excellent extraction performance.

AUTHORS

Michael Tremer