Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
User Guide / Concepts / Supported Build Recipes and Package Formats

2 Supported Build Recipes and Package Formats

2.1 About Formats

OBS differentiates between the format of the build recipes and the format of the installed packages. For example, the spec recipe format is used to build RPM packages by calling rpmbuild.

In most cases, the build result format is the same as the package format used for setting up the build environment, but sometimes the format is different. An example is the KIWI build recipe format, which can build ISOs, but uses RPM packages to set up the build process.

OBS currently supports the following build recipe formats and packages:

Supported Package Formats
  • RPM package format, used for all RPM-based distributions like openSUSE, SUSE Linux Enterprise, Fedora, and others.

  • DEB package format, used in Debian, Ubuntu, and derived distributions

  • Arch package format, used by Arch Linux

Supported Build Recipe Formats
  • Spec format for RPM packages

  • Dsc format for DEB packages

  • KIWI format, both product and appliances

  • preinstallimage

  • SimpleImage format

  • Mkosi format to build images

If no build recipe format and binary format are specified in the project configuration, OBS tries to deduce them from the preinstall list, which includes the name of the used package manager. This means that you need to manually configure the kiwi build recipe, as an RPM package format will select spec builds as default. This configuration is done by adding a Type line to the project configuration.

2.2 RPM: Spec

RPM (RPM Package Manager) is used on openSUSE, SUSE Linux Enterprise, Red Hat, Fedora, and other distributions. For building RPMs you need:

.spec

the spec file for each package containing metadata and build instructions. OBS parses the spec file's BuildRequires lines to get a list of package dependencies. OBS uses this information to both build the packages in the correct order and also for setting up the build environment. The parser understands most of RPMs macro handling, so it is possible to use architecture specific BuildRequires, conditional builds and other advanced RPM features.

.changes

the file which contains the changelog.

2.3 Debian: Dsc

DEB packages are used on all Debian or Ubuntu based distributions. For building .deb files, you need:

debian.control

The file contains the meta information for the package like the build dependencies or some description.

debian.rules

This file describes the build section of the DEB building process. There are the configure and make compile commands including other DEB building sections.

PACKAGE.dsc

In this file you describe the package names of each subpackage and their dependency level. Unlike RPM, the release numbers are not increased automatically during build unless the keyword DEBTRANSFORM-RELEASE is added to the file.

2.4 Arch: pkg

Pkg files is used on Arch Linux and its derivatives. For building Pkg you need:

PKGBUILD

It contains the build description and the source tarball. The file PKGBUILD does not have macros like %{buildroot}. It contains variables, for example, makedepends=(PACKAGE1, PACKAGE2). These variables are parsed by OBS and uses them as dependencies. On Arch Linux you typically build packages without subpackage. They are no *-dev or *-devel packages.

2.5 KIWI Appliance

KIWI is an OS appliance builder that builds images for various formats, starting from hardware images, virtualization systems like QEMU/KVM, Xen and VMware, and more. It supports a wide range of architectures, which are x86, x86_64, s390 and ppc.

For building an image in KIWI you need:

my_image.kiwi

Contains the image configuration in XML format. Full XML schema documentation can be found https://osinside.github.io/kiwi/image_description.html.

config.sh (optional)

configuration script that runs at the end of the installation, but before package scripts have run.

root/

directory that contains files that will be applied to the built image after package installation. This can also be an archived and compressed directory, usually named root.tar.gz.

Note
Note

OBS only accepts KIWI configuration files with a .kiwi suffix. Other naming schemes KIWI supports like config.xml, are ignored in OBS.

For more information about building images with KIWI, see the https://osinside.github.io/kiwi/building_images.html.

2.6 SimpleImage

This format can be used to get simple rootfs tarball or squashfs image. It does not contain a bootloader or a kernel. For advanced features, use KIWI. Use SimpleImage for simple rootfs tarball/squashfs image of any distribution that is supported by OBS but does not have anything fancier than that.

For building a SimpleImage, you need a simpleimage file. Be aware of the following points:

  • SimpleImage uses a similar syntax than a spec file.

  • Supported tags include Name, Version, BuildRequires, and #!BuildIgnore.

  • Additional customization with %build phase is supported.

  • RPM macros are not supported, but $SRCDIR shell variable is available.

Example 2.1: SimpleImage File (simpleimage)
Name:           example-image
Version:        1.0
BuildRequire:   emacs
#!BuildIgnore:  gcc-c++

%build
# Set root password
passwd << EOF
opensuse
opensuse
EOF

# Enable ssh
systemctl enable sshd

2.7 AppImage

2.8 Flatpak

The Flatpak format can be used to generate desktop apps for Linux.

For building an installable Flatpak bundle, you need a flatpak.yaml manifest file. See Flatpak Manifests for the full documentation.

Also some project and package configuration is necessary.

Quick Start
Manifest Format
  • Input format is YAML. Although flatpak also accepts JSON, we are using YAML in Open Build Service, because we have a special additional field in form of a YAML comment.

  • You can use JSON, as it is a subset of YAML. But be aware that flatpak accepts non-standard // comments, while Open Build Service does not.

  • #!BuildVersion - Use this field to specify the version of your app so the .flatpak file will be versioned. Flatpak manifests do not have a version field.

  • To learn YAML, have a look at this YAML Tutorial.

The base images for Freedesktop, GNOME, KDE are maintained in the OBS:Flatpak repository in form of rpm packages. They are generated by installing the images from Flathub and packing the directories into a tar archive.

Example 2.2: Flatpak Manifest (flatpak.yaml)
######################################################
# Flatpak manifest example for Open Build Service
# https://docs.flatpak.org/en/latest/manifests.html
# Input should be YAML, even though the file can have
# a .json suffix (JSON is a subset of YAML).
# Don't use '//' comments!
######################################################

# Special OBS field because flatpak does not have a version field
# Default will be '0' if the field is missing.
#!BuildVersion: 3.14.15
---
app-id: org.gnome.Mahjongg
runtime: org.gnome.Platform
sdk: org.gnome.Sdk
runtime-version: '3.36'
command: gnome-mahjongg

finish-args:
  - --share=ipc
  - --socket=fallback-x11
  - --socket=wayland
  - --device=dri
  - --metadata=X-DConf=migrate-path=/org/gnome/Mahjongg/

cleanup:
  - "/share/man"

modules:
- name: gnome-mahjongg
  buildsystem: meson
  sources:
  - type: archive

    # Source archives should be put into the OBS package, but you can
    # keep the original URL from where it was downloaded here.
    url: https://download.gnome.org/sources/gnome-mahjongg/3.36/gnome-mahjongg-3.36.2.tar.xz

    # You can also just specify a simple filename
    # url: gnome-mahjongg-3.36.2.tar.xz

    # flatpak-builder will do a checksum
    sha256: 'd2e8f1563ee03d112a17042c4e99971295b36f3ba795c7d905d636cc94b8ae97'
Example 2.3: Flatpak Project config (prjconf)
Type: flatpak
Support: kmod-compat kernel-default perl-YAML-LibYAML
Example 2.4: Flatpak Project meta example
<project name="Your:Project:Name">
  <title>Title</title>
  <description>Description</description>
  <repository name="openSUSE_Leap_15.2">
    <path project="OBS:Flatpak" repository="openSUSE_Leap_15.2"/>
    <arch>x86_64</arch>
  </repository>
  <repository name="openSUSE_Leap_15.1">
    <path project="OBS:Flatpak" repository="openSUSE_Leap_15.1"/>
    <arch>x86_64</arch>
  </repository>
</project>

2.9 mkosi

Mkosi allows building images for rpm, arch, deb and gentoo based distributions, on any architecture that supports UEFI. Images built with mkosi will follow the Discoverable Partitions Specification and will be bootable on baremetal (UEFI), virtual machines (UEFI), containers via systemd-nspawn, or as Portable Services in systemd.

For building an image in mkosi you need the mkosi.my_image recipe file. This file contains the image configuration in INI format. All available options can be found in the Mkosi documentation.

Note
Note

Ensure to set Type: mkosi in the repository's prjconf where the image builds are enabled on OBS.

Example 2.5: mkosi minimal build recipe (mkosi.suse) for a Tumbleweed image
[Distribution]
Distribution=opensuse
Release=tumbleweed

[Output]
Format=gpt_ext4

[Content]
Password=
Autologin=yes
Packages=
 patterns-base-minimal_base
Example 2.6: mkosi Project config (prjconf)
%if "%_repository" == "suse"
Type: mkosi
Substitute: integritysetup
Substitute: veritysetup
Prefer: openSUSE-release-appliance-custom python310-cryptography
%endif
Example 2.7: mkosi Project meta example
<project name="Your:Project:Name">
  <title>Title</title>
  <description>Description</description>
  <repository name="suse">
    <path project="openSUSE:Factory" repository="snapshot"/>
    <arch>x86_64</arch>
  </repository>
</project>