Running the Balsa Builder
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
- You will need a machine running Linux. The Balsa Builder has been tested on Debian and Ubuntu distributions.
- You will need sudo permissions on your account. The balsa builder requires root access.
- You will need a Ubuntu CD. You can download the required tools from ubuntu.com. 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.
- 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.
- You will need at least 20 GB of free space. As of Jul-2013, the balsa-results folder is 18GB after the initial build.
- You will need to have the git package installed.
- 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.
- To use a different partition, cd to a different partition, e.g. /var/tmp before you use the git command below. Or,
- 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
Obtain an up-to-the-minute version of balsa-build using git as follows:
git clone git://git.lsdev.sil.org/balsa-builder.git
To keep this updated in the future, you will just need to run:
in the newly created balsa-builder directory.
To use the current precise build:
git checkout precise
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.
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:
|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 |
|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:
./build-balsa.sh 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.