doc/HOWTO.txt

   1 Catalyst is a release-buildcing tool for Gentoo.  If you use Gentoo
   2 and want to roll your own live CD or bootable USB stick, this is the
   3 way to go.  First, get a Gentoo development box and install the
   4 necessary tools:
   5
   6     # emerge -av dev-util/catalyst
   7
   8 Configure catalyst by editing `/etc/catalyst/catalyst.conf`, which is
   9 well commented.  This sets up defaults such as hashing algorithms and
  10 storage directories.  The defaults will probably be fine unless disk
  11 space is an issue.
  12
  13 Assembling a starting point
  14 ---------------------------
  15
  16 Portage snapshot
  17 ~~~~~~~~~~~~~~~~
  18
  19 Create a snapshot of your current Portage tree (you may want to
  20 `emerge --sync` first):
  21
  22     # catalyst --snapshot 20130131
  23     # ls /var/tmp/catalyst/snapshots/
  24     portage-20130131.tar.bz2
  25     portage-20130131.tar.bz2.CONTENTS
  26     portage-20130131.tar.bz2.DIGESTS
  27
  28 where the storage location is relative to the default
  29 `$storedir=/var/tmp/catalyst`.
  30
  31 Stage3 tarball
  32 ~~~~~~~~~~~~~~
  33
  34 Get a stage3 tarball (containing the build tools you'll need to
  35 construct your stage1) from your local
  36 http://www.gentoo.org/main/en/mirrors.xml[Gentoo mirror].
  37
  38     $GENTOO_MIRROR/releases/$ARCH/current-stage3/
  39
  40 For example,
  41
  42     http://distfiles.gentoo.org/releases/amd64/current-stage3/stage3-amd64-20121213.tar.bz2
  43
  44 Grab the tarball and put it where catalyst will find it:
  45
  46     # wget http://…/stage3-amd64-20121213.tar.bz2
  47     # wget http://…/stage3-amd64-20121213.tar.bz2.CONTENTS
  48     # wget http://…/stage3-amd64-20121213.tar.bz2.DIGESTS.asc
  49     # sha512sum -c stage3-amd64-20121213.tar.bz2.DIGESTS.asc
  50     # gpg --verify stage3-amd64-20121213.tar.bz2.DIGESTS.asc
  51     # mv stage3-amd64-20121213.tar.bz2* /var/tmp/catalyst/builds/default/
  52
  53 where the storage dir is `$storedir/builds/$source_subpath`
  54 (`$storedir` from `catalyst.conf`, `$source_subpath` from your
  55 `*.spec` file).
  56
  57 `.*spec` files
  58 ~~~~~~~~~~~~~~
  59
  60 `.*spec` files tell catalyst about the system you're trying to build.
  61 There are a number of examples distributed with catalyst.  Look in
  62 `/usr/share/doc/catalyst-*/examples/`.  A minimal `*.spec` file for
  63 this example is:
  64
  65     # cat default-stage1-amd64-2013.1.spec
  66     subarch: amd64
  67     version_stamp: 2013.1
  68     target: stage1
  69     rel_type: default
  70     profile: default/linux/amd64/10.0/no-multilib
  71     snapshot: 20130131
  72     source_subpath: default/stage3-amd64-20121213
  73
  74 You may need to adjust the `subarch`, `snapshot`, and `source_subpath`
  75 fields of the `*.spec` to match your target host, Portage snapshot,
  76 and stage3 tarball name respectively.
  77
  78 For more details on what can go into a `*.spec` file, see
  79 `catalyst-spec(5)`.
  80
  81 Building stage1
  82 ---------------
  83
  84 Now that everything's setup, run catalyst:
  85
  86     # catalyst -f default-stage1-amd64-2013.1.spec
  87
  88 which will build the target and install something like:
  89
  90     # ls /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.*
  91     /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2
  92     /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.CONTENTS
  93     /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.DIGESTS
  94
  95 The name is an expansion of
  96 `$storedir/builds/$rel_type/$target-$subarch-$version_stamp…`.
  97
  98 Building stage2 and stage3
  99 --------------------------
 100
 101 Once you've built the stage1 from your seed stage3, you can use that
 102 stage1 to build a stage2 and stage3.  The `*.spec` files are similar:
 103
 104     $ diff -u default-stage{1,2}-amd64-2013.1.spec
 105     --- default-stage1-amd64-2013.1.spec
 106     +++ default-stage2-amd64-2013.1.spec
 107     @@ -1,7 +1,7 @@
 108      subarch: amd64
 109      version_stamp: 2013.1
 110     -target: stage1
 111     +target: stage2
 112      rel_type: default
 113      profile: default/linux/amd64/10.0/no-multilib
 114      snapshot: 20130131
 115     -source_subpath: default/stage3-amd64-20121213
 116     +source_subpath: default/stage1-amd64-2013.1
 117     $ diff default-stage{2,3}-amd64-2013.1.spec
 118     --- default-stage2-amd64-2013.1.spec
 119     +++ default-stage3-amd64-2013.1.spec
 120     @@ -1,7 +1,7 @@
 121      subarch: amd64
 122      version_stamp: 2013.1
 123     -target: stage2
 124     +target: stage3
 125      rel_type: default
 126      profile: default/linux/amd64/10.0/no-multilib
 127      snapshot: 20130131
 128     -source_subpath: default/stage1-amd64-2013.1
 129     +source_subpath: default/stage2-amd64-2013.1
 130
 131 Gentoo stages
 132 -------------
 133
 134 You can't compile a big pile of source code without an already
 135 compiled toolchain, which is where Gentoo's stages come in.  The “base
 136 system” contains the necessary build tools and supporting
 137 infrastructure to get things going.  The stages are:
 138
 139 1. System must be bootstrapped and the base system must be compiled
 140    (a new toolchain built with external seed tools).
 141 2. Stage1 + bootstrapped (a new toolchain build with stage1 tools).
 142 3. Stage2 + base system compiled (the base system built with stage2 tools).
 143 4. Stage3 + non-base packages.
 144
 145 For more details on the differences between the stages, look at the
 146 target helper scripts (e.g. `targets/stage1/*.sh`).
 147
 148 Building with a kernel
 149 ----------------------
 150
 151 If you're shooting for a live CD or bootable USB stick, you'll need to
 152 compile your own kernel.  Here's how that works.
 153
 154 Genkernel
 155 ~~~~~~~~~
 156
 157 When you don't know exactly which kernel options you need, add
 158 something like the following to your `*.spec`:
 159
 160     boot/kernel: gentoo
 161     boot/kernel/gentoo/sources: gentoo-sources
 162
 163 You can still set `boot/kernel/<label>/config` when you're using
 164 genkernel if you want to give genkernel some hints.
 165
 166 Genkernel alternatives
 167 ~~~~~~~~~~~~~~~~~~~~~~
 168
 169 If you don't want to use a genkernel, your options are fairly limited.
 170 The currently suggested route is to create your own binary kernel
 171 package.
 172
 173 Stage4
 174 ------
 175
 176 `examples/stage4_template.spec` is a good template for building a
 177 stage4 tarball.  Besides setting `target: stage4` and adjusting
 178 `source_subpath`, I usually use `stage4/packages`, `stage4/rcadd`, and
 179 the `boot/kernel` stuff described above.  This gives an almost
 180 bootable stage that you can dump on a USB flash drive.
 181
 182 Live CDs
 183 --------
 184
 185 Live CDs should be built in two stages: `livecd-stage1` (based on a
 186 stage3 source) for building extra packages (along the same lines as a
 187 stage4) and `livecd-stage2` (based on `livecd-stage1`) for setting up
 188 the kernel, bootloader, filesystem, and other details.  See
 189 `examples/livecd-stage*_template.spec` for some ideas.
 190
 191 Live USBs
 192 ---------
 193
 194 The easiest way to create a live USB is currently to install a live CD
 195 ISO using
 196 http://www.syslinux.org/wiki/index.php/Doc/isolinux#HYBRID_CD-ROM.2FHARD_DISK_MODE[isohybrid]
 197 and `dd`:
 198
 199     # isohybrid filename.iso
 200     # dd if=filename.iso of=/dev/sdX
 201
 202 replacing `X` with the appropriate drive letter for your USB disk.
 203 See https://bugs.gentoo.org/show_bug.cgi?id=251719[bug 251719] for
 204 details.
 205
 206 Running catalyst from a Git checkout
 207 ------------------------------------
 208
 209 If you're developing catalyst, you'll want to test your altered
 210 version.  An easy way to run it without reinstalling is to setup a
 211 local configuration file and run:
 212
 213     # ./catalyst -c catalyst.conf -f path/to/your.spec
 214
 215 The local configuration file can use all the defaults except for
 216 `sharedir`, which you should change to point to your development
 217 directory:
 218
 219     sharedir="/home/wking/src/catalyst"