Running the Balsa Builder

From LSDevLinux
Revision as of 09:13, 6 May 2014 by Peacocw (talk | contribs) (Basic usage: Expand note on ''balsa-results/cache'')

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


This page describes how a bootable Balsa image is produced. This process is meant to be undertaken by a maintainer or distributor of Balsa only. It is not intended to be performed by language advisers or on-site technicians. They should download the finished image for installation to an SD card.

Resources needed and notes

  1. You will need a machine running Linux. The Balsa Builder has been tested on Debian and Ubuntu distributions.
  2. You will need sudo permissions on your account. The balsa builder requires root access.
  3. You will need a Ubuntu CD. You can download the required tools from However, the builder can work with just the CD image file (.iso) so burning it to physical media is optional. Download the 32 bit desktop Ubuntu release corresponding to the current Balsa release. The CD downloaded images are about 700MB each.
  4. You will need an internet connection. The builder itself is about 90MB, and will download another 655MB as it runs. The builder maintains local copies of the files that it has downloaded, so second and subsequent runs of the builder will only download files that have changed. The total download size is slightly larger than for downloading a built image, so using the builder is useful only if you want to customize the process, or keep up with improvements to the builder as they are released.
  5. You will need at least 20 GB of free space. As of Jul-2013, the balsa-results folder is 18GB after the initial build.
  6. You will need to have the git package installed.
  7. Some partitions are mounted with nosuid,nodev options. The builder will not run on those partitions. In particular, if you set up Ubuntu with a separate home partition, it will have these options set by default. To run the builder, you can use a different partition or change these options.
    1. To use a different partition, cd to a different partition, e.g. /var/tmp before you use the git command below. Or,
    2. To change the options:
sudo <your_favorite_text_editor> /etc/fstab
Locate the line that contains /home as the second item on the line. On the same line, remove the nosuid,nodev

Initial preparation

Obtain an up-to-the-minute version of balsa-build using git as follows:

git clone git://

To keep this updated in the future, you will just need to run:

git pull

in the newly created balsa-builder directory.

To use the current precise build:

git checkout precise

Basic usage

Insert the Ubuntu CD (but don't run it). Alternatively, you can "loop-mount" the .iso file like this:

sudo mount -o loop ubuntu-12.04-desktop-i386.iso /mnt

Note that the builder will find the CD image regardless of where you mount it.

Open a terminal and use cd to get to the newly created balsa-builder directory. Run this command:


This command will build a Balsa installation into the balsa-results directory, which is a sibling to the balsa-builder directory.

The balsa-results directory contains three subdirectories:

  • balsa-results/logs - contains log files of previous builds. The latest is in balsa-results/logs/latest_log
  • balsa-results/build - contains the built balsa files and image.
  • balsa-results/cache - contains cached packages downloaded during previous builds. The builder looks here first for the packages needed. Only the packages that have changed since the last update will be downloaded.

Advanced usage

If at any time you wish to run individual parts of the installer, you can put one or more of the following words after the script name:

Command      Description
prerequisites Makes sure you have the right programs installed to build Balsa
base Creates the base system image. It is a plain Ubuntu install. The only step that requires the Ubuntu CD or .iso
teapot Modifies the plain Ubuntu image. Historically this was to make it XO compatible. Balsa no longer supports the XO.
balsa Modifies the teapot image to make it a Balsa image
image_8 Makes the image for a 8Gb Balsa SD card
zip_8 Compresses the 8Gb Balsa image

For example, if you already have a Ubuntu image, you could redo the Teapot and Balsa process without creating a new image like this:

./ teapot balsa

Note that while all the other options don't ask for confirmation, the prerequisites option does, as it is changing the programs installed on your host system.