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 [options="header",frame="topbot",grid="none"]
 140 |=======================================================================================
 141 | Source         | Action                                                       | Result
 142 | seed stage3    | Build packages listed in your profile's `packages.build`     | stage1
 143 | stage1         | Rebuild the toolchain with the package tree's `bootstrap.sh` | stage2
 144 | stage2         | Compile the base `@system` packages                          | stage3
 145 | stage3         | Compile additional `@world` packages                         | stage4
 146 |=======================================================================================
 147
 148 For stage1, Catalyst builds the stuff your profile says you need to
 149 get started, using the tools in the seed stage3.  It uses Portage's
 150 ability to merge packages into an alternatively-rooted filesystem
 151 (`/tmp/stage1root`, using `ROOT` in `make.conf`).  This ensures that
 152 only freshly-built packages end up in stage1.
 153
 154 A fresh stage1 has newly-compiled versions of everything you need to
 155 build a full system, but all of the stage1 binaries were built with
 156 tools from the seed stage3.  For stage2, Catalyst rebuilds a number of
 157 critial packages (GCC, glibc, binutils, ...) using the `bootstrap.sh`
 158 script distributed with the package tree.  Rebuilding the packages
 159 using the packages themselves (instead of the seed stage3 tools) gives
 160 an extra layer of separation from any crazy output that the seed
 161 tooling may have generated.
 162
 163 Once we have a stage2, Catalyst builds all of the base system packages
 164 for stage3, rebuilding any that were already built in stage2 (`emerge
 165 -e @system`).  The `@system` set of packages is defined by `packages`
 166 files in your cascading profile.  See
 167 http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-520005.2.6[the Package
 168 Manager Specification] for details.
 169
 170 For more details on the differences between the stages, look at the
 171 target helper scripts (e.g. `targets/stage1/*.sh`).
 172
 173 Building with a kernel
 174 ----------------------
 175
 176 If you're shooting for a live CD or bootable USB stick, you'll need to
 177 compile your own kernel.  Here's how that works.
 178
 179 Genkernel
 180 ~~~~~~~~~
 181
 182 When you don't know exactly which kernel options you need, add
 183 something like the following to your `*.spec`:
 184
 185     boot/kernel: gentoo
 186     boot/kernel/gentoo/sources: gentoo-sources
 187
 188 You can still set `boot/kernel/<label>/config` when you're using
 189 genkernel if you want to give genkernel some hints.
 190
 191 Genkernel alternatives
 192 ~~~~~~~~~~~~~~~~~~~~~~
 193
 194 If you don't want to use a genkernel, your options are fairly limited.
 195 The currently suggested route is to create your own binary kernel
 196 package.
 197
 198 Stage4
 199 ------
 200
 201 `examples/stage4_template.spec` is a good template for building a
 202 stage4 tarball.  Besides setting `target: stage4` and adjusting
 203 `source_subpath`, I usually use `stage4/packages`, `stage4/rcadd`, and
 204 the `boot/kernel` stuff described above.  This gives an almost
 205 bootable stage that you can dump on a USB flash drive.
 206
 207 Live CDs
 208 --------
 209
 210 Live CDs should be built in two stages: `livecd-stage1` (based on a
 211 stage3 source) for building extra packages (along the same lines as a
 212 stage4) and `livecd-stage2` (based on `livecd-stage1`) for setting up
 213 the kernel, bootloader, filesystem, and other details.  See
 214 `examples/livecd-stage*_template.spec` for some ideas.
 215
 216 Live USBs
 217 ---------
 218
 219 The easiest way to create a live USB is currently to install a live CD
 220 ISO using
 221 http://www.syslinux.org/wiki/index.php/Doc/isolinux#HYBRID_CD-ROM.2FHARD_DISK_MODE[isohybrid]
 222 and `dd`:
 223
 224     # isohybrid filename.iso
 225     # dd if=filename.iso of=/dev/sdX
 226
 227 replacing `X` with the appropriate drive letter for your USB disk.
 228 See https://bugs.gentoo.org/show_bug.cgi?id=251719[bug 251719] for
 229 details.
 230
 231 Running catalyst from a Git checkout
 232 ------------------------------------
 233
 234 If you're developing catalyst, you'll want to test your altered
 235 version.  An easy way to run it without reinstalling is to setup a
 236 local configuration file.  The checkout also includes a testpath file
 237 which when sourced adds it's bin/ to PATH and it's checkout dir to
 238 PYTHONPATH.  That terminal will then use the checkout bin/catalyst and
 239 the checkout's python modules.
 240
 241 cd into the checkout directory and run:
 242
 243     # source ./testpath
 244     # catalyst -c catalyst.conf -f path/to/your.spec
 245
 246 The local configuration file can use all the defaults except for
 247 `sharedir`, which you should change to point to your development
 248 directory:
 249
 250     sharedir="/home/wking/src/catalyst"