Packages source tree

Packages artifacts in deb and RPM formats are built starting from source archives. Fatbuildr follows strict principles to extract the source archives into a deterministic and predictable source tree. These principles are designed to help development of packaging code by making it consistent accross version and formats and reduce maintenance cost over time eventually.

The principle applied by Fatbuildr to extract source archives are detailed in this page to help package maintainers write optimal and resilient packaging code for all types of sources archives.

Common mono-source package

Most packages are based from a unique source archive, ie. the tarball that contains the source tree as released by the software editor. A common good practice followed by most software editors is to include a top-level directory in the source archives. Unfortunately, this good practice is not strictly applied in all released source archives. For this reason, Fatbuildr manages both cases and always extract the source tree in a subfolder named <artifact>-<version>, whatever the presence and the exact name of the top-level folder in the editor source archive.

This principle is illustrated for an example artifact foo in Figure 1 and Figure 2 which represent with and without top-level directory cases respectively.

source tree mono source
Figure 1. Artifact foo with top-level directory in source archive
source tree mono source wo toplevel
Figure 2. Artifact foo without top-level directory in source archive

Multi-sources packages

Fatbuildr natively supports building packages in deb and RPM formats using multiple sources archives. Sources are declared in artifact definition file with a source identifier. The first source is considered as the main source and its identifier must match the artifact name. All other sources are considered as supplementary sources.

For the main source, Fatbuildr follows the same principle as for the mono-source packages.

All the supplementary sources are extracted in a subfolder named after the source archive filename in which all characters except alphanumericals and hyphens (-) are removed. This table provides some examples:

Archive filename Source subfolder






This subfolder renaming operation may seem weird and irrational at first glance. It has been choosen for compatibility reason with Debian source packages supplementary tarballs specifications which only supports alphanumeric and hyphen characters for components names. Please refer to dpkg-source source code for more details.

A symbolic link is created from the supplementary source identifier to the versioned renamed subfolder (ex: barbar-456/). This makes possible to write packaging code with generic paths agnostic to version number changes.

The symbolic links created for supplementary archives are integrated in source packages in the form of a patch that is dynamically generated and automatically integrated by Fatbuildr into the source package.

For similar reason to the main source archive, Fatbuildr is agnostic to the presence of a top-level directory in the supplementary source archives. If it is present, it is removed from the resulting source tree.

These principles are illustrated for an example artifact foo with a bar supplementary source in Figure 3 and Figure 4 which represent with and without top-level directory cases respectively.

source tree multi sources
Figure 3. Artifact foo with supplementary bar source with top-level directories in all source archives
source tree multi sources wo toplevel
Figure 4. Artifact foo with supplementary bar source without top-level directory in bar source archive

To quickly figure out the source tree defined by Fatbuildr for a given artifact with all principles mentioned above, it is possible to run fatbuildrctl patches command with the artifact in argument:

$ fatbuildrctl patches --artifact foo

This command downloads the artifact source archives and extract them in a temporary local directory (with a subshell and an initialized Git repository).

Please refer to fatbuildrctl manpage for more details about this command.