[gentoo-releng] catalyst livecd instructions

[Daniel Robbins]

Hi guys,

Here are some beta catalyst livecd instructions, so that you can start
playing with catalyst livecd support. The livecd-stage1 and
livecd-stage2 steps are already documented in the catalyst docs online
(http://www.gentoo.org/proj/en/releng/catalyst/) and the remaining steps
will be documented soon. Until then, this doc should
get you by.

Livecd building starts from a stage3, then goes to livecd-stage1,
livecd-stage2, livecd-stage3, and livecd-final. All these steps are
supported in catalyst except livecd-final, which isn't a big deal
because livecd-final is pretty trivial and can be done by hand.

livecd-stage1

Example: examples/livecd/x86/x86-livecd-stage1-20040110.spec
Livecd-stage1 starts from a stage3 and builds new packages, specified
using the "livecd-stage1/packages" variable in the spec file.
/etc/make.conf is set to contain the USE variables specified in the
"livecd-stage1/use" variable.

livecd-stage2

Example: examples/livecd/x86/x86-livecd-stage2-20040110.spec
Livecd-stage2 starts from livecd-stage1 and builds
kernel(s) and initrd(s) using genkernel, which get stored in tarballs
that are placed in
/var/tmp/catalyst/builds/<profile>/<target-subpath>/binaries/ inside
tarballs. Names for each kernel (such as "gentoo") are specified
in the "boot/kernel" variable in the spec file. For each entry in
"boot/kernel", you need a "boot/kernel/foo/sources" and
"boot/kernel/foo/config" option. Should be fairly self-explanatory.
Right now, genkernel gets the --no-bootsplash option and we don't
support passing any options to genkernel itself. This will be added when
we need it (soon.)

livecd-stage3

Example: examples/livecd/x86/x86-livecd-stage3-20040110.spec
Runscript: examples/livecd/runscript/x86-isolinux-loop-example.sh
cdtar: examples/livecd/cdtar/isolinux-2.08-cdtar.tar.bz2

livecd-stage3 is where the "guts" of livecd creation reside. There are
three parts to a livecd-stage3 -- the spec file, the runscript and the
cdtar. The spec file points to the runscript and cdtar by using the
"livecd-stage3/runscript" and "livecd-stage3/cdtar" variables
respectively. The cdtar for isolinux/x86 contains the following:

root@music cdtar # tar tjvf isolinux-2.08-cdtar.tar.bz2 
drwxr-xr-x root/root         0 2004-01-08 18:20:41 ./
drwxr-xr-x root/root         0 2004-01-08 18:21:55 ./isolinux/
-rw-r--r-- root/root      9652 2004-01-08 18:21:55 ./isolinux/isolinux.bin

The purpose of the cdtar is to contain any pre-built binary things like
binary bootloaders. It will be extracted to the ISO tree root, so you
can also use it to create a skeleton directory tree if you want, or
include any pre-built files. However, it's not really designed to put
any "payload" such as stages or packages on the livecd -- this will be
handled by the livecd-final target when it's
complete.

Now take a look at the example livecd-stage3 spec file. You'll notice
several "trimming-down"-related variables that are used to trim down the
runtime image: 

"livecd-stage3/unmerge" -- What packages to unmerge from the
livecd-stage2 to get it "prepped" for being on the livecd. 

"livecd-stage3/empty" -- What directories should be wiped of any
contents. The directory itself will be kept, but its contents will be
totally wiped.

"livecd-stage3/rm" -- Files to remove from the runtime image. Globs are
supported, and what you specify will be passed to "rm -rf"

"livecd-stage3/prune" -- This is not supported yet (will be soon,) but
will allow directory trees to be emptied of everything *except* for
filesystem objects you specify.

Now take a look at the example runscript. You'll see that it is a
standard bash script that contains a large case statement. The purpose
of the runscript is to hold any steps related to "prepping" the runtime
image that cannot be performed in the spec file, and also handling
creation of a loopback filesystem, getting the kernels to the right
place on the iso root, creating any necessary bootloader config files
and also calling mkisofs for creating the ISO itself (this step will be
performed by the "livecd-final" target.)

So, the purpose of the runscript is to get all those "tweaks" needed to
create a livecd in one file.

Here is the order of steps performed in livecd-stage3 creation:

1. bind mounts are mounted inside the runtime chroot

2. The "run" target of the runscript executes

3. The "preclean" target of the runscript executes

4. The "livecd-stage3/unmerge" step is executed; packages are unmerged.

5. Bind mounts inside the runtime chroot are unmounted for safety
reasons

6. The "livecd-stage3/empty" step is executed; directory trees are
emptied.

7. The "livecd-stage3/delete" step is executed; files are deleted.

(livecd-stage3/prune will execute here once implemented)

8. The "clean" step of the runscript executes

9. The "cdroot_setup" step of the runscript executes, which creates (if
needed) a loopback filesystem, gets genkernel-created kernels in place,
etc.

Take a look at the example files, and I think you'll find that things
aren't too confusing.

Note: don't expect the examples to actually boot yet. I haven't tested
the isolinux.cfg nor the bootable runtime that currently gets created.
But we should be able to get it booting in a few days, and from this
point forward should have maintainable and easy-to-build livecds :)

Best Regards,

Daniel


--
gentoo-releng@g.o mailing list