tito/doc/mead.md

Introduction

Mead is a Maven-based build system for Koji. It works by building your project via Maven, rendering a RPM spec file from a template, and then packaging everything as an RPM with the rendered spec file.

Tito has support for Mead in its tagging, building, and releasing capacities.

Setup

For a Maven project, Tito needs two things: a pom.xml and a .tmpl file. The POM file should already be present since Maven itself requires one. The .tmpl file is a Cheetah template of your RPM spec file that Mead fills in when it is building.

Tagging

Tito will increase the version in the pom.xml for you when you tag. However, it does not set the new version to a -SNAPSHOT version as is the convention in many Maven projects.

Tito uses the maven-version plugin to increase the version.

Building

Tito attempts to mimic the Mead build process although it is not perfect. Mead offers the ability to descend into different directories and run the build from there. Tito does not do this. Instead, Tito ascends to the root of the SCM checkout and runs a maven deploy against the top-level POM file. The artifacts are deployed to a temporary Maven repository under /tmp/tito. Tito then attempts to render the .tmpl file for the package. The following variables are available (these values are also provided by Mead when Koji runs a build):

• $artifacts - A hash of the Maven generated artifacts with the file extensions as keys. For example: `{'.md5': 'my_project.jar.md5', '.jar': my_project.jar'}
• $all_artifacts - All Maven generated artifacts in a list (including MD5 sums, pom files, etc)
• $all_artifacts_with_path - All artifacts but with the full path to the artifact within the project
• $version - The version of the top level project
• $revision - The revision of the top_level project
• $epoch - Currently always set to None
• $name - The name of the top_level project

Note that the name, version, and revision variables are not very useful as they receive their values from the top-level POM file.

Once the spec file is rendered, Tito proceeds with a standard RPM build.

Assemblies

Tito attempts to use the maven-assembly plugin to build a project tarball so its best if you have that plugin configured. Tito will fall back to a git archive command, but the assembly plugin is the best way.

Builder Arguments

The Mead builder can take several arguments on the command line: maven_arg and maven_property. These arguments can be specified multiple times. The maven_property arguments are passed to Maven as -D style properties and the maven_arg arguments are passed as command-line arguments. For example:

$ tito build --rpm --arg "maven_property=maven.test.skip=true" --arg "maven_arg=-X" -arg "maven_arg=-fae"

Other Cheetah Notes

• Dollar signs are meaningful in Cheetah. If your spec file contains shell variables, you will need to surround the relevant block with #raw and #end raw tags.

#raw
for selinuxvariant in %{selinux_variants}
do
  make NAME=$selinuxvariant -f /usr/share/selinux/devel/Makefile
  mv %{modulename}.pp %{modulename}.pp.$selinuxvariant
  make NAME=$selinuxvariant -f /usr/share/selinux/devel/Makefile clean
done
#end raw

• Do not use line continuations (i.e. ending a line with \)! Cheetah doesn't like them for some reason.
• Do not use non-ASCII characters anywhere in the Cheetah template (including names with non-ASCII characters in the changelog.) I ran into difficulties with the template failing to render when non-ASCII characters appeared in it.
• Always surround the entire %changelog section in #raw and #end raw tags so that people's changelog entries won't break the template.

Releasing

Configuring the DistGitMeadReleaser

The first thing to do is to create a section in your releasers.conf for the mead releaser. In addition to the releaser class and branch, you need to provide values for mead_scm and mead_push_url. Mead does not build from tarballs located in the Koji lookaside cache. Instead it builds from URLs pointing to an SCM repository.

• mead_scm - The SCM URL used to checkout the code
• mead_target - The SCM URL that Tito will use to push a copy of its tags to. A MEAD_SCM_USERNAME value set in ~/.titorc can be used here.

For example:

[mead]
releaser = tito.release.DistGitMeadReleaser
branches = fedora-20
mead_scm = git://example.com/my_project.git
mead_push_url = git+ssh://MEAD_SCM_USERNAME@example.com/my_project.git

Configuring the Koji Build Process

The tito.release.DistGitMeadReleaser releaser using Mead's maven-chain functionality. The top-level package directory (the same directory with the .tmpl file) must have a .chain file.

The chain file is an INI style file with each section as a different link in the chain. The section title is in the "groupId-artifactId" format and contains a value for scmurl which is a pointer to the SCM containing the code and a pointer to the git ref to use. For example

scmurl=git://example.com/my_project.git?app#app-1.2.3-1

Note that the SCM URL can be followed by a "?" and a subdirectory; and that the git ref is placed at the end after a "#".

Other options:

• buildrequires - a space delimited list of all sections that must be built beforehand
• type - set this to wrapper to add a wrapper RPM step. Wrapper RPM steps need to have a buildrequires on the actual Maven build step.
• packages - a space delimited list of additional YUM packages to install before building
• maven_options - command line flags to pass to Maven
• properties - "key=value" list of properties to set with -D

For Tito, the .chain file needs to have a few variables in it that will be filled in to alleviate the need for setting the git ref by hand.

The variables passed in are

• mead_scm: The value of mead_scm in releasers.conf
• git_ref: The git reference Tito is trying to build
• maven_properties: The value of any maven_properties provided as builder arguments
• maven_options: The value of any maven_args provided as builder arguments

Here's a short example that will ultimately produce an RPM named "app".

[org.example-foobar-parent]
scmurl=${mead_scm}#${git_ref}
maven_options=-N ${maven_options}

[org.example-foobar-common]
scmurl=${mead_scm}?common#${git_ref}
buildrequires=org.example-foobar-parent
packages=gettext

[org.example-app]
scmurl=${mead_scm}?app#${git_ref}
buildrequires=org.example-foobar-common

[app]
type=wrapper
scmurl=${mead_scm}?app#${git_ref}
buildrequires=org.example-app

During the release process, Tito will check in a rendered version of your chain file to dist-git (as well as upload a tarball of the source it is building to the lookaside cache). It will then fire off a build.