rbm/doc/rbm_tutorial.asc

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 the 'version_command' option with a shell script or command that
will print the version number.

For tor, we will use the '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_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
-----------------------

TODO

Building a debian package
-------------------------

TODO

Using a remote build server
---------------------------

TODO

SEE ALSO
--------
link:rbm.html[rbm(1)]