rbm_tutorial(7)

NAME

rbm_tutorial - A tutorial introduction to rbm

DESCRIPTION

This tutorial will explain how to start using rbm to build rpm and debian packages for different distributions.

In this example we will package the tor software.

Creating a new workspace

The first step is to create a rbm workspace. In this example, we will use ~/rbm, but you could use anything :

$ mkdir ~/rbm
$ cd ~/rbm

The first thing to do is to create the main configuration file, which will contain the configuration for all projects in this workspace. For now, we will just add the compress_tar option, and add more options later when needed.

$ cat > rbm.conf <<END
compress_tar: xz
END

The compress_tar options means that we want tarballs to be compressed using xz.

Creating a new project

We will now add the tor project. To do this we just create the directory inside the projects directory, and put a config file inside containing the configuration for the project. The main option that we will set is git_url, which is the url used to clone the git repository of the software. If your project is using mercurial rather than git, you could set hg_url instead.

$ mkdir -p projects/tor
$ cat > projects/tor/config <<END
git_url: https://git.torproject.org/tor.git
END

We can check that the project is correctly defined using the projects command :

$ rbm projects
tor

And we can display the tor project configuration using the showconf command :

$ rbm showconf tor
---
git_url: https://git.torproject.org/tor.git

Version settings

The first thing to do when adding a new project is to configure the version settings: rbm needs to be able to compute the version of the software, for any git commit.

By default, rbm will use the latest tag on which a commit is based as the version number. Sometimes it works, when the project uses version numbers as tags, but this is not always the case. Alternatively, you can define a var/version_command option with a shell script or command that will print the version number.

For tor, we will use a var/version_command option. The version of the software is defined in the ChangeLog file, so we will use a simple command to get it. The tor config file now look like this :

git_url: https://git.torproject.org/tor.git
version: '[% exec(c("var/version_command")) %]'
var:
  version_command: perl -ne 'if (m/^Changes in version ([^-]+)-.*$/) { print "$1\n"; exit }' < ChangeLog

Using the showconf command, we can check the value of the version option for different commits :

$ rbm showconf tor version --git-hash master
0.2.5.1
$ rbm showconf tor version --git-hash tor-0.2.4.17-rc
0.2.4.17

The first time you run this command, the git repository will have to be cloned, which can take some time.

Creating a tarball

After setting the configuration for the version, we are now ready to create a tarball based on a git commit. We can do this using the tar command :

$ rbm tar tor --git-hash master
Created /home/boklm/rbm/out/tor-0.2.5.1.tar.xz
$ rbm tar tor --git-hash tor-0.2.4.17-rc
Created /home/boklm/rbm/out/tor-0.2.4.17.tar.xz

Building an rpm package

In order to build rpm packages, you will need to define an rpm step (see rbm_steps(7)) in rbm.conf.

The rbm.conf file should define an rpm option containing the commands to build an rpm package:

rpm: |
  #!/bin/bash
  [ here the commands for building an rpm package ]

Unfortunately, this part of the tutorial, with details about the definition of the rpm step has not been written yet.

You should be able to start a build with the build command and the --step option:

$ rbm build --step rpm tor

Building a debian package

Similarly to the rpm package, building debian packages will require that you define a deb step in rbm.conf. This part of the tutorial has not been written yet.

Using a build container

Using the remote options (see rbm_remote(7)) you can do the builds inside containers. Unfortunately this part of the tutorial has not been written yet. However you can look at the Tor Browser build repository for an example: https://gitweb.torproject.org/builders/tor-browser-build.git/