kentauros
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 outgit/commit
: specifies a concrete commit to check out after the initial repository clonegit/keep
: specifies whether the generated snapshot tarball should be removed after being used by the constructorgit/keep_repo
: specifies whether the repository should be removed after the snapshot tarball was createdgit/orig
: the git repository URLgit/shallow
: specifies whether a shallow checkout (depth=1) should be attempted (this is not possible ifgit/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 abovebzr/orig
: the bzr repository URL (orlp:PROJECT
abbreviations for launchpad.net) - setting a branch here AND in thebzr/branch
key is obviously not supportedbzr/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, theRelease
tag is set to1
and an appropriate ChangeLog message is added to the.spec
file, by defaultUpdate to version X.Y.Z.
. - When a new snapshot of a bzr or git repository is detected, the
Release
tag is reset to1
and an appropriate ChangeLog message is added to the.spec
file, by defaultUpdate 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. TheRelease
tag will be bumped up by+1
and a Changelog message will be inserted, by defaultUpdate 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 inmock/export
: specifies whether any successfully built packages are copied into theexports/PACKAGE/
directory or notmock/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 inmock/keep
: specifies whether to keep or remove the used.src.rpm
file after successful uploadscopr/repo
: name of the repository to upload the package tocopr/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.