Lib.rs

Overview

This is brz-debian, a plugin for Breezy that allows you to build Debian packages from a Breezy compatible branch, like a Git repository or a Bazaar branch.

Note that there is a user manual available at /usr/share/doc/brz-debian/user_manual/index.html that gives more information than this file.

Installation

This plugin requires python-debian and Breezy.

It also requires the dpkg-dev package to be installed (for the dpkg-mergechangelogs tool):

apt install dpkg-dev

This plugin can be installed in two ways. As you are probably using a Debian system you can probably just use the Debian packages. The other way is to branch it in to ~/.breezy/plugins/debian, i.e:

brz branch https://code.breezy-vcs.org/breezy-debian/trunk/ \
  ~/.config/breezy/plugins/debian

This will give you a brz builddeb command (alias bd).

Help for this plugin can be found by running brz help builddeb.

There is also a script named brz-buildpackage provided in /usr/bin that provides access to the tool as well. It is just a wrapper script that calls brz builddeb with the arguments you provide, so the rest of the documentation applies equally well to using this script. Probably the only difference is that help will be got with brz-buildpackage ---help (as brz builddeb --help also works and does the same as brz help builddeb). The script is provided for two reasons, the first is similarity to the other -buildpackage systems, and the second is so that the Debian package can provide the brz-buildpackage package, and so make it easier for people to find the package.

Configuration

There are also configuration files that can be used, these are, in the order that values will be used if found:

* .bzr-builddeb/local.conf (in the package directory)
* ~/.bazaar/builddeb.conf
* .bzr-builddeb/default.conf (in the package directory)

The last of these should be used for values that will be used by all users of the package, for instance 'merge = True'. The others are for the user to add or override settings that are specific to them, either globally or per package.

There is one complication to this however. As arbitrary commands can be specified for some of the options there is a potential security hole. This is closed by only taking these options from the configuration file in your home directory, which can't be changed by another committer to the branch. I apologise if this breaks your setup, and if you can't work around it please talk to me to try to find an approach that satisfies you and does not open any security holes.

These files must start with:

[BUILDDEB]

Creating a package

Below are instructions for creating a package. These instructions differ depending on whether you want to use merge mode or not.

First the common start create a directory to hold your work. This is not absolutely necessary, but as you still get all the power of brz when using this plugin, so you might want to branch etc. and so this will be useful later on:

$ mkdir path/to/project

If you are going to be using branches then the following is a good optimisation you can use:

$ brz init-repo --trees path/to/project

Now create your global config file if you want to change something like the builder in use, or have a global result directory or similar:

$ echo "[BUILDDEB]" > ~/.bazaar/builddeb.conf
$ $EDITOR ~/.bazaar/builddeb.conf

and any options that you want.

I will describe creating a new project, but for existing projects you can copy the code over and call brz init then continue in the same way.

I will also describe the setup that conforms to the default options for directories. If you wish to use a different layout set up the options to your liking and tweak the commands below as necessary.

$ brz init project

$ cd project/
$ mkdir .bzr-builddeb/
$ echo -e "[BUILDDEB]\nmerge = True" > .bzr-builddeb/default.conf

$ brz add
$ brz ci

$ cd path/to/project
$ brz init project

$ cd project
$ brz add
$ brz ci

Building a Package

Once your package is set up then building it is easy. Run the following command from the top-level of the project branch, after checking in all changes:

$ brz bd

If you used the default options this should build the package and leave the resulting files in ../build-area.

Note that most of the options can be used as parameters to this command as well by prefixing their name with --. So you can do for example:

$ brz bd --builder pdebuild

to change from what is in the configuration files. Note that there is currently no way to set the binary options to false if they are set to true in the configuration files. It would be possible to allow this, but it would bloat the code and the help listings quite a lot, so I will only it if asked to.

Tips

If you have a slow builder defined in your configuration (for instance pdebuild, you can bypass this by using the --quick option. This uses whatever the quick_builder option is (defaults to fakeroot debian/rules binary).

If you are running in merge mode, and you have a large upstream tarball, and you do not want to unpack it at every build you can speed things up even more. This involves reusing the tarball each build, so saving the need to unpack it. To do this run:

$ brz bd --export-only

once to create a build-dir to use. (-e is the short option for this). Then on the next builds you can use the --reuse and --dont-purge options to keep using this build directory. N.B. This may cause build problems, especially if files are removed, it is advisable to run a build without --reuse after removing any files.

Workflow

brz-debian is designed to fit in with the workflow that brz encourages. It is designed as a plugin, so that it just becomes one more brz command that you run while working on the package.

It also works fine with the frequent branching approach of brz, so that you can branch to test something new for the package, or for a bug fix, and then merge it back in to your main branch when it is done.