pbuild Reference Guide

Defines build configurations. Usually defaults from a distribution are used, but this file can provide additional rules. These define which packages need to become available in the build environment, macro definitions and many more. See the build config topic for a detailed list.

This file defines one or more presets in XML format. A preset bundles the distribution configuration, repositories, container registries, and target architecture into a named configuration.

The XML schema is:

Elements within a preset:

Example _pbuild file with multiple presets:

Contains all binaries for the given preset. These are either downloaded or built locally. Additional underscore-prefixed files contain information about the build history and current states of the build.

Source lines in spec files can declare remote assets. Rpm is already supporting to use an URL as source definition.

A comment before such a line marks the next source definition as remote asset, so that it will be automatically downloaded:

It is also possible to specify a checksum to make sure that the asset is correct.

If the source file name should be different from the last component of the url path, the url can also be specified as argument of the RemoteAsset line:

A tar ball can be created automatically at build time when adding

in front of the Source line. The directory name is taken from the archive name by default. It can be optionally provided as argument:

Common mechanics to provide the directory are either

The kiwi format is not supporting remote source specifications, but they can be specified via XML comments.

The resulting downloaded file can be copied into the image using

The kiwi profile name is added to container names by default. This can be disabled via

Remote assets that will be downloaded before the build can be added via the comment #!RemoteAsset: https://my.url/asset.tar. pbuild will fetch the asset before the build and will make it available in the buildroot so that the asset can copied into the container as follows:

PKGBuild files already contain the needed URLs and Checksums, so no extra treatment is needed.

The sources file contains a list of file names with checksums. PBuild will automatically download the missing files from a FedPkg Server that needs to be configured in the project config via the "AssetsURL:" directive or set with the "--assets" option.

Define a url for automatic asset downloading. Supported types are currently fedpkg and goproxy.

The binary type is the format of the packages that make up the build environment. This is usually set automatically depending on the recipe type and preinstall package list. Currently understood values are: rpm, deb, and arch.

Use an alternative build engine. Examples are mock (for Fedora and Red Hat) and debootstrap (for Debian), debbuild (to build debian packages with spec files), podman (container builds).

Here is an example config for debbuild:

The BuildFlags keyword defines flags for the build process. The following values for FLAG are usable.

Defines a specific file system when building inside of a VM. Possible values are ext2, ext3, ext4, btrfs, xfs, reiserfs (v3).

Sets options for file system creation. Currently only the nodirindex option is supported, which disables directory indexing for ext file systems. This makes file ordering inside of directories reproducible but may have a negative performance impact.

Selects the profiles to build in kiwi appliance builds.

Build jobs which do not create any output are aborted after some time. This flag can be used to modify the limit.

Exclude a package from building. If a package builds multiple flavors ("multibuild"), the corresponding flavor can be specified via the package:flavor syntax.

This can be used to configure that package is build, but not used for building other packages.

This can be used to maintain a whitelist of packages to be built. All other packages will turn to excluded state (and the old build results will be erased!).

Defines the ccache implementation, possible values are: ccache, sccache.

Configure usage of ccache when building the specified package.

OBS can run an external program that has access to the current build and the previously successful result, e.g. to generate a difference or a changelog from the diff.

build will run all scripts in /usr/lib/build/obsgendiff.d/ on the build host (not in the %buildroot) when this flag is set. If one of the scripts fails to run or no scripts are found, then the overall build fails. I.e. if BuildFlags: obsgendiff is set, then you must provide at least one script in /usr/lib/build/obsgendiff.d/, otherwise your build will fail.

A common use case for obsgendiff is to run release-compare after the build.

Adds the SCM URL to binary results when the package sources are managed via the scmsync mechanic. The url is written into the VCS tag of rpms when enabling this functionality.

Enables generation of SBOM (Software Bill Of Material) data. Supported formats are spdx and cyclonedx.

Sets a compression format for container layers. Possible values are gzip, zstd, zstd:chunked. The usage of values other than gzip is only supported by the podman engine.

For podman container builds, it specifies the container config format. Possible values are docker and oci. The default is docker. The docker format allows a few extensions like ONBUILD, SHELL, DOMAINNAME, COMMENT, HEALTHCHECK amongst others.

For podman container builds, it sets a timestamp for the container build. This can be a number (seconds since the epoch), the string scm (read time from _scmsync.obsinfo) or the string source_date_epoch (get time from the $SOURCE_DATE_EPOCH environment variable set in the build environment).

To enable build options during productcompose builds. For example to build reduced products via updateinfo_packages_only for maintenance testing.

Specify that a package must not be installed in the build environment.

Specify a synthetic conflict between to packages.

Define build constraints for build jobs. The selector is a colon-separated list which gets a string assigned. See the build job constraints page for details.

Define a macro to be used when parsing the spec files of packages. This is similar to using a Macros: section with the difference that the macro will not be written to the .rpmmacros file. It should therefore be used for macros that come from packages of the distributions.

Note that the lines of the project config are macro expanded while parsing, so you have to use %% for a literal percent sign in the value.

Flags which modify the behaviour during dependency resolution.

The priority of repositories defined in an image build is usually important. This is to avoid switching repositories when the same package is available in multiple repositories. However, it might be wanted to ignore that and just pick the highest version. This can be achieved by defining this flag

Preinstall also all dependencies of a preinstalled package. Instead of manually listing all packages for a working package tool one can just install dependencies of it. However, these might be more then actually needed depending on the distribution.

Enable Red Hat-specific module support in repo md repositories. By default, no module is used, so every module needed needs to be specified in the configuration. To remove a module, add an exclamation mark (!) as prefix.

Try to install all recommended packages. Packages with dependency conflicts are ignored.

Try to install all supplemented packages. Packages with dependency conflicts are ignored. This has the downside that new packages can cause different dependency expansion, so this should only be enabled for special use cases.

Ignore defined conflicts of packages. By default these are reported as unresolvable. This switch may be useful when packages get not installed in the build environment, but getting processed afterwards. That tool, eg. some image building tool, must be able to handle the situation (eg. by just using a subset of the packages).

Do not put the require/support/preinstall packages in the repositories offered to the kiwi build tool. This should have been the default.

Dependencies on files are only fulfilled if matching FileProvides are specified in the project configuration. If those are missing, the dependency results in an "unresolvable" state for directly required files or in silent breaking of the dependency for indirectly required files. With this option, all file requires are honoured by default and lead to "unresolvable" if there are no matching FileProvides defined.

Add all support/preinstall packages to the IgnoreRebuild list. This is useful so that packages only pulled in by dependencies from the support packages will also not trigger a rebuild. This could be considered a bug fix and should be used for all new base projects.

The export filter can be used to export build results from one architecture to others. This is required when one architecture needs packages from another architecture for building. The REGEX placeholder must match the resulting binary name of the package. It will export it to all listed scheduler architectures. Exported packages are not used in the built architecture by default, add a . pseudo architecture to also use them locally.

Due to memory consumption reasons dependencies to files as supported by rpm are ignored by default. As a workaround, FileProvides can be used to tell the systems which packages contain a file. The file needs to have the full path.

This is used for cross builds. It defines the host architecture used for building, while the scheduler architecture remains the target architecture.

Ignore can be used to break dependencies. This can be useful to reduce the number of needed packages or to break cyclic dependencies. If a package is specified, all capabilities provided by the package are ignored.

Be careful with this feature as breaking dependencies can have unwanted results. It is usually better to limit its usage by also specify the originating package as described in the following section.

Ignore a dependency coming from ORIGIN_PACKAGE. See the previous section for more details.

Do not trigger a rebuild if the specified packages are changed. The difference to the Support keyword is that the packages are not automatically installed for builds.

To eliminate build cycles the to-be-built packages are not installed by default. Keep can be used to overwrite this behavior. It is usually needed for packages like make that are used to build itself. Preinstalled packages are automatically kept, as the package installation program needs to work all the time.

Defines the start of a literal macros block. The block is ended by either reaching the end of the config or by a literal Macros: line. See the section about macro definitions below for more information.

Optflags exports compiler flags to the build by adding lines to rpm’s rpmrc file. They will only have an effect when the spec file is using $RPM_OPT_FLAGS or %{optflags}. The target architecture may be set to * to affect all architectures.

The build script takes care about the installation order if they are defined via dependencies inside of the packages. However, there might be dependency loops (reported during setup of the build system) or missing dependencies. The Order statement can be used then to give a hint where to break the loop.

The package in PACKAGE_A will get installed before the package in PACKAGE_B.

Defines the pattern format. Valid values are: none (default), ymp, comps. Multiple types can be specified.

In case multiple packages satisfy a dependency, the dependency expansion will fail. This is unlike like most package managing tools, which just pick one of the package. It is done that way to provide reproducible builds and reduce the chance of surprising changes when new packages are added to the repository. The Prefer directive lists packages to be preferred in case a choice exists. When the package name is prefixed with a minus sign, it is treated as a de-prefer.

It is possible to define the prefer only when the dependency comes from the specified originating package.

This is used to specify packages needed to run the package installation program. These packages are unpacked so that the native installation program can be used to install the build environment. Included scripts are not executed during this phase. However, these packages will be re-installed later on including script execution.

Limits the published binary packages in public repositories. Packages that match any REGEXP will not be put into the generated repository.

There can be only one line of PublishFilter for historic reasons. However, multiple REGEXP can be defined.

Flags which modify the behaviour during repository generation.

Create a repository even with no content, but with meta data.

Only publish kiwi build results after entire repository has finished building. Without this kiwi build results get published immediately after the build is finished.

Block publishing if any build result was failed, broken, or unresolvable. This is evaluated individually for each architecture. That means, packages can be published for an architecture on which it builds, even if a package fails to build on another architecture.

Also publish internal content tracking files (.report files).

Also publish SBOM data in the repostory. Container SBOM data is always pushed to the registries.

Defines the distversion to be used in group element of ymp files. This is used by the installer to check if the repository is suitable for the installed distribution. (OBS 2.11 or later)

If multiple packages contain different versions of a rpm package, only publish the one from the first package. If the project is of the type maintenance_release, this will be the package with the highest incident number.

Specify data for artifacthub repository verification. This will be added to the registry repository when pushing a container to it.

Define a url for the downloading of containers.

Defines the repository format for published repositories. Valid values are: none, rpm-md, suse, debian, hdlist2, arch, staticlinks and vagrant. Multiple types can be specified to generate more than one metadata type.

The OPTIONS parameter depends on the repository type, for rpm-md the known options are legacy to create the old rpm-md format, deltainfo or prestodelta to create delta rpm packages, rsyncable to use rsyncable gzip compression.

To split the debug packages in an own published repository the type splitdebug:REPOSITORY_SUFFIX can be appended, e.g.:

This results in a debuginfo package repository being created in parallel to the package repository.

Define a url for the downloading of repository packages. Supported types are currently arch, debian, hdlist2, rpmmd, suse. If the type is not specified, it is guessed from the build type.

Specify a package that always is installed for package builds. A change in one of these packages triggers a new build.

Execute the scriptlets of the specified preinstalled package. Scriptlet execution takes place after the preinstall phase, but before installing the remaining packages.

It is possible to replace BuildRequires dependencies with other dependencies. This will have only an effect on directly BuildRequired packages, not on indirectly required packages.

Specify a package that always is installed for package builds. Unlike Required:, a change in one of these packages does not trigger an automatic rebuild.

This is useful for packages that most likely do not influence the build result, for example make or coreutils.

Defines the target architecture via a gnu triplet (not the debian architecture!). For example arm-linux-gnueabihf for armv7hl builds, or i686 for building i686 packages.

Build recipe type. This is the format of the file which provides the build description (the "build recipe"). This is usually autodetected from the binary type, but in some rare cases it may be needed to manually configure the type. Currently the following types are understood: spec, dsc, arch, kiwi, livebuild, productcompose, preinstallimage.

Like Preinstall, but these packages get only installed when a virtual machine like Xen or KVM is used for building. Usually packages like mount are listed here.

If the Dockerfile references a base image via FROM, the image must be available from a configured registry (--registry option) or as a local build result from another package in the project.

Build arguments can be passed via the build configuration using:

Container builds produce several output files:

The container format and compression can be controlled via build config flags:

Remote assets can be fetched before build using a comment directive:

The terminology for this is unfortunately not standardised and various tools have conflicting definitions.

We use the following

Dependencies need to be resolved always twice during a cross build. One time for the host architecture and one time for the target architecture. Build dependencies of a package get only installed for the target architecture by default.

However, global rules in the build configuration can be created to modify this behaviour.

Note: the basic design of rpm was the GNU style, but it changed in the way that you have to specify the host architecture via %target macro on most distributions: