-*- emacs-wiki -*-

a typical umlsetup.sh might look like this.

*  POOLSPACE=/mara6/sandboxes/keys/UMLPOOL

this decides where all the UML roots and UML kernel sources will go.

*  BUILDTOP=/mara6/sandboxes/keys export BUILDTOP

This is just a convenience variable.

*  REGRESSRESULTS=${POOLSPACE}/results

Set this to where you want the results of the tests to go. If not set,
they go nowhere. There will be a file testresults.html that shows the
results. It will be set to the META refresh stuff while tests are running so
that your browser will stay up to date.

*  OPENSWANDIR=$BUILDTOP

Probably not necessary anymore.

*  BASICROOT=/mara6/uml/root

This is an extract root image. It will be hard linked to build the UML
root images. It is therefore to your advantage to have it on the same
partition as your $POOLSPACE.  MCR even extracts it multiple times 
when he needs to work on multiple partitions. 

*  SHAREDIR=${BASICROOT}/usr/share

This will be mounted read-only. It isn't copied. You can probably even use
your real /usr/share.

*  REGULARHOSTS='sunrise sunset nic carrot beet sec pole'
*  OPENSWANHOSTS='east west japan road north'

The list of hosts that will be built. Perhaps this list should go into
the testing system itself, since the tests assume that certain hosts exist,
but for now they are listed here, since you might want to create new hosts.
This has been a source of problems.

*   NONINTPATCH=none

There is a patch in testing/kernelconfigs/linux-2.4.0-nonintconfig.patch that
permits "make oldconfig" to just fail rather than interface. If you want it 
(and you do for nightly regression work if you change kernels, etc.) then
point this variable to it. It may not work on 2.6. kernels.

The following variables are grouped into 2.6 and 2.4 uses.

* 2.6 kernel definitions

** KERNPOOL=/distros/kernel/linux-2.6.13

Where to find an extracted (but not built) kernel. A future version may make
use of O= instead.

** KERNVER=26

Indicate that this is a 2.6 kernel.

** NATTPATCH=true

Whether to patch the kernel with the NAT-Traversal patch. This is done
for both plain and swan kernels.

** UMLPATCH=/dev/null

If any User-Mode-Linux patch is needed. Post 2.6.9, none is needed.

* 2.4 kernel definitions

(Pick only one or the other.)

** KERNPOOL=/distros/kernel/linux-2.4.20

Where to find an extracted (but not built!. Must be "make mrproper") kernel. 

** KERNVER=

To indicate a 2.4 kernel, set KERNVER to an empty string.

** NATTPATCH=true

Whether to patch the kernel with the NAT-Traversal patch. This is done
for both plain and swan kernels.

** UMLPATCH=/distros/user-mode-linux/uml-patch-2.4.20

An appropriate User-Mode-Linux patch. For 2.4 kernels, this is required.

* Specializing for a particular host.

Sometimes one wants to do general testing, but replace the kernel on one host
with a particular kernel that has been built elsewhere. This can now
(2005-11-20) be done with:

** UML_host_KERNEL=/path/name

Where host is, for instance "east" or "west". 
        UML_east_KERNEL=/mara1/git/klips/O/um-01/linux

The kernel must be a User-Mode-Linux kernel.

* Avoiding kernel builds all-together

Often if you have multiple development trees, you may want to avoid
the kernel builds entirely. This is useful if you are primarily debugging
user-space things.  You can effectively set all of the kernels with:

        UML_plain26_KERNEL=/mara6/sandboxes/openswan.git/UMLPOOL/plain26/linux

and 

        UML_swan26_KERNEL=/mara1/git/klips/O/um-01/linux

(for 2.4 kernels, it should be just "plain" and "swan").

If you specify UML_foo_KERNEL= for all hosts, such that no kernel is needed,
then none will be built. Also, no modules will be built if there are no plain
kernels built.

* Including additional software: UML_extra_DIRS

You can include new things into a UML root file system by listing directories
in:
        UML_extra_DIRS="/mara2/sandboxes/l2tpd /my/favorite/editor"

The build process will cd into that directory and invoke:

        make DESTDIR=UMLROOTDIR install

with many build processes, this will cause the install to go to UMLROOTDIR
instead of /. 

* BUILD_MODULES=[true,false]

If set to false, then modules will not be built. This is useful if you
have changed the kernel code, are compiling it a seperate directory
(using UML_xxx_KERNEL), and don't want to build kernels against the plain26
kernel. (Likely because it won't work)