From b7f2cf0f4c34af8d2dd9dcfa186930c17323e298 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 9 Feb 2013 15:40:30 -0500 Subject: [PATCH] doc/HOWTO: First pass at a gentle Catalyst introduction Reviewed-by: Matt Turner --- doc/HOWTO.txt | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 doc/HOWTO.txt diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt new file mode 100644 index 00000000..ea9c8f42 --- /dev/null +++ b/doc/HOWTO.txt @@ -0,0 +1,204 @@ +Catalyst is a release-buildcing tool for Gentoo. If you use Gentoo +and want to roll your own live CD or bootable USB stick, this is the +way to go. First, get a Gentoo development box and install the +necessary tools: + + # emerge -av dev-util/catalyst + +Configure catalyst by editing `/etc/catalyst/catalyst.conf`, which is +well commented. This sets up defaults such as hashing algorithms and +storage directories. The defaults will probably be fine unless disk +space is an issue. + +Assembling a starting point +--------------------------- + +Portage snapshot +~~~~~~~~~~~~~~~~ + +Create a snapshot of your current Portage tree (you may want to +`emerge --sync` first): + + # catalyst --snapshot 20130131 + # ls /var/tmp/catalyst/snapshots/ + portage-20130131.tar.bz2 + portage-20130131.tar.bz2.CONTENTS + portage-20130131.tar.bz2.DIGESTS + +where the storage location is relative to the default +`$storedir=/var/tmp/catalyst`. + +Stage3 tarball +~~~~~~~~~~~~~~ + +Get a stage3 tarball (containing the build tools you'll need to +construct your stage1) from your local +http://www.gentoo.org/main/en/mirrors.xml[Gentoo mirror]. + + $GENTOO_MIRROR/releases/$ARCH/current-stage3/ + +For example, + + http://distfiles.gentoo.org/releases/amd64/current-stage3/stage3-amd64-20121213.tar.bz2 + +Grab the tarball and put it where catalyst will find it: + + # wget http://…/stage3-amd64-20121213.tar.bz2 + # wget http://…/stage3-amd64-20121213.tar.bz2.CONTENTS + # wget http://…/stage3-amd64-20121213.tar.bz2.DIGESTS.asc + # sha512sum -c stage3-amd64-20121213.tar.bz2.DIGESTS.asc + # gpg --verify stage3-amd64-20121213.tar.bz2.DIGESTS.asc + # mv stage3-amd64-20121213.tar.bz2* /var/tmp/catalyst/builds/default/ + +where the storage dir is `$storedir/builds/$source_subpath` +(`$storedir` from `catalyst.conf`, `$source_subpath` from your +`*.spec` file). + +`.*spec` files +~~~~~~~~~~~~~~ + +`.*spec` files tell catalyst about the system you're trying to build. +There are a number of examples distributed with catalyst. Look in +`/usr/share/doc/catalyst-*/examples/`. A minimal `*.spec` file for +this example is: + + # cat default-stage1-amd64-2013.1.spec + subarch: amd64 + version_stamp: 2013.1 + target: stage1 + rel_type: default + profile: default/linux/amd64/10.0/no-multilib + snapshot: 20130131 + source_subpath: default/stage3-amd64-20121213 + +You may need to adjust the `subarch`, `snapshot`, and `source_subpath` +fields of the `*.spec` to match your target host, Portage snapshot, +and stage3 tarball name respectively. + +For more details on what can go into a `*.spec` file, see +`catalyst-spec(5)`. + +Building stage1 +--------------- + +Now that everything's setup, run catalyst: + + # catalyst -f default-stage1-amd64-2013.1.spec + +which will build the target and install something like: + + # ls /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.* + /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2 + /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.CONTENTS + /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.DIGESTS + +The name is an expansion of +`$storedir/builds/$rel_type/$target-$subarch-$version_stamp…`. + +Building stage2 and stage3 +-------------------------- + +Once you've built the stage1 from your seed stage3, you can use that +stage1 to build a stage2 and stage3. The `*.spec` files are similar: + + $ diff -u default-stage{1,2}-amd64-2013.1.spec + --- default-stage1-amd64-2013.1.spec + +++ default-stage2-amd64-2013.1.spec + @@ -1,7 +1,7 @@ + subarch: amd64 + version_stamp: 2013.1 + -target: stage1 + +target: stage2 + rel_type: default + profile: default/linux/amd64/10.0/no-multilib + snapshot: 20130131 + -source_subpath: default/stage3-amd64-20121213 + +source_subpath: default/stage1-amd64-2013.1 + $ diff default-stage{2,3}-amd64-2013.1.spec + --- default-stage2-amd64-2013.1.spec + +++ default-stage3-amd64-2013.1.spec + @@ -1,7 +1,7 @@ + subarch: amd64 + version_stamp: 2013.1 + -target: stage2 + +target: stage3 + rel_type: default + profile: default/linux/amd64/10.0/no-multilib + snapshot: 20130131 + -source_subpath: default/stage1-amd64-2013.1 + +source_subpath: default/stage2-amd64-2013.1 + +Gentoo stages +------------- + +You can't compile a big pile of source code without an already +compiled toolchain, which is where Gentoo's stages come in. The “base +system” contains the necessary build tools and supporting +infrastructure to get things going. The stages are: + +1. System must be bootstrapped and the base system must be compiled + (a new toolchain built with external seed tools). +2. Stage1 + bootstrapped (a new toolchain build with stage1 tools). +3. Stage2 + base system compiled (the base system built with stage2 tools). +4. Stage3 + non-base packages. + +For more details on the differences between the stages, look at the +target helper scripts (e.g. `targets/stage1/*.sh`). + +Building with a kernel +---------------------- + +If you're shooting for a live CD or bootable USB stick, you'll need to +compile your own kernel. Here's how that works. + +Genkernel +~~~~~~~~~ + +When you don't know exactly which kernel options you need, add +something like the following to your `*.spec`: + + boot/kernel: gentoo + boot/kernel/gentoo/sources: gentoo-sources + +You can still set `boot/kernel/