Skip to content


Repository files navigation

spindle - a tool to help spin distribution images


spindle is a set of scripts to aid building and working on a distribution image. I've been using this tool to generate Debian wheezy images for the Raspberry Pi, with the aim of producing reproducible, unbooted, clean setups that require no manual intervention. It works by producing a series of image files in QEMU's QED format (I exploit the format's support for backing files and copy on write).

It's not massively user friendly yet, but hopefully that should soon change (and of course, patches are welcome).

Project links

Current scripts

  • setup_spindle_environment: Sets up an schroot using wheezy and installs the pre-requisites needed for spindle (mainly QEMU, as it turns out I haven't used augeas). If you don't use this, please make sure you have at least QEMU 1.0.1
  • wheezy-stage0: Create and partition an SD card image, perform the initial debootstrap on the host and copy the files to the SD image.
  • wheezy-stage1: Complete second stage of debootstrap under QEMU after first setting up a squashfs filesystem derived from Rob Landley's excellent Aboriginal Linux. Setup dropbear.
  • wheezy-stage2: Add in Raspberry Pi 'firmware' and do misc config (e.g.
    fstab, network interfaces, hostname). The resulting image is bootable.
  • wheezy-stage3: Install and configure a few useful packages (such as ifplugd, sudo).
  • wheezy-stage4-lxde: Set up the lxde desktop.
  • wheezy-stage4-lxde-edu: Install MIT Scratch, Python development tools and other packages.

Getting started

The following describes how to start building SD card images using spindle.
The process isn't massively user friendly for people with no experience at all, but if you're currently doing this by hand then hopefully you'll find it helpful. Note that executing the downgrade_qemu script is necessary on most Debian and Ubuntu versions right now.

sudo ./setup_spindle_environment  my_spindle_chroot
sudo modprobe nbd max_part=16
schroot -c spindle
sudo ./downgrade_qemu
./helper export_image_for_release out/stage4-lxde.qed stage4-lxde.img

Now you can write stage4-lxde.img to SD card.

Take a look at wheezy-stage4-lxde to see how to add your own stage if you want further customisation.


If you want to contribute, please do file issues on the bug tracker or send in patches/pull requests.

spindle is written in POSIX shell script and tries to make use of QEMU where possible for manipulating the filesystem of the target being generated. Look at the current scripts for examples. Please do talk to me if you're thinking of any large refactoring.

Good resources for shell scripting include:


MIT. See the LICENSE file.


Author: Alex Bradbury