rbm_tutorial(7)

1RBM_TUTORIAL(7)                                                RBM_TUTORIAL(7)
2
3
4

NAME

6       rbm_tutorial - A tutorial introduction to rbm
7

DESCRIPTION

9       This tutorial will explain how to start using rbm to build rpm and
10       debian packages for different distributions.
11
12       In this example we will package the tor software.
13

CREATING A NEW WORKSPACE

15       The first step is to create a rbm workspace. In this example, we will
16       use ~/rbm, but you could use anything :
17
18           $ mkdir ~/rbm
19           $ cd ~/rbm
20
21       The first thing to do is to create the main configuration file, which
22       will contain the configuration for all projects in this workspace. For
23       now, we will just add the compress_tar option, and add more options
24       later when needed.
25
26           $ cat > rbm.conf <<END
27           compress_tar: xz
28           END
29
30       The compress_tar options means that we want tarballs to be compressed
31       using xz.
32

CREATING A NEW PROJECT

34       We will now add the tor project. To do this we just create the
35       directory inside the projects directory, and put a config file inside
36       containing the configuration for the project. The main option that we
37       will set is git_url, which is the url used to clone the git repository
38       of the software. If your project is using mercurial rather than git,
39       you could set hg_url instead.
40
41           $ mkdir -p projects/tor
42           $ cat > projects/tor/config <<END
43           git_url: https://git.torproject.org/tor.git
44           END
45
46       We can check that the project is correctly defined using the projects
47       command :
48
49           $ rbm projects
50           tor
51
52       And we can display the tor project configuration using the showconf
53       command :
54
55           $ rbm showconf tor
56           ---
57           git_url: https://git.torproject.org/tor.git
58

VERSION SETTINGS

60       The first thing to do when adding a new project is to configure the
61       version settings: rbm needs to be able to compute the version of the
62       software, for any git commit.
63
64       By default, rbm will use the latest tag on which a commit is based as
65       the version number. Sometimes it works, when the project uses version
66       numbers as tags, but this is not always the case. Alternatively, you
67       can define a var/version_command option with a shell script or command
68       that will print the version number.
69
70       For tor, we will use a var/version_command option. The version of the
71       software is defined in the ChangeLog file, so we will use a simple
72       command to get it. The tor config file now look like this :
73
74           git_url: https://git.torproject.org/tor.git
75           version: '[% exec(c("var/version_command")) %]'
76           var:
77             version_command: perl -ne 'if (m/^Changes in version ([^-]+)-.*$/) { print "$1\n"; exit }' < ChangeLog
78
79       Using the showconf command, we can check the value of the version
80       option for different commits :
81
82           $ rbm showconf tor version --git-hash master
83           0.2.5.1
84           $ rbm showconf tor version --git-hash tor-0.2.4.17-rc
85           0.2.4.17
86
87       The first time you run this command, the git repository will have to be
88       cloned, which can take some time.
89

CREATING A TARBALL

91       After setting the configuration for the version, we are now ready to
92       create a tarball based on a git commit. We can do this using the tar
93       command :
94
95           $ rbm tar tor --git-hash master
96           Created /home/boklm/rbm/out/tor-0.2.5.1.tar.xz
97           $ rbm tar tor --git-hash tor-0.2.4.17-rc
98           Created /home/boklm/rbm/out/tor-0.2.4.17.tar.xz
99

BUILDING AN RPM PACKAGE

101       In order to build rpm packages, you will need to define an rpm step
102       (see rbm_steps(7)) in rbm.conf.
103
104       The rbm.conf file should define an rpm option containing the commands
105       to build an rpm package:
106
107           rpm: |
108             #!/bin/bash
109             [ here the commands for building an rpm package ]
110
111       Unfortunately, this part of the tutorial, with details about the
112       definition of the rpm step has not been written yet.
113
114       You should be able to start a build with the build command and the
115       --step option:
116
117           $ rbm build --step rpm tor
118

BUILDING A DEBIAN PACKAGE

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

USING A BUILD CONTAINER

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