RBM_TUTORIAL(7)

✨ rbm_tutorial ✨

okay bestie, gather round, we're learning rbm_tutorial 💖 (that's the page name, and also literally what this is: a tutorial intro to rbm)

---

🌸 NAME 🌸

rbm_tutorial — a tutorial introduction to rbm, but make it actually make sense 🫶

---

💅 DESCRIPTION 💅

So this tutorial is gonna walk you through starting to use rbm to build rpm and debian packages for different distributions. no gatekeeping here.

And for the example we're packaging the tor software. iconic choice tbh.

---

🎀 CREATING A NEW WORKSPACE 🎀

Step one, bestie: make yourself an rbm workspace. In this example we're using ~/rbm, but fr fr you could use literally anything:

$ mkdir ~/rbm
$ cd ~/rbm

Now the first thing you gotta do is create the main configuration file, which holds the config for all the projects in this workspace. For now we're just adding the compress_tar option, and we'll add more options later whenever we need them. lowkey minimal, highkey efficient.

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

And what does compress_tar do? It means we want tarballs compressed using xz. periodt. ✨

---

🦋 CREATING A NEW PROJECT 🦋

Next up we're adding the tor project. To do that we just make the directory inside the projects directory and drop a config file in there with the configuration for the project. The main option we're setting is git_url, which is the url used to clone the git repository of the software. And if your project uses mercurial instead of git, no worries — you could set hg_url instead. iykyk.

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

We can vibe 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

look at that. she's defined. 💅

---

⭐ VERSION SETTINGS ⭐

First thing you do when adding a new project: configure the version settings. rbm needs to be able to compute the version of the software, for any git commit. no exceptions.

By default, rbm will use the latest tag on which a commit is based as the version number. Sometimes that works — when the project uses version numbers as tags — but bestie, that 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. your call.

For tor, we're gonna use a var/version_command option. The version of the software is defined in the ChangeLog file, so we'll use a simple command to get it. The tor config file now looks 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

heads up 🫶 the first time you run this command, the git repository will have to be cloned, which can take some time. go get a snack, you've earned it.

---

🌈 CREATING A TARBALL 🌈

Okay so now that the version configuration is set, we're ready to create a tarball based on a git commit. We do this with 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

ate. 🍓

---

👑 BUILDING AN RPM PACKAGE 👑

To build rpm packages, you're gonna need to define an rpm step (peep rbm_steps(7) for that) 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 — the whole details-about-the-definition-of-the-rpm-step thing — has not been written yet. it's giving "coming soon" energy, not gonna lie.

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. And yeah — this part of the tutorial has not been written yet either. 💀 same vibe, different step.

---

🔥 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 🙈. But bestie, you can look at the Tor Browser build repository for an example:

https://gitweb.torproject.org/builders/tor-browser-build.git/

---

💜 SEE ALSO 💜

• rbm(1)

---

and that's the whole page, bestie 🥰 go build something gorgeous. this was rbm_tutorial(7) from the 07/25/2025 era — mwah, drink some water, clone that repo, slay 💖✨🎀