Skip to content
This repository
branch: master
Octocat-spinner-32 extras add a horribly hacky (but very useful) export_img_over_nfs script May 26, 2012
Octocat-spinner-32 misc add Raspberry Pi logo May 07, 2012
Octocat-spinner-32 LICENSE Initial commit. Brown paper bag bugs very likely May 01, 2012
Octocat-spinner-32 README.mkd fix typo June 25, 2013
Octocat-spinner-32 common common: update with info on new release January 07, 2014
Octocat-spinner-32 config config: bump to 3GiB :/ September 25, 2013
Octocat-spinner-32 downgrade_qemu add script to downgrade qemu April 08, 2013
Octocat-spinner-32 f2fsify f2fsify: new script to converting the rootfs of a generated image to … April 17, 2013
Octocat-spinner-32 grow_image grow_image: fix errant /dev/loop0 reference April 15, 2013
Octocat-spinner-32 helper ask_yn now takes printf args and common no longer takes args May 19, 2012
Octocat-spinner-32 qa_checklist.mkd qa_checklist: must fsck images before release to verify them June 14, 2012
Octocat-spinner-32 setup_spindle_environment various fixes to setup_spindle_environment February 03, 2013
Octocat-spinner-32 shrink_image shrink_image: get rid of bits that drop back to shell May 15, 2013
Octocat-spinner-32 wheezy-stage0 wheezy-stage0: set label of boot partition to 'boot' May 15, 2013
Octocat-spinner-32 wheezy-stage1 wheezy-stage1: fix address for my aboriginal rootfs mirror April 08, 2013
Octocat-spinner-32 wheezy-stage2 wheezy-stage2,common: use qemu nameserver during image build July 04, 2013
Octocat-spinner-32 wheezy-stage3 wheezy-stage3: install v4l-utils December 16, 2013
Octocat-spinner-32 wheezy-stage4-lxde wheezy-stage4-lxde: don't let high contrast icons install (too big) January 07, 2014
Octocat-spinner-32 wheezy-stage4-lxde-edu wheezy-stage4-lxde-edu: install x2x January 07, 2014

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

Something went wrong with that request. Please try again.