--- /dev/null
+= 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
projects / pakfire.git / commitdiff
