README

Vyatta VC4 ISO Build Procedures

    This document describes how to build a Vyatta VC4 ISO image.
    The most recent version of this document is the top-level README file of
    the "islavista" 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 that 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.

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.
    Note that the super-module and submodules each have multiple
    branches available.  To build successfully, all modules must
    have the same branch checked out.
    To clone the super-module, if you haven't do so, install git:

	apt-get install git-core

    Then:

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

    This will create a tree in the directory ./build-iso .
    (At this point, you might want to switch to reading
    ./build-iso/README, which is the most recent version
    of the file which you are reading now:-)

    Our git repositories have branches, the most stable of which
    is the default git branch ("master"). If you are
    interested in another branch (let's call it BRANCH), then:

	cd build-iso
	git checkout --track -b BRANCH origin/BRANCH

    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,

	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,

	git submodule update pkgs/SUBMODULE

    This command clones the SUBMODULE repository in the "pkgs/SUBMODULE"
    directory and checks out the master branch.  If you wish to checkout a
    different branch, use:

	cd pkgs/SUBMODULE
	git checkout --track -b BRANCHNAME origin/BRANCHNAME

    To clone all sub-modules for full verification build,

	git submodule update

    Remember to create and checkout the same working branch for all
    submodules.

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.  You can also use the Vyatta livecd ISO for a
    build host. (If you do want to start from the Vyatta system, you will
    have to unistall libsnmp15--which will uninstall most of the Vyatta
    specific features.)

	http://cdimage.debian.org/cdimage/daily-builds/daily/arch-latest/i386/iso-cd/debian-testing-i386-businesscard.iso
	http://cdimage.debian.org/cdimage/daily-builds/daily/arch-latest/i386/iso-cd/debian-testing-i386-netinst.iso
	http://packages.vyatta.com/iso/testing/*.iso

    The respective installation prompts for distribution mirror. Any debian "lenny"
    mirror will do.  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, you need to install
    certain tools on the build host.

    This script will setup the build environment for an ISO build:

	setup-build-env

    In order to build the individual vyatta packages, you need to install additional
    debian packages.  Note that each vyatta package build will check if the required
    debian packages are installed.  It will "complain" if they are not.  In order to
    save some iteration, run this script to download and install these packages:

	setup-pkg-env

Configuration

    The Vyatta ISO builder has GNU autotool configuration,

	autoreconf -i
	./configure --with-target-dist=lenny

    To see all configure options,

	./configure --help

Build ISO

    To build an ISO:

	PATH=/sbin:/usr/sbin:$PATH
	sudo 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:

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

    For example, to clean the ISO build files,

	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),

	tools/submod-mk { --all | SUBMODULE... }

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

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

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

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

    To clean files generated during submodule build,

	tools/submod-clean SUBMODULE...

    To clean files generated during all submodule builds,

	tools/submod-clean

    To also clean the submodule build stage(s),

	tools/submod-clean -d [ SUBMODULE... ]

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

	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,

	git push suva.vyatta.com:/git/SUBMODULE.git

    This will, of course, require an account on suva.vyatta.com, which
    is only available to authorized vyatta developers.
    Then update and publish the super-module index to include the
    submodule changes,

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

Updates using git

    Update the super-module.

	git pull
	git submodule init

    To update all modules, you can use:

	tools/submod-git pull

    Or for the paranoid

	tools/submod-git fetch
	git whatchanged HEAD..origin/master
	git merge

    To see which checked-out submodules have upstream modifications,

	git status		# search for changes in pkgs/

    Get the "from" and "to" commit ids (SHAs) with,

	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,

	cd pkgs/SUBMODULE
	git whatchanged FROM_SHA TO_SHA

    To merge these submodule changes,

	git merge
	cd ../..
	git submodule update

    The "git status" for this submodule should now be clean. Iterate
    through the other updated submodules, then rebuild the ISO.