= pakfire-archive-format(5)

== 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
[source,json]
----
{
  "name": "iproute2",
  "evr": "4.18.0-1.ipfire3",
  "arch": "src",
  "vendor": "IPFire Project",
  "uuid": "54c2dfe8-5259-4fda-8320-04819b3cab86",
  "groups": "Networking/Tools",
  "url": "https://git.kernel.org/pub/scm/network/iproute2/iproute2.git",
  "license": "GPLv2+",
  "summary": "Advanced IP routing and network device configuration tools.",
  "description": "The iproute package contains networking utilities (ip and rtmon, ...",
  "size": 0,
  "dependencies": {
    "requires": [
      "bison",
      "flex",
      "libdb-devel",
      "libnl-devel",
      "linux-atm-devel >= 2.5.1",
      "pakfire(Digest-SHA512)",
      "pakfire(Digest-SHA256)",
      "pakfire(Compress-Zstandard)",
      "pakfire(PackageFormat-6)"
    ]
  },
  "build": {
    "pakfire": "0.9.27",
    "host": "michael.haj.ipfire.org",
    "time": 1661364093
  }
}
----

== 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 link: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