4 Build Configuration #

4.1 About the Build Configuration #

Each project has a build configuration which defines the setup of the build system and the publish behaviour. Usually the distribution base is defining it and you do not need to change anything. However, when you change it, it can be used for the following reasons:

Handle compatibility layers.
Switch on or off certain features during the build.
Decide which package is installed during build.
Resolve dependency problems like when there are multiple providers for a dependency:
Handle user decisions like macro settings
Modify publish behaviour, e.g. define metadata or filter binaries.

The build configuration can be stored in multiple places. Inside of OBS it can be stored only once per project. However, it is possible to define exceptions via if-conditions, for example per repository name or architecture. At the project level, the build configuration is sometimes referred to as the "project config", or "prjconf" for short. At build time, the configuration gets merged according to the repository path configuration defined in the project metadata. This resulting configuration can be requested using osc buildconfig. To view or edit the build configuration in projects, use one of the following methods

With osc. Use osc meta prjconf in your working directory of your project.
In the OBS Web UI. Via the Project Config tab.
With the OBS API. Reachable via the /source/PROJECT/_config path.
Via git/scmsync. Store a file called '_config' in a git repository used via the scmsync mechanism for a project.

4.2 Configuration File Syntax #

The syntax is basically the same as in RPM spec files. However, it is independent of the packaging format used. The build configuration (prjconf) is parsed by OBS. This means, you can use RPM features like macros or conditions in the configuration. All lines (except conditionals) have the form:

keyword: arguments

Use the conditionals (%if or %ifarch) if a line should only be used in some condition.

Many keywords, like `Require` or `BuildFlags`, do not replace existing data, but add to it. This means you can have multiple `BuildFlags` lines instead of having one line with all the flags you need.

An exclamation mark `!` can be prepended to the argument to remove an existing entry from the data.

In the following list, the placeholder PACKAGES indicates a package base name (or names). When specifying multiple packages, separate their base names with spaces. For example, as a package name you need the base name like gcc but not the full name as in gcc-1.2.3.i386.rpm.

The following list contains a list of allowed keywords in the build configuration (prjconf):

Available Keywords in Build Configuration #

BinaryType: TYPE (OBS 2.4 or later)

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`.

Sets the binary format used to set up the build environment. For example a package with spec build description may use and generate deb packages instead of RPMs. If no binary type is specified, OBS deduces it from the build recipe type. If the recipe type is also not set, OBS looks at the Preinstall package list for a hint.

BuildEngine: ENGINE

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`:

Type: spec
Repotype: debian
Binarytype: deb
BuildEngine: debbuild
Support: pax debbuild

BuildFlags: FLAG:VALUE

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

allowrootforbuild

Allow any package build to use root user for building. This still needs a marker inside of the build description to enable it.

vmfstype:TYPE

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

vmfsoptions:OPTION

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. vmfsoptions:nodirindex

kiwiprofile:PROFILE

Selects the profiles to build in kiwi appliance builds.

logidlelimit:SECONDS

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

excludebuild:PACKAGE

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

onlybuild:PACKAGE

DANGER: this may remove many build results when introduced the first time! It can be used to maintain a whitelist of packages to be built. All other packages will turn to excluded state and get removed if available.

useccache:PACKAGE

Configure usage of ccache when building the specified package.

ccachetype:TYPE

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

obsgendiff

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.

OBS 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.

setvcs

Add 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.

nodisturl

Skip the embedding of DISTURL tag into binaries. Please note that this might also break other features like binary tracking. So never do this for maintained binaries.

sbom:FORMAT

OBS 2.11 can produce and publish additional SBOM (Software Bill Of Material) meta data by enabling this flag. This is currently supported for container and kiwi images builds and includes only data from installed rpm packages. Supported formats are spdx and cyclonedx.

slsaversion:VERSION

OBS 2.11 is producing slsa provenance files in version 0 by default at build time, when enabled. It is possible to switch to v1 by specifing slsaversion:v1 as buildflag.

container-compression-format:FORMAT

Sets a compression format for container layers. Possible values are gzip, zstd, zstd:chunked. Every value other than gzip is only supported by podman and buildah.

container-build-format:FORMAT

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.

Conflict: PACKAGE

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

Conflict: PACKAGE_A:PACKAGE_B

Specify a synthetic conflict between two given packages.

Constraint: SELECTOR STRING (OBS 2.4 or later)

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.

DistMacro: NAME VALUE

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.

ExpandFlags: FLAG

Flags which modify the behaviour during dependency resolution.

unorderedimagerepos (OBS 2.10 or later): 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
preinstallexpand: Preinstall also all dependencies of a preinstalled package. This may increase the amount of preinstalled packages a lot.
module:NAME-STREAM (OBS 2.10.7 or later): 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.
dorecommends: Try to install all recommended packages. Packages with dependency conflicts are ignored.
dosupplements: 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.
ignoreconflicts: 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, e.g. some image building tool, must be able to handle the situation (e.g. by just using a subset of the packages).
kiwi-nobasepackages: Do not put the require/support/preinstall packages in the repositories offered to the kiwi build tool. This should have been the default.
keepfilerequires: Dependencies on files are only fulfilled if matching FileProvides are specified in the build configuration (prjconf). 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.

ExportFilter: REGEX ARCHITECTURES

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. Using a single dot will export it to the architecture which was used to build it. So not using a dot there will filter the package.

FileProvides: FILE PACKAGES

OBS ignores dependencies to files (instead of package names) by default. This is mostly done to reduce the amount of memory needed, as the package file lists take up a considerable amount of repository meta data. As a workaround, FileProvides can be used to tell the systems which packages contain a file. The File needs to have the full path.

HostArch: HOST_ARCH

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

Ignore: PACKAGE_OR_DEPENDENCY

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.

Ignore: ORIGIN_PACKAGE:PACKAGE_OR_DEPENDENCY

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

Keep: PACKAGES

To eliminate build cycles the to-be-built package are not installed by default, even when it is required. 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.

OptFlags: TARGET_ARCH FLAGS (RPM only)

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.

Order: PACKAG_A:PACKAGE_B

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.

Patterntype: TYPE

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

Prefer: PACKAGES

In case multiple packages satisfy a dependency, the OBS system will complain about that situation. This is unlike like most package managing tools, which just pick one of the package. Because one of OBS' goal is to provide reproducible builds, it reports an error in this case instead of choosing a random package. The Prefer: tag lists packages to be preferred in case a choice exists. When the package name is prefixed with a dash, this is treated as a de-prefer.

Prefer: ORIGIN_PACKAGE:PACKAGE

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

Preinstall: 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.

PublishFilter: REGEXP [REGEXP]

Limits the published binary packages in public repositories. Packages that match any REGEXP will not be put into the exported repository. There can be only one line of PublishFilter for historic reasons. However, multiple REGEXP can be defined.

PublishFlags: FLAG

Flags which modify the behaviour during repository generation.

artifacthub:TAG (OBS 2.11 or later)

Publish a specific verified publisher identifier (aka repository id) for artifactub.io. This can be used to proof to be the publisher (aka maintainer) for containers from these OBS repositories.

createempty (OBS 2.11 or later)

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

noearlypublish (OBS 2.11 or later)

Only publish build results after entire repository has finished building. This is the default for classic package (rpm/deb) build types, but not for certain image builds (like kiwi or products). Without this, build results get published immediately after the build is finished.

archsync (OBS 2.11 or later)

Publish all architectures at the same time. This means that the publisher is waiting until the last architecture has finished building.

nofailedpackages (OBS 2.11 or later)

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

This is by default evaluated individually for each architecture. It can be combined with the archsync flag when publishing should be blocked also when a failure exists on any architecture.

keepobsolete (OBS 2.11 or later)

The default behaviour of OBS is to remove binaries when a package object gets removed, even when the project is publish disabled (but the package may have been enabled).

This flag is changing this behaviour to keep binaries in published repositories even when a package gets removed. As consequence this flag has only an effect on publish disabled projects.

singleexport (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.

withsbom (OBS 2.11 or later)

Enables publishing of SBOM files (SPDX or CycloneDX format) (.cdx.json or .spdx.json files). Please note that the building of SBOM files usually needs to get enabled via a BuildFlags switch as well.

withreports (OBS 2.11 or later)

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

ympdist:NAME (OBS 2.11 or later)

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.

RegistryURL: URL

Define a url for the downloading of containers.

Repotype: TYPE[:OPTIONS]

Defines the repository format for published repositories. Read on for permissible values (repository types). The syntax of the OPTIONS parameter depends on the repository type, and is also described below.

This is the list of repository types. Multiple values can be combined in the same line, separated by spaces.

rpm-md: rpm-md repository data is generated as invented by YUM originaly.
suse: suse tag repository data is generated as used until SUSE Linux 10 generation.
hdlist2: Mandriva repository format
debian: Debian repository format
arch: Arch Linux repository format
vagrant: Vagrant image repository format
staticlinks: Additional links to build results excluding version and build numbers are created.
zyppservice: Generate zypp service files, publishing all used repository pathes to the zypp client.
helm: Helm repository metadata
checksumsfile: Checksums file with signatures of repository content
ymp: YaST single install ymp file generation. Zypp services should be used instead.
comps: Generate comps files, Fedora style patterns

This is the list of repository options to modify the way the repository type is generated:

sha256

rpm-md repository data is generated using SHA-256 checksums. This is the default.

sha512

rpm-md repository data is generated using SHA-512 checksums.

legacy

rpm-md repository data is generated using SHA-1 checksums. Considered to be unsafe and not anymore recommended.

zchunk

rpm-md repository data gets extended with additional zchunk compressed files.

filelists-ext

rpm-md repository provides additional filelist-ext provides

compression-zstd

rpm-md repository data is compressed using zstd instead of gz

deltainfo

rpm-md repository provides additional rpm delta informations for incremental rpm updates.

splitdebug:SUFFIX

A second repository is generated where all debuginfo and debugsource packages get moved to. The specified SUFFIX is added to the repository name. For example:

Repotype: rpm-md splitdebug:-debuginfo

rsyncable

rpm-md repository gets recompressed using rsyncable format.

rawsig

checksumsfile repository provides binary signatures instead of ascii signatures

RepoURL: [TYPE@]URL

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.

Required: PACKAGE

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

Runscripts: PACKAGES

Defines the scripts of preinstalled packages which needs to be executed directly after the preinstall phase, but before installing the remaining packages.

Substitute: OLD_DEPENDENCY NEW_DEPENDENCY

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.

Support: PACKAGE

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.

Target: TARGET_ARCH

Defines the target architecture. This can be used to build for i686 on i586 schedulers for example. Please note that on rpm based systems just the architecture needs to be specified, but on debian systems the gnu triplet, for example arm-linux-gnueabihf.

Target: GNU_TRIPLET

Type: TYPE

Build recipe type. This is the format of the file which provides the build description. This gets usually autodetected, but in some rare cases it can be set here to either one of these: spec, dsc, kiwi, livebuild, arch, preinstallimage, mkosi.

Defines the build recipe format. Valid values are currently: none, spec, dsc, arch, kiwi, preinstallimage. If no type is specified, OBS deduces a type from the binary type.

VMInstall: PACKAGE

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.

4.3 Building with ccache or sccache #

The usage of ccache or sccache can be enabled for each package by seting the useccache:PACKAGE build flag.

The ccache package will automatically be installed and configured. The directory /.ccache/ will be configured as cache directory. To configure ccache, the file /.ccache/ccache.conf can be modified as part of the build process by the $BUILD_USER environment variable.

In some cases, there is no archive for the current package, such as when the package was newly branched or when binaries were deleted. In these cases, the system will check whether there is a package of the same name built for the same architecture within one of the repositories configured in the project's meta configuration. If so, the archive of that package will be used. The repositories will be searched in the order they are configured in the meta configuration, starting from the top.

An alternative way to enable caching based on build dependencies is to add "--enable-cache" as dependency, for example via a Substitute rule:

Substitute: gcc-c++ gcc-c++ --enable-ccache

This will always enable ccache when a direct build depdency to gcc-c++ is required.

It is also possible to set the type, eg:

Substitute: cargo cargo --enable-ccache=sccache

4.4 Macro Definitions in the Build Configuration #

You can use rpm macro definitions in the build configuration (prjconf) to improve configurability. There are two types of macros that can be defined in the build configuration:

Macros: Macro Definitions. Macros defined after a Macros: line are exported into the .rpmmacros file of the build root. As such, these macro definitions can be used in a spec file. The section may be closed via a :Macros line. This is sometimes required to avoid parse errors, for example when the macro definitions are inside an %if-%endif statement. The Macros: section is always verbatim: any condition to activate it must be outside of the Macros: tags. Macros defined in this section are used by Open Build Service for build dependency resolution and are also available at build time. Any definition here is also overwriting definitions provided by any packages.
DistMacro. The DistMacro can be used to define a macro for build dependency resolution. It is intended to be used when a distribution defines relevant macros inside of any of their packages. These macros are hidden by default to the Open Build Service dependency resolver. Use this directive to make it known to Open Build Service. Unlike Macros:, DistMacro won't overwrite any existing and possibly changed definition at build time.
%define Macro Definitions. Macro definitions starting with a %define line are used during the build configuration parsing only. These definitions are not available inside the build root or during parsing of build recipes. Typical use cases are macros inside of %if statements inside of the build configuration or macros in any Support, Require or Substitute line.

4.4.1 Macros for the Build Configuration Only #

To specify macros for the building process, use the %define keyword.

For example, if you put this line in the prjconf

%define _with_pulseaudio 1

then the macro %_with_pulseaudio will expand to 1 only inside the build configuration.

4.4.2 Macros Used in Spec Files Only #

To define the values of macros used in spec files, `%define` is not used. For this use case, either enclose the macro definitions between "Macros:"/":Macros" lines, or place them at the end of the prjconf file. All lines after a line containing the directive "Macros:" up to the end of the config, or up to a :Macros line, are used when parsing spec files and also made available to the build by copying them to the .rpmmacros file in the build root.

The macro definition in the project configuration is located at the end and has the following structure:

Example 4.1: Structure of a Macro Definition #

Macros:
  # add your macro definitions
:Macros

Everything that starts with a hash mark (#) is considered a comment.

The macro definition itself are defined without a %define keyword. Start with %macroname, for example:

%_hardened_build 0