Other things on this site...

MCLD
music
Evolutionary sound
Listen to Flat Four Internet Radio
Learn about
The Molecules of HIV
MCLD
software
Make Oddmusic!
Make oddmusic!

How to package SuperCollider for Debian and Ubuntu Linux

SuperCollider works on Linux just great. I've been responsible for one specific part of that in recent years, which is that when a new release of SuperCollider is available, I put it into the Debian official package repository - which involves a few obscure admin processes - and then this means that in the next releases of Debian AND Ubuntu, it'll be available really easily.

These are my notes to help others understand how it's done.

First a few words: on Ubuntu you can also make SuperCollider available through an Ubuntu "PPA", and there's even a sort-of-official PPA where you can get it. Some people like this because it happens much quicker (there's less official approval needed). I strongly advise maintainers: it's really valuable to go through the Debian official repository, even though it's slower. There's no need to feel rushed! Getting it into Debian often means fixing a few little packaging quirks to make sure it installs nicely and interoperates nicely, and your work will result in much wider benefit. It's OK to do the PPA thing as well, of course, but you mustn't rely purely on the PPA. (You may as well do the debian thing and then repurpose the same codebase for PPA.)

The things I'm going to cover, i.e. the things you'll need to know/do in order to get a new SuperCollider release into Debian, include:

  1. joining the debian-multimedia team
  2. debian's lovely way of using git together with buildpackage
  3. importing a fresh sourcecode release of SC into the git
  4. compiling it, checking it, releasing it

But I'm mainly going to do this as a step-by-step walkthrough, NOT a broad overview. Sorry if that means some things seem unexplained.

DO IT IN DEBIAN

I'm an Ubuntu user normally, but to keep things clean I do this work in a Debian virtual machine, by using Virtualbox. Ubuntu is based on Debian so you might think you can do it directly in Ubuntu but in practice it tends to go wrong because you end up specifying the wrong versions of package dependencies etc.

Of course, Ubuntu "inherits" packages from Debian, so after we push the Debian package it will magically appear in Ubuntu too.

In the debian you'll also need these packages, which you can get from apt install as normal:

  • build-essential
  • git-buildpackage
  • cmake

You'll also need to install whatever is needed ordinarily to compile SuperCollider - check the readme. (There's a tool mk-build-deps which can help with this, as long as the dependencies haven't changed since the previous SC.)

GET THE DEBIAN-FLAVOURED CODE

The Debian "multimedia team" has a special git repository of their own, which contains the released version of SuperCollider plus the debian scripts and metadata.

Here are shell commands for fetching the git repo and specifically checking out the three branches that are used in debian's git-buildpackage workflow:

git clone https://anonscm.debian.org/git/pkg-multimedia/supercollider.git
cd supercollider
git checkout -b upstream origin/upstream
ls
git checkout -b pristine-tar origin/pristine-tar
ls
git checkout master
ls

If you do those "ls" commands you get a rough idea of what's in the 3 branches:

  1. "upstream": this should be the exact same as the contents of the "-Source-linux.tar.bz2" sourcecode downloaded from the main SuperCollider release.
  2. "master": this is the same as upstream EXCEPT that it has the special "debian" folder added, which contains all of the magic to compile and bundle up SuperCollider correctly.
  3. "pristine-tar": the file layout in here is very different from the others. It's simply an archive of all the source code tar files, created automatically.

This might seem a bit arcane, but don't change it - the debian "git-buildpackage" scripts expect the git repo to be laid out EXACTLY like this.

A shortcut that actually pulls all three branches is provided by gbp:

gbp clone https://anonscm.debian.org/git/pkg-multimedia/supercollider.git

but I'm doing it explicitly because it's kinda useful to get a bit of an idea what's going on in those three branches.

IMPORTING A FRESH SOURCE CODE RELEASE

Let's imagine the main SuperCollider team have released a new version, including putting a new sourcecode download on the website. IMPORTANT: it needs to be the "-Source-linux.tar.bz2" version, because that strips out some Windows- and Mac-specific stuff. Some people don't care about whether there's extra Windows and Mac cruft in a zip file, but the Debian adminstrators do care, because they monitor the code in the repository to be careful there's no non-free material in there etc.

Do this every time there's a new release of SuperCollider to bundle up:

  1. Run uscan which checks the SuperCollider website for a new source code download. If it finds one it'll download it, and it'll also automatically repack it (removing some crufty files that are either not needed or lead to copyright complications). It puts the resulting tar.gz in ../tarballs. You can run uscan --verbose and it'll show some text details that might help you understand what actions the program is actually doing.
  2. Run gbp import-orig --pristine-tar --sign-tags ${path-to-fetched-tarball} the path, for me at least, is ../tarballs/ followed by the actual tarball file. Make sure it's the "repack" one. The procedure will check with you what the upstream version number is. Is it "3.8.0~repack"? No, it's "3.8.0".
  3. Refresh the patches. What this means is, the debian folder has a set of patches that it uses to modify the supercollider source code, to fix problems. These patches might not apply exactly to the new code, so we need to go through,

    export QUILT_PATCHES=debian/patches
    quilt push -a
    quilt refresh
    quilt pop      # repeat refresh-and-pop until all are popped
    

    Did you run the last two lines again and again? Eventually it says "No patches applied".

    After this, it's a good idea to do a git commit debian to store any changes you made to the patches in a git commit of their own.

    You may need to remove a patch - typically, this happens if it's been "upstreamed". To do that, you can git rm the patch itself as well as edit its name out of debian/patches/series, then commit that. You may also find you need to make a new patch, to fix some issue such as getting the latest code to build properly on all the architectures that Debian supports.

    (Recently the debian admins have started using gbp pq to look after the patches. Maybe that's useful. I haven't got into it yet.)

  4. Create a changelog entry.

    gbp dch -a debian

Here's something that might be surprising: the changelog file is what tells debian which version of SC it's building. If it sees 3.7.0 as the top item, it tries to build from 3.7.0 source. It doesn't matter what's been happening in the git commits, or which source code you have downloaded. So if you're importing a new version you have to make sure to add a new entry to the top of the changelog. Hopefully the pattern is obvious from the file itself, but you can also look at general Debian packaging guidelines to understand it more.

NOW TEST THAT IT BUILDS

First let's get gbp to build a debian style source package. (You may be wondering: we started with SuperCollider's original source code bundle, why are we now building a source code bundle? This is different, it makes a .dsc file that could be used to tell the Debian servers how to compile a binary.)

The main reason I'm telling you to do this is that it performs some of the build process but not the actual compiling. So it's a good way to check for any errors before doing the hardcore building:

gbp buildpackage -S --git-export-dir=../buildarea

This will also run lintian to check for errors in rule-following. Debian's rules are quite strict and you'll probably find some little error or other, which you should fix, then do a git commit for, then try again.

You can also then build proper binary debs:

gbp buildpackage --git-export-dir=../buildarea

This might take a long time. Eventually... it should produce some .deb files. It might even ask you to sign them.

THINGS YOU MAY HAVE TO CHANGE

  1. SuperCollider uses "boost" code library. SuperCollider comes bundled with a recent version of it, and the exact version gets updated now and again. Debian makes this a little more complicated - they don't want to use the bundled version, instead they want to use the version that's built in to debian. So if you look in debian/control you'll see some "libboost" dependencies specified. If SuperCollider's dependency has changed, you may need to update this to get it building properly. You'll also need to use apt install to fetch those boost dependencies.
  2. If SC source code files get renamed or the folders change, it's fairly common that you need to edit one of the text files in the debian folder to point it at the right thing.

NOW TEST THAT IT RUNS

You've successfully made the .deb files, i.e. the actual installable binaries. Install them on your system. You can do it using dpkg -i like you would with most deb files, or for convenience you can use the debi command which makes sure you're installing the whole set of packages you've built:

debi ../buildarea/supercollider_3.8.0-1_*.changes

NOTE that this installing step is "real" installing. If you're working in a virtualbox like I am then you're probably not worried about whether you'll be overwriting your existing SC. Otherwise do bear in mind - this install will overwrite/upgrade the SC that's installed on your system.

Once installed, run it, make sure the thing is OK.

NOW PUBLISH THIS STUFF

In order to get this stuff actually live on the official debian package system, you need to do a few things. You'll need to join "debian multimedia team" as a guest (see their webpages for more info on that), and once you've done that it gives you permission to push your git changes up to their server:

git push origin master upstream pristine-tar
git push --follow-tags

Then after that you need to do a "request for upload" - i.e. asking one of the debian multimedia team with upload rights, to give it a quick check and publish it. You do this via the debian multimedia team mailing list. It's also possible to get upload rights yourself, but that's something I haven't gone through.

CONCLUSION

So there we have it. Thanks to Felipe Sateler and other Debian crew for lots of help inducting me into this process.

Interested in helping out? Whether it's SuperCollider or some other audio/video linux tool, the Debian MultiMedia team would love you to join!

P.S. some added notes from Mauro about using Docker as part of this

| supercollider | Permalink

social