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

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 #

To avoid having to enter the configuration manually, you can:
go to the Image Templates and create a project from there, or
branch the Template Package

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. Images built with mkosi by default 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. GRUB2 is also supported. It can also be used to build Unified Kernel Images (UKIs) (and addons) and Sysexts.

In order to build an image in mkosi you need at least a mkosi.conf recipe file. This file contains the image configuration in INI format. All available options can be found in the Mkosi documentation.

With a recent enough version of mkosi (at least v26) it is possible to sign images on OBS. Simply add Include=mkosi-obs and # needssslcertforbuild to the main mkosi.conf configuration file, and UKIs, bootloaders in the ESP, and dm-verity images will be signed with the project's certificate. If the sources have a mkosi.uefi.db/ and/or mkosi.uefi.KEK/ subdirectory, any x509 PEM certificate contained therein will be set up for self-enrolling on first boot in UEFI images for the respective key database.

Note

Ensure to set Type: mkosi in the repository's prjconf where the image builds are enabled on OBS. Repotype: checksumsfile:rawsig staticlinks can also be set to be compatible with systemd-sysupdate.

2.9.1 UKI from inline config #

Example 2.5: mkosi minimal build recipe (mkosi.conf) for a Debian UKI #

  # needssslcertforbuild

  [Distribution]
  Distribution=debian

  [Include]
  Include=mkosi-initrd
          mkosi-obs

  [Output]
  Format=uki
  ManifestFormat=json
  ImageId=%d-%r
  Output=%d-%r_%v_%a
  SplitArtifacts=pcrs

  [Content]
  Packages=
          systemd
          udev
          p11-kit
          lvm2
          util-linux
          kmod
          dmsetup
          dosfstools
          btrfs-progs
          e2fsprogs
          systemd-cryptsetup
          systemd-repart
          libcryptsetup12
          libfido2-1
          libtss2-esys-3.0.2-0t64
          libtss2-mu-4.0.1-0t64
          libtss2-rc0
          libtss2-tcti-device0
          libseccomp2
          linux-image-generic
          plymouth-themes
          kbd
          desktop-base
          amd64-microcode
          intel-microcode
          systemd-boot-efi

  RemoveFiles=
          /usr/lib/systemd/boot
          /usr/lib/firmware
          /boot
          /efi
          /vmlinuz
          /vmlinuz.old
          /initrd.img
          /initrd.img.old
          /etc/xdg/
          /usr/share/bug/
          /usr/share/doc/
          /usr/share/doc-base/
          /usr/share/man/
          /usr/share/common-licenses/
          /usr/share/bash-completion/
          /usr/share/reportbug/
          /usr/share/zsh/
          /usr/share/initramfs-tools/
          /usr/share/lintian/
          /usr/share/desktop-base/
          /usr/share/wallpapers/
          /usr/share/plasma/
          /usr/share/gnome-background-properties/
          /usr/share/pixmaps/
          /usr/share/icons/
          /usr/share/images/
          /var/cache
          /var/log
          /var/lib/systemd/deb-systemd-helper-enabled

  KernelModulesExclude=.*
  KernelModulesInclude=defaultstack
                      /drivers/gpu/drm

  KernelCommandLine=plymouth.use-simpledrm

Example 2.6: mkosi Project config (prjconf) #

  %if "%_repository" == "Debian_Testing_images"
  Type: mkosi
  Repotype: checksumsfile:rawsig staticlinks
  Patterntype: none
  %endif

Example 2.7: mkosi Project meta example #

  <project name="Your:Project:Name">
    <title>Title</title>
    <description>Description</description>
    <repository name="suse">
      <path project="Debian:Testing" repository="standard"/>
      <path project="Debian:Testing" repository="non-free-firmware"/>
      <arch>x86_64</arch>
    </repository>
  </project>

2.9.2 Full Discoverable Disk Image from git #

In order to build a more complex project, with multiple configuration files, it is possible to use a git repository via obs-service-tar_scm. OBS needs a single config file to be extracted, to resolve, download and and preseed dependencies, so make sure one of the config files in the repository lists all required dependencies for the build. It can be a hidden file that mkosi itself doesn't use, in case that is desired. See the ParticleOS repository for a real world example.

Example 2.8: mkosi _service file to build image from git #

<services>
  <service name="obs_scm">
    <param name="scm">git</param>
    <param name="url">https://github.com/systemd/particleos.git</param>
    <param name="revision">obs</param>
    <param name="extract">.obs/debian/x86-64/gnome/mkosi.conf</param>
    <param name="without-version">1<param>
  </service>
</services>