Writable overlays (union mount) development README
==================================================

General HOWTO page, including info on git repos:

http://valerieaurora.org/union/

Cheatsheet
==========

This is the quick 'n' easy way to get writable overlays up and running
the automated test suite.

Presuming you have put this dev kit in ~/union_mount and your
kernel source in ~/src/linux-2.6:

Compile:

cp <version>-config_x86_64 ~/src/linux-2.6/.config
make ARCH=um -j2 -C ~/src/linux-2.6

Run UML under gdb:

cd ~/union_mount/
gdb ~/src/linux-2.6/linux
set args ubd0=./uml_root_img ubd1=./uml_iso_img init=/root/union_mount/union_tests.sh rw
run

And you should get a lot of test output scrolling up your screen,
followed by a bash prompt.

Drop into gdb from a running UML, presuming no other processes with
the string "linux" in the command name are running:

pkill -SIGUSR1 -o linux

Now you can set break points, etc.  To continue from gdb without
barfing:

signal 0

Union mount your root file system by copying the file "pivot.sh" to /
and booting with additional kernel command line args of:

init=/pivot.sh ro

Files in the union mount tarball
================================

File system images for UML block devices:

uml_root_img is the root file system image, compiled for x86_64.  All the
union mount testing infrastructure is kept in /root/union_mount in
this image.  It becomes /dev/udba when UML boots with the above
command line.

uml_iso_img is an iso9660 format test file system image for the
read-only layer of a union mount.  It becomed /dev/ubdb when booted
with the above command line.

ro_img_src/ is a directory containing the files that have to be in the
read-only image in order for the automatic regression tests to
complete.  This is the source for genisoimage to make uml_iso_img.

Makefile

Run make, and it will make the above two disk images automatically.
NOTE: You must have the whiteout-enabled e2fsprogs installed on your
compilation machine to rebuild the disk images.  It will compile
everything in src/, mount the root UML fs, and copy the binaries from
src/ and the scripts from scripts/ into the the root image.  It will
create the read-only test images from ro_img_src/, too.

Files in the UML disk images
========================

General theory:

Set the init program (via kernel command line) to
/root/union_mount/union_tests.sh.  This script automatically runs all the
current regression tests and then dumps you into a shell.

Script organization:

union_tests.sh: The starter script, does any generic setup needed.
Calls run_tests.sh, then starts a shell.

run_tests.sh: Runs generic tests and then the fs-dependent tests, once
for each interesting combination of file system.  Current this is
iso9660/ext2 for the read-only layer and ext2/tmpfs for the read-write.

one_shot_tests.sh: Tests that only need to be run once.

per_fs_tests.sh: Tests that need to be run once per fs combo.

Union mount test files:

All under /root/union_mount/.

union_tests.sh - master init/test script, does setup
run_tests.sh - runs one-time and per-fs tests
one_shot_tests.sh - tests that only need to run run once
per_fs_tests.sh - tests to run on all potential fs combos
edit.sh - fsck and mount ext2 images so you can edit them
mnt/union - mountpoint for unioned file system
mnt/ro - mountpoint for read-only file systems
mnt/rw - mountpoint for read-write file systems
mnt/tmp - scratch mountpoint
img/ro - read-only ext2 file system for bottom layer, loopback mounted
img/rw_src - read-write ext2 file system for top layer, loopback mounted
bin/ - test binaries

Adding a test
=============

The short version is: open up one_shot_tests.sh and add the test
before the final umounts at the end.  Type "make" and start your UML
session with the freshly updates UML root image.

Long version: Creating a test usually includes the following steps:
Creating a C test case, adding any needed test files to the read-only
test file system image, editing one of the test scripts to run your
test, and rebuilding the UML disk images via make.

Creating a C test case: Add your .c file to the src/ directory.  make
will automatically build it and copy it to /root/union_mount/bin/ on
the UML root file system image.  E.g., create "test/rename.c" and
after the next make, it will show up as "/root/union_mount/bin/rename".

Adding test files to the test UML ro file system image: Add the
appropriate files in ro_img_src/.  E.g., "touch
ro_img_src/rename_src", and edit one_shot_tests.sh to add:

ln ./mnt/union/link_src ./mnt/union/link_target
if [ "$?" != "0" ]; then
    echo "link() returned an error"
    exit 1
fi

If it's not there when you try to run it, you probably forgot to run
make.