posts:catalyst: Add post about building the SWC bootable ISO

diff --git a/posts/catalyst.mdwn b/posts/catalyst.mdwn
new file mode 100644 (file)
index 0000000..f0e5173
--- /dev/null
+++ b/posts/catalyst.mdwn
@@ -0,0 +1,107 @@
+[[!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 [notes][catalyst-spec]
+[upstream][howto-mail].  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-amd64-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-amd64-2013.1.spec
+    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-stage2-amd64-2013.1.spec
+    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-stage3-amd64-2013.1.spec
+    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-livecd-stage1-amd64-2013.1.spec
+    # catalyst -c catalyst.conf -f /mnt/d/tmp/catalyst/spec/default-livecd-stage2-amd64-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
+[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]]