This is bzr-builddeb, a plugin for bzr that allows you to build Debian packages from a bzr branch.
Note that there is a user manual available at /usr/share/doc/bzr-builddeb/docs/user_manual/index.html that gives more information than this file.
This plugin requires python-debian (at least version 0.1.4), and a version of bzr at least 0.18. The two python modules are available in Debian (though maybe not at the required versions for a development version of builddeb), the former in experimental at the moment.
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 ~/.bazaar/plugins/builddeb, i.e:
bzr branch http://jameswestby.net/bzr/bzr-builddeb/ \ ~/.bazaar/plugins/builddeb
This will give you a bzr builddeb command (alias bd).
Help for this plugin can be found by running bzr help builddeb.
There is also a script named bzr-buildpackage provided in /usr/bin that provides access to the tool as well. It is just a wrapper script that calls bzr 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 bzr-buildpackage ---help (as bzr builddeb --help also works and does the same as bzr 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 bzr-buildpackage package, and so make it easier for people to find the package.
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]
The following options are read from the configuration files. Most can also be used as command line arguments by prepending -- to the names and not using the \= symbol. There are a few exceptions to this that are noted in the descriptions.
These change the directories that the plugin uses for various things.
build-dir = path
The directory in which the build takes place. (Defaults to ../build-area relative to the branch).
result-dir = path
The directory the resulting files will be placed in. (Defaults to whatever is being used for build_dir).
orig-dir = path
The directory to search for the .orig.tar.gz when not in native mode. (Defaults to ../tarballs relative to the branch).
These change the way in which the plugin operates. They can be set depending on the type of package you are building.
merge = True
Turns on merge mode. This is where only the debian/ directory is versioned. It uses and orig.tar.gz for the upstream and combines the two before building. It works with both the debian/ directory in the branch, or the contents of debian/ (e.g. rules, control) directly in the top level directory of the branch. (Defaults to False).
native = True
If you want to build a native package from a branch then turn on this option. It will stop the plugin from looking for an orig.tar.gz and build a native package instead. This has no effect if merge mode is on, as I don't think it makes any sense to version the debian/ separately for a native package. If you disagree let me know.
split = True
This takes a package from a branch that includes both the upstream source and the debian/ dir and creates a non-native package from it by creating an orig.tar.gz from the code outside of debian/. This is probably most useful if you are bot upstream and Debian maintainer of a non-native package. This has no effect if merge or native are true, the former is for use when you don't version the full source, the second for when you don't need an orig.tar.gz so they make no sense to be used together.
export-upstream = path
This option takes a path (remote or local) to a bzr branch that contains the upstream code. If this is set then the plugin will export the code from that branch to create the .orig.tar.gz. This option only has any effect if merge is set, and causes any orig-dir setting to be ignored.
When the upstream source is in bazaar and you use the export-upstream mode then these options control how the plugin interacts with the upstream branch.
export-upstream-revision = revision
This sets the revision that the upstream code will be branched at. It takes the same revision spec as the normal --revision parameter. Use it to associate an upstream version number with a particular revision of the upstream code. This has no effect if export-upstream is not set.
export-upstream-prepull = True
This allows for the case where you want to use a local mirror of the upstream source, but want to build automatically. It does a pull in the local branch before exporting it. It is your responsibility to setup the default pull location for the branch. It probably doesn't make too much sense to use this option with the export-upstream-revision one as this will change the tip, but then wont use it. However this is allowed. This option only has an effect if export-upstream is set. Also note that this option cannot be used when export-upstream is set to a remote branch. [Not a command line option.]
export-upstream-stop-on-trivial-pull = True
This allows you to stop the build if the upstream pull doesn't pull any revisions. It is designed for automated builds where you don't want to bother building if there have been no changes. It has no effect unless the export-upstream-prepull option is true. [Not a command line option.]
These configure the commands that are used to build the package in different situations.
builder = command
The command to use to build the package. Defaults to dpkg-buildpackage -rfakeroot -uc -us). Will only be read from the file in your home directory.
quick-builder = command
The command used to build the package if the --quick option is used. (Defaults to fakeroot debian/rules binary). Will only be read from the file in your home directory.
source-builder = command
The command used to build a source package if the --short or -S options are used. Overriden if --builder or --quick are given on the command line. (Defaults to dpkg-buildpackage -rfakeroot -uc -us -S). Will only be read from the file in your home directory.
working-tree = True
Always build the working tree, rather than the last revision committed to the branch.
The idea is that certain options can be set in .bzr-builddeb/default.conf that apply to the package on all systems, or that there is a default that is wanted that differs from the default provided. merge = True is a perfect example of this.
Then the user can override this locally if they want for all of their packages (they prefer builder = pdebuild), so they can set this in ~/.bazaar/builddeb.conf. They can override it for the package if they want (e.g. they have a different location for upstream tarballs of a package if they are involved with upstream as well, so they set orig_dir = /home/.../releases/), this can be done in .bzr-builddeb/local.conf).
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 bzr 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:
$ bzr 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 bzr 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.
Merge mode is when only the debian/ directory of the package is versioned, with the upstream version of the code living elsewhere. It allows for clear separation of the Debian specific changes from the upstream code.
If you want to use merge mode you need to create a tarballs directory for the .orig.tar.gz files:
$ cd path/to/project $ mkdir tarballs
Then copy the .orig.tar.gz file for the current version in to this directory. If you do not have the upstream tarball for the current version, but you do have a watch file detailing where it can be found then the plugin will automatically retrieve the tarballs as they are needed.
If upstream holds their code in a bzr branch then you don't need to create the tarballs yourself, you can instead have the plugin export the upstream code and create the tarball itself using the export-upstream option. You need to be careful with this, as if you do not change the upstream version in the debian/changelog and upstream makes some commits then the .orig.tar.gz will change without being reflected in the version number. This can be disastorous if it happens across uploads of the package. Use export-upstream-revision to avoid this. You might be especially interested in the use-existing flag to the plugin to save having to branch the upstream code every build. You might also want to make a local mirror.
Now create the branch for the debian/ directory:
$ bzr init project
Now you can either create a project/debian/ directory for all the files, or add them in the project directory.
Now tell bzr-builddeb that this is a merge mode project:
$ cd project/ $ mkdir .bzr-builddeb/ $ echo -e "[BUILDDEB]\nmerge = True" > .bzr-builddeb/default.conf
Now you are ready to create the project. Create the usual files, and edit them to your satisfaction. When you have the files run:
$ bzr add $ bzr ci
from the root of the project branch.
You are now ready to build the project. See below for instructions on doing this.
This is a little simpler to set up. Create the branch for the project:
$ cd path/to/project $ bzr init project
Now add all the project files to the branch, and add the to bzr:
$ cd project $ bzr add $ bzr ci
There are two options when you want to build a Debian package, whether it is a native package or not. Most packages are non-native so I will desribe that first.
To create a non-native package you need an upstream tarball to build against. Set the orig-dir variable to the directory containing the tarball that you want to use and the plugin will pick it up and you will have a non-native package. If you do not have the upstream tarball corresponding to the version of the package you are trying to build, but you have a watch file detailing where it can be found then it will be automatically retrieved when needed.
However sometimes you might be upstream of a package as well as Debian maintainer, but it is not a native package. In that case you may version the whole source including debian/, but not want to have to manually make a tarball without the debian/ directory. In that case see the split variable. If you set that then the plugin will create you an appropriately named orig.tar.gz of everything outside of debian/.
If you want to have a native package you don't need to worry about orig-dir, but instead set native = True in the .bzr-builddeb/default.conf file (make sure it starts with [BUILDDEB] if you create it).
Now you are ready to build using the plugin.
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:
$ bzr 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:
$ bzr 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.
If you are trying to solve a problem, and you are trying lots of different fixes you might not want to commit every time. If this is the case you can tell bzr-builddeb to build from the working tree, rather than the branch. This means that just editing files will be enough to change a build, rather than the default, which requires a check-in of all changes before building. To do this use the --working-tree option, or more succinctly:
$ bzr bd -w
If you also 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:
$ bzr 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.
bzr-builddeb is designed to fit in with the workflow that bzr encourages. It is designed as a plugin, so that it just becomes one more bzr command that you run while working on the package.
It also works fine with the frequent branching approach of bzr, 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.
This README is Copyright (C) 2006 James Westby <jw+debian@jameswestby.net> and is distributed under the following terms:
This file is part of bzr-builddeb. bzr-builldeb is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. bzr-builddeb is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with bzr-builddeb; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA