View: HTML | Text | PS | PDF | RTF | Wiki | DocBook | DocBook Inline | changelog | about this header Circle Jeff Boweron  
Multi-Build, a Cross-Distro PPA Script

Multi-Build, a Cross-Distro PPA Script

I've been writing little scripts for a while and most of them are single-use things that don't deserve much love or attention. However, I started writing some scripts that I wanted to have on both my work PC and my home PC. Keeping them updated and in sync just became a nightmare, especially when I wanted to put them on one or more of my servers as well. Being a Ubuntu user, I started using Launchpad PPAs which work great. The problem is some of my scripts are much more popular than I had anticipated and getting a Launchpad PPA to work under other distros is tough.

Enter multi-build, a script that is designed to make uploading to a PPA and then creating individually-distributable files much easier. It integrates with my DocBook work and builds off the Ubuntu PPA documentation I wrote a while ago. The net result is automated building and submission to a PPA and then extracting the resulting .deb files and creating .rpm files for our RedHat-loving cousins.


Table of Contents
1. Functionality Overview
2. Usage and Configuration
2.1. Editing .multi-build.conf
2.2. Document Template
2.3. Command Line Options
A. Installation
B. About Me

1. Functionality Overview

The multi-build script is pretty stupid as of now and fairly hardcoded into my own environment. It expects a directory structure like ppasrc/packagename-packageversion and assumes that there's a ~/docs/packagename DocBook entry (if one doesn't exist it's not a big deal, but if it's there you've got some extra fun stuff).

First you'll need to configure it by creating ~/.multi-build.conf. This can set whatever variables you want, but must include ppa=ppaname. For example, my PPA is found at ~ubuntu-ebower/ebower so I specify ubuntu-ebower/ebower. Another variable you can specify is default_series which can be something like precise, oneiric, quantal, etc. By default it will be precise since that's the latest LTS flavor, and I'll change it as new versions get released.

Step one is to use the documentation here to set up a PPA directory including the debian collection. Once that's complete and you're ready to build, instead of using debuild -S and then dput just run multi-build build and it will do some sanity checking (including a new check that I added after I was forced to submit a 1.0.1.1 thanks to a faulty install file). It will automatically update your changelog with the current date, ensure that you've got the version properly set, ensure that your code has a variable version which is set correctly, check that the install files exist, and then run debuild and dput for you.

Now you wait. I hope to do some more automated stuff to help you figure out when the build is complete and to copy the build to new series, but that's for a future date so you'll need to do this manually.

Once you're done, from the same directory run multi-build repackage. This will create a packages directory as necessary, grab the .deb and .tar.gz files from Launchpad, and then create .rpm files from them. If you do have a ~/docs/packagename directory, it will automatically copy the resulting files to there replacing the version number with latest. It will also look for a ~/docs/download-template.docbook file and it will copy it to the directory replacing the text _PACKAGE_NAME_ with the actual package name. My template creates the Appendix A appendix below.


2. Usage and Configuration

This section covers the static configuration information in .multi-build.conf, the variables you can use in the download documentation template, as well as the command-line usage.


2.1. Editing .multi-build.conf

First thing's first, you'll need to create a .multi-build.conf file. This file will set certain variables and default values to help let multi-build know who you are and what you want to do.

You may have multiple .multi-build.conf files which can add new parameters or overwrite existing ones. I first check for ~/.multi-build.conf which should store global information.

I then check for ../../.multibuild.conf which assumes that you use the directory structure ppa/package/package-version and you're running the file in the package-version directory. This configuration file should have PPA-specific information, since I only use one PPA I don't use this but rather have the PPA information in my global file.

Finally, I check for ../.multi-build.conf for package-specific information. Here I set things like a custom documentation directory which only affect a single package.

The file format is very simple, it's simply variablename=value with one line per variable. My example global file is below:

Example 1. Example .multi-build.conf

ppa=ubuntu-ebower/ebower
default_series=quantal

The only required variable in this file is ppa, all of the rest are optional.

ppa

The name of the PPA comprised of the PPA owner and the PPA name. For example, my PPA is ubuntu-ebower/ebower. There is no default value for this.

default_series

Which series you want to use by default for submissions. If not set, the default value will be precise (which will be updated to the latest LTS when they are released). You may wish to change this to whichever series you run, in my case I decided to change it to quantal both because this reduces the impact of new submissions should I discover a typo after submission as well as because quantal doesn't show up in the supported distro list yet so it's the easiest way to get my packages there.

doc_basedir

If you have a documentation directory you may set it here. By default I use ~/docs.

docdir

The directory for the documentation of this package. By default I use the package name, so if your documentation is in $doc_basedir/$package_name you don't need to touch this. Otherwise you can set this, probably in the package-specific config file.

doc_suffix

The suffix to be appended to your documentation file. The filename will be ${package_name}${doc_suffix} and the default value is -download.docbook. This means that the filename for the multi-build package will be multi-build-download.docbook.

download_template

This is the name of the file residing in doc_basedir that contains the text you wish to have modified every time you submit a build. For information regarding how this template may be constructed, please see Section 2.2.

wait_for_build_timer

After submitting the source, it can take a while before the build completes. If you want to copy the package to a new series you'll need to wait for build completion so multi-build will check the status periodically. This value is expressed in seconds any by default will be 900 or 15 minutes.


2.2. Document Template

The document template was written with DocBook in mind, but realistically you could use any sort of plain-text file and it should work. You may specify certain variable names which will be replaced with the real values as I copy them over.

I'll also copy the files to the documentation directory both with the actual filenames as well as files with a static name of ${package_name}-latest_${arch}.deb, ${package_name}-latest-2.${arch}.rpm, and ${package_name}_latest.tar.gz.

_PACKAGE_NAME_

This will be replaced with the actual package name.

_PACKAGE_VER_

This will be replaced with the package version.

_DEB_32_

This will be replaced with the name of the 32-bit .deb file.

_DEB_64_

This will be replaced with the name of the 64-bit .deb file.

_RPM_32_

This will be replaced with the name of the 32-bit .rpm file.

_RPM_64_

This will be replaced with the name of the 64-bit .rpm file.

_TGZ_NAME_

This will be replaced with the name of the .tgz file.


2.3. Command Line Options

The command line options for multi-build are pretty simple, there are only three things it does:

submit

This will perform some sanity checks and then submit the build to Launchpad. As I screw up submissions expect more sanity checks. Note that these checks are based heavily on my own practices (for example, I look for the setting of a version variable in hopes that I remember to update the embedded version number), if they don't work for you let me know and I'll see if I can modify them to something that works better for you.

copy

This will copy the package from your default series to all other available series (except hardy, that's ancient and Launchpad doesn't like it very much). Note that this uses ppa-tools to copy the packages and requires you authorize the app to your Launchpad account. This will open up a webpage that lets you manage the auth token. Both multi-build and ppa-tools are simple scripts so you can read them to see for yourself that I don't do anything malicious, and if you notice me doing anything dangerous please let me know since I've only tested on my own PPA.

repackage

Repackaging your package will download the .deb and .tar.gz files, create .rpm files from them, and then integrate them with your documentation. This is useful if you use a PPA but also have users who need RedHat binaries. Note that to create the .rpm files I'll need root access to preserve the file permissions. Again, open source means you can check to see if I do anything malicious or stupid.

all

This is just a convenience command that sequentially executes the commands above.


A. Installation

Most Ubuntu users should strongly consider using my Launchpad PPA which will help keep your package up-to-date. You can install it with the following commands:


sudo add-apt-repository ppa:ubuntu-ebower/ebower
sudo apt-get update
sudo apt-get install multi-build

If you're not fortunate enough to be able to use this, you can download the packages here:


B. About Me

My name is Jeff Bower, I'm a technology professional with more years of experience in the telecommunications industry than I'd care to admit. I tend to post with the username jdbower on various forums. Writing these documents is a hobby of mine, I hope you find them useful and feel free to browse more at https://www.ebower.com/docs.

If you've got any questions or feedback please feel free to email me at docs@ebower.com or follow me on Google+ or Twitter.