This document describes how to build a Vyatta VC4 (Glendale) ISO image.
The most recent version of this document is the top-level README file of
the "glendale" branch of the "build-iso" source tree.

Prerequisites

The Vyatta ISO build uses the "live-helper" tool that is available
in several distributions. However, we recommend build hosts
based on either Debian "lenny" or Ubuntu "hardy". The "build-iso"
source is maintained as a GIT super-module that references several
submodules that each build one or more self named Debian
packages. The submodule feature was added to GIT v1.5.2.

Build Host Setup

To set up a build environment (e.g., system or VM), we recommend
installing Debian "lenny" (i.e. "testing") with either business-card
or net-install image,

http://cdimage.debian.org/cdimage/daily-builds/daily/arch-latest/i386/is...
http://cdimage.debian.org/cdimage/daily-builds/daily/arch-latest/i386/is...


The respective installation prompts for distribution mirror. To
include Vyatta's Debian miror, add this to /etc/apt/sources.list,

deb http://packages.vyatta.com/debian/ lenny main
deb http://packages.vyatta.com/debian-security/ lenny/updates main


You also need to add the Vyatta buildtools repository to sources.list,

deb http://packages.vyatta.com/vyatta-dev/ buildtools main


To install the Vyatta repository GPG key,

$ wget -O vyatta-pubkey.gpg \
http://packages.vyatta.com/vyatta-dev/vyatta-pubkey.gpg
$ sudo apt-key add vyatta-pubkey.gpg


To build an ISO with all pre-built, binary packages, we'll need to install some tools on the build host. Before doing that, however, we'll have to tell apt-get to use older versions of some tools because the latest versions are incompatible with the current livecd build system. Add the following lines to the build host's /etc/apt/preferences file:

Package: fakechroot
Pin: version 2.5*
Pin-Priority: 1001


Package: live-helper
Pin: version 1.0~a37-2
Pin-Priority: 1001


Next, install these tools on the build host using apt-get:

automake autoconf bzip2 curl debhelper devscripts dpatch
fakeroot fakechroot genisoimage git-core sysv-rc-conf
live-helper lsb-release rsync sudo


To build submodules, each package should list all build
dependencies. However, to save some iteration, install these
packages using apt-get:

bison flex docbook-utils gcc g++ git-buildpackage groff gs
gs-gpl imagemagick libncurses5-dev libpam0g-dev
libpcap0.8-dev libreadline-dev libsablot0-dev libtool lintian
manpages-dev tetex-bin texi2html texinfo transfig xmlto
zlib1g-dev libatm1-dev libdb-dev linuxdoc-tools git2cl
kernel-package lynx libcap-dev


Getting Source

The Vyatta ISO builder consists of scripts and config files
maintained as a GIT super-module named, "build-iso" that
references several submodules within its "pkgs/" sub-directory. To
clone the super-module,

$ git-clone http://git.vyatta.com/build-iso.git


To create and checkout a working glendale branch,

$ cd build-iso
build-iso$ git branch --track glendale origin/glendale
build-iso$ git checkout glendale


If you don't want to build any submodules and just want to build an
ISO with all pre-built packages, you can skip the following submodule
instructions and go to the next section "Configuration".

To register the submodules in the cloned repository config,

build-iso$ git-submodule init


It's most efficient to selectively clone only the submodules
needing for review or modifcation. The ISO build downloads the
Vyatta pre-built, binary packages of any non-cloned sub-module. To
clone a specific sub-module,

build-iso$ git-submodule update pkgs/SUBMODULE


This command clones the SUBMODULE repository in the "pkgs/SUBMODULE"
directory, and you need to create and checkout a glendale tracking
branch,

build-iso$ cd pkgs/SUBMODULE
build-iso/pkgs/SUBMODULE$ git branch --track glendale origin/glendale
build-iso/pkgs/SUBMODULE$ git checkout glendale


To clone all sub-modules for full verification build,

build-iso$ git-submodule update


Remember to create and checkout a glendale tracking branch for each
updated submodule.

Configuration

The Vyatta ISO builder has GNU autotool configuration,

build-iso$ autoreconf -i
build-iso$ ./configure


To see all configure options,

build-iso$ ./configure --help


Build ISO

To build an ISO,

build-iso$ PATH=/sbin:/usr/sbin:$PATH
build-iso$ make


The end results is the following livecd,

livecd/binary.iso


Clean

The Vyatta ISO builder has these standard automake targets to
clean files generated:

mostlyclean during ISO build (excludes package built files)
clean during package builds along with ISO files
distclean by autoreconf and configure plus all of the above


For example, to clean the ISO build files,

build-iso$ make mostlyclean


Build submodules

When you do a "make", the build system will build the binary packages
for all cloned submodules and include them in the ISO. If you want to
work with specific submodules, you can use the commands listed below.

To build binary packages for cloned submodule(s),

build-iso$ tools/submod-mk { --all | SUBMODULE... }


To build binary and source packages for submodule(s),

build-iso$ tools/submod-mk --source { --all | SUBMODULE... }


To build signed binary and source packages for submodule(s),

build-iso$ tools/submod-mk --signed-source { --all | SUBMODULE... }


To clean files generated during submodule build,

build-iso$ tools/submod-clean SUBMODULE...


To clean files generated during all submodule builds,

build-iso# tools/submod-clean


To also clean the submodule build stage(s),

build-iso# tools/submod-clean -d [ SUBMODULE... ]


To clean the source tree of submodules to skip subsequent builds,

build-iso# tools/submod-clean -g [ SUBMODULE... ]


This retains the local bare git repository for quicker updates.

Changes

After making, testing, and commiting your changes to your local
repos, publish them to the shared repos with,

build-iso/pkgs/SUBMODULE$ git-push suva.vyatta.com:/git/SUBMODULE.git


Then update and publish the super-module index to include the
submodule(s) changes,

build-iso/pkgs/SUBMODULE$ cd ../..
build-iso$ git-update-index pkgs/SUBMODULE
build-iso$ git-commit -m 'update sub-module SUBMODULE'
build-iso$ git-push suva:/git/build-iso.git


Updates

Update the super-module with,

build-iso$ git-pull
or for the paranoid,
build-iso$ git-fetch origin
build-iso$ git-whatchanged HEAD..origin/glendale
build-iso$ git-merge origin/glendale


If new submodules were added, include these in the config,

build-iso$ git-submodule init


To see which checked-out submodules have upstream modifications,

build-iso$ git-status # search for changes in pkgs/


Get the "from" and "to" SHAs with,

build-iso$ git-diff pkgs/SUBMODULE


This will produce output something like,

diff --git a/pkgs/vyatta-cfg-quagga b/pkgs/vyatta-cfg-quagga
index 78124a9..fca1739 160000
--- a/pkgs/vyatta-cfg-quagga
+++ b/pkgs/vyatta-cfg-quagga
@@ -1 +1 @@
-Subproject commit 78124a9754efe0bda1d9c827c593c5e0635fec3c
+Subproject commit fca1739f1985c2ba8d6316b1882365f5e26245cd


To review what changed between these SHAs,

build-iso$ git --git-dir=pkgs/SUBMODULE/.git fetch
build-iso$ git --git-dir=pkgs/SUBMODULE/.git whatchanged FROM_SHA TO_SHA


To merge these submodule changes,

build-iso$ cd pkgs/SUBMODULE
build-iso/pkgs/SUBMODULE$ git checkout glendale
build-iso/pkgs/SUBMODULE$ git merge origin/glendale
build-iso/pkgs/SUBMODULE$ debuild -i -b -us -uc
build-iso/pkgs/SUBMODULE$ cd ../..


The "git-status" for pkgs/SUBMODULE should now be clean. Iterate
through the other updated submodules, then rebuild the iso.