From: Michael Tremer Date: Fri, 26 Aug 2022 09:19:48 +0000 (+0000) Subject: man: Add some documentation about the archive format X-Git-Tag: 0.9.28~361 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=51a3d080e2b0220f337a8c8b9da77b028ccc498a;p=pakfire.git man: Add some documentation about the archive format Signed-off-by: Michael Tremer --- diff --git a/Makefile.am b/Makefile.am index e1a5f89f2..7033ce81a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -721,6 +721,7 @@ dist_macros_DATA = \ MANPAGES = \ man/pakfire.8 \ + man/pakfire-archive-format.5 \ man/pakfire-deps.5 MANPAGES_TXT = $(MANPAGES_TXT_5) $(MANPAGES_TXT_8) diff --git a/man/pakfire-archive-format.txt b/man/pakfire-archive-format.txt new file mode 100644 index 000000000..226deb481 --- /dev/null +++ b/man/pakfire-archive-format.txt @@ -0,0 +1,177 @@ += 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