What is “kentauros”?

kentauros is a tool that is designed to make a packager’s life easier by providing automation for frequently necessary tasks, such as:

  • downloading tarballs from URLs
  • creating tarball snapshots of git / bzr repositories
  • constructing RPM packages from .spec file and sources
  • locally building packages for testing purposes
  • uploading packages to cloud build services

Configuration is simple

Configuration files are only read from the configs/ folder in the kentauros root directory. The base name of the .conf file doesn’t have to match the package name - so it is possible to have, for example, a stable configuration and a snapshot configuration of the same package at the same time (e.g. mesa.conf and mesa-git.conf), without them having file conflicts. All kentauros sub-folders put package-specific files and folders into a folder named like the “configuration” name (e.g. packages/mesa/ and packages/mesa-git/).

The minimal configuration file for a package named “PACKAGE_NAME” with version “PACKAGE_VERSION” consists of the following lines (classic .ini syntax with a simple extension for lists):

[package]
name = PACKAGE_NAME
version = PACKAGE_VERSION
modules =

Note that empty keys are NOT optional (in fact, NO key is optional). Package configuration files are strictly validated before each action and helpful error messages are printed.

Using Modules

A package containing no modules does nothing and is rather boring. Modules can be added by adding the appropriate string to the list in the package/modules key in the configuration file, for example:

[package]
name = PACKAGE_NAME
version = PACKAGE_VERSION
modules = source,constructor,builder,uploader

If kentauros is run in chain mode (ktr chain PACKAGE), the modules are executed in the order specified in the package/modules key.

Every module type specified like this needs to know which concrete module is wanted, for example:

[modules]
source = url
constructor = srpm
builder = mock
uploader = copr

Every concrete module expects a section in the configuration file. More about that in the sections below.

Source support

Right now, downloading tarballs from URLs and creating snapshot tarballs of bzr / git repositories are supported. Additionally, the branch and commit can be specified to arbitrary values, making it easy to target, for example, stable branches of software or specific “known good” commits.

Using some variables in the supplied source “origin” is supported (%{name} and %{version} right now, matching the respective RPM macro names). This makes it possible to only change one configuration value (the package/version key) and correctly build and publish a package update with one kentauros command (ktr chain PACKAGE), because the Version and Source tags in the RPM .spec file are automatically set according to this value.

Configuration for URL tarballs

URL sources expect the following configuration values to be present:

[url]
keep = # true or false
orig = # the URL

The url/keep key specifies whether the tarball should be removed after being used for (for example) .src.rpm file construction.

Configuration for git repositories

git sources need a bit more configuration than URL sources:

[git]
branch =
commit =
keep = # true or false
keep_repo = # true or false
orig =
shallow = # true or false
  • git/branch: specifies which branch to check out
  • git/commit: specifies a concrete commit to check out after the initial repository clone
  • git/keep: specifies whether the generated snapshot tarball should be removed after being used by the constructor
  • git/keep_repo: specifies whether the repository should be removed after the snapshot tarball was created
  • git/orig: the git repository URL
  • git/shallow: specifies whether a shallow checkout (depth=1) should be attempted (this is not possible if git/commit is set)

Configuration for bzr repositories

bzr sources are a bit simpler:

[bzr]
branch =
keep = # true or false
keep_repo = # true or false
orig =
revno =
  • bzr/branch, bzr/keep, bzr/keep_repo: same as above
  • bzr/orig: the bzr repository URL (or lp:PROJECT abbreviations for launchpad.net) - setting a branch here AND in the bzr/branch key is obviously not supported
  • bzr/revno: specifies which concrete revision to check out after the initial download

Trying to keep track of state

Deleting the VCS repositories between snapshot tarball creations is supported, where the last known state of the repository is always saved in a human-readable JSON file - to make sure no information is lost in the process.

Constructor support

At the moment of writing, only the automatic construction of SRPM packages is supported by kentauros (although adding - for example - debian source package support should not be too hard, since kentauros is designed to be easily extensible).

The SRPM Constructor only needs a valid RPM .spec (and the specified sources being present) to construct a .src.rpm file.

Configuration for the SRPM Constructor

There are currently no configuration switches for the SRPM Constructor. Regardless, an empty [srpm] section is expected for the configuration file to be deemed valid.

Trying to be smart: Versions

Right now, the Version and Release tag only support one formatting scheme for each type of source. Support for custom schemes is planned for the future (for example to match the current stupid Package Versioning Guidelines in fedora).

The currently used versioning scheme sets the Version string in the following ways:

  • $VERSION for normal release tarballs
  • $VERSION+git$DATE.$SHORTCOMMIT for git snapshots
  • $VERSION+bzr$REV for bzr snapshots

This way, the version always increases monotonocally for releases and snapshot updates. The only limitation is that the current scheme assumes “post-release” snapshots (currently snapshots of version X supersede a stable release X, because of the + sign after the version string).

I plan on adding a package setting to indicate whether snapshot builds are “pre-release” or “post-release”, where ~ will be used as the separator for pre-release snapshots and + is used as the separator for post-release snapshots, so RPM can always correctly determine the version order.

Trying to be smart: Releases

The SRPM Constructor also tries to be smart with Version and Release tag handling:

  • When the value of the Version tag changes between builds, the Release tag is set to 1 and an appropriate ChangeLog message is added to the .spec file, by default Update to version X.Y.Z..
  • When a new snapshot of a bzr or git repository is detected, the Release tag is reset to 1 and an appropriate ChangeLog message is added to the .spec file, by default Update to latest snapshot..
  • If the package has not discernibly changed, no changes are applied to the Release tag and a straight rebuild of the package is done.
  • If the -f or --force CLI switch is supplied to the Constructor, a packaging change is assumed. The Release tag will be bumped up by +1 and a Changelog message will be inserted, by default Update for packaging changes., though this can be overridden with a custom message with the -m or --message CLI option.

Builder support

At the moment, .src.rpm packages constructed by the SRPM Constructor can be built locally with a Mock Builder.

If specified, packages resulting from successful builds are copied to the project’s exports directory for further use (so they aren’t lost when the next mock build for the same chroot is started).

Configuration for the Mock Builder

The Mock Builder can change behavior according to some settings:

[mock]
active = # true or false
dists =
export = # true or false
keep = # true or false
  • mock/active: tells the Mock Builder whether to do anything - this makes it possible to load and initialize a Mock Builder but not to use it (for example for testing / verification purposes or only temporarily enabling local builds)
  • mock/dists: comma-separated list of mock chroots to build the package in
  • mock/export: specifies whether any successfully built packages are copied into the exports/PACKAGE/ directory or not
  • mock/keep: specifies whether to keep or remove the used .src.rpm file after successful builds

Trying to be smart: chroots / dists

Supplying multiple chroots is supported, although builds are not executed in parallel because that would cause issues in certain circumstances (for example: different mock dist configurations targeting the same chroot).

If the specified chroot is in use, kentauros will correctly detect that and back off until the currently running build finishes.

Uploader support

Right now, only uploads of .src.rpm files to the COPR build service are automated, though support for koji “scratch” builds should be easy to add (which is on my todo-list).

When using the COPR Uploader, kentauros assumes that copr-cli is properly configured (the ~/.config/copr file is present and contains a valid authentication token).

If specified in the configuration file, kentauros waits for COPR builds to finish.

Configuration for the COPR Uploader

The COPR Uploader can change behavior according to some settings:

[copr]
active = # true or false
dists =
keep = # true or false
repo =
wait = # true or false
  • copr/active: tells the COPR Uploader whether to do anything - this makes it possible to load and initialize a COPR Uploader but not to use it (for example for testing / verification purposes or only temporarily enabling uploads)
  • copr/dists: comma-separated list of chroots to build the package in
  • mock/keep: specifies whether to keep or remove the used .src.rpm file after successful uploads
  • copr/repo: name of the repository to upload the package to
  • copr/wait: specifies whether kentauros should wait for the remote build to finish or not

Trying to be smart: chroots / dists

If no dists are specified in the package’s configuration file, the package will be built for all dists configured for the specified COPR repository (which is the default behaviour of copr-cli, too). If dists are supplied, one build for all specified dists is requested.