[[!template id=gitrepo repo=catalyst-swc]]

[Catalyst][] is a release-building tool for Gentoo.  If you use Gentoo
and want to roll your own live CD or bootable USB drive, this is the
way to go.  As I've been wrapping my head around catalyst, I've been
[pushing][catalyst-spec-mail] [my][catalyst-spec] [notes][howto-mail]
[upstream][howto].  This post builds on those notes to discuss the
construction of [a bootable ISO][iso] for [Software Carpentry][swc]
boot camps.

Getting a patched up catalyst
=============================

Catalyst has been around for a while, but the user base has been
fairly small.  If you try to do something that [Gentoo's Release
Engineering team][releng] doesn't do on a regular basis, built in
catalyst support can be spotty.  There's been a fair amount of patch
submissions an [gentoo-catalyst@][] recently, but patch acceptance can
be slow.  For the SWC ISO, I applied versions of the following patches
(or patch series) to [37540ff][]:

* [chmod +x all sh scripts so they can run from the git checkout][chmod]
* [livecdfs-update.sh: Set XSESSION in /etc/env.d/90xsession][90xsession]
* [Fix livecdfs-update.sh startx handling][startx]

Configuring catalyst
====================

The easiest way to run catalyst from a Git checkout is to setup a
[local config file][config].  I didn't have enough hard drive space on
my local system (~16 GB) for this build, so I set things up in a
temporary directory on an external hard drive:

    $ cat catalyst.conf | grep -v '^#\|^$'
    digests="md5 sha1 sha512 whirlpool"
    contents="auto"
    distdir="/usr/portage/distfiles"
    envscript="/etc/catalyst/catalystrc"
    hash_function="crc32"
    options="autoresume kerncache pkgcache seedcache snapcache"
    portdir="/usr/portage"
    sharedir="/home/wking/src/catalyst"
    snapshot_cache="/mnt/d/tmp/catalyst/snapshot_cache"
    storedir="/mnt/d/tmp/catalyst"

I used the default values for everything except `sharedir`,
`snapshot_cache`, and `storedir`.  Then I cloned the `catalyst-swc`
repository into `/mnt/d/tmp/catalyst`.

Portage snapshot and a seed stage
=================================

Take a snapshot of the current Portage tree:

    # catalyst -c catalyst.conf --snapshot 20130208

Download a seed stage3 from a [Gentoo mirror][mirror]:

    # wget -O /mnt/d/tmp/catalyst/builds/default/stage3-i686-20121213.tar.bz2 \
    >   http://distfiles.gentoo.org/releases/x86/current-stage3/stage3-i686-20121213.tar.bz2

Building the live CD
====================

    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-stage1-i686-2013.1.spec
    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-stage2-i686-2013.1.spec
    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-stage3-i686-2013.1.spec
    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-livecd-stage1-i686-2013.1.spec
    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-livecd-stage2-i686-2013.1.spec

isohybrid
=========

To make the ISO bootable from a USB drive, I used [isohybrid][]:

    # cp swc-x86.iso swc-x86-isohybrid.iso
    # isohybrid iso-x86-isohybrid.iso

You can install the resulting ISO on a USB drive with:

    # dd if=iso-x86-isohybrid.iso of=/dev/sdX

replacing replacing `X` with the appropriate drive letter for your USB
drive.

With versions of catalyst after [d1c2ba9][], the `isohybrid` call is
built into catalysts ISO construction.

[Catalyst]: http://www.gentoo.org/proj/en/releng/catalyst/
[catalyst-spec-mail]:http://thread.gmane.org/gmane.linux.gentoo.catalyst/2006
[catalyst-spec]: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=0a99c494d4602ebb92f6d352f86ec519903fdc88
[howto-mail]: http://thread.gmane.org/gmane.linux.gentoo.catalyst/2107
[howto]: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=b7f2cf0f4c34af8d2dd9dcfa186930c17323e298
[iso]: http://lists.software-carpentry.org/pipermail/discuss-software-carpentry.org/2013-March/000210.html
[swc]: http://software-carpentry.org/
[releng]: http://www.gentoo.org/proj/en/releng/
[gentoo-catalyst@]: http://www.gentoo.org/main/en/lists.xml#doc_chap1_sect2
[37540ff]: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=37540ff5e9db28e65a4f55b71c16cec1e7d294ec
[chmod]: http://thread.gmane.org/gmane.linux.gentoo.catalyst/2085/focus=2093
[90xsession]: http://thread.gmane.org/gmane.linux.gentoo.catalyst/2182
[startx]: http://thread.gmane.org/gmane.linux.gentoo.catalyst/2187/focus=2191
[config]: http://article.gmane.org/gmane.linux.gentoo.catalyst/2111
[mirror]: http://www.gentoo.org/main/en/mirrors.xml
[isohybrid]: http://www.syslinux.org/wiki/index.php/Doc/isolinux#HYBRID_CD-ROM.2FHARD_DISK_MODE
[d1c2ba9]: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=d1c2ba9bdaf1a69078fcbcd6ec4210e829f99f0a

[[!tag tags/tools]]
[[!tag tags/teaching]]