From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id BB1F413894A for ; Sat, 9 Feb 2013 20:41:07 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 3253721C00D; Sat, 9 Feb 2013 20:41:07 +0000 (UTC) Received: from vms173001pub.verizon.net (vms173001pub.verizon.net [206.46.173.1]) by pigeon.gentoo.org (Postfix) with ESMTP id 8B40121C001 for ; Sat, 9 Feb 2013 20:41:06 +0000 (UTC) Received: from odin.tremily.us ([unknown] [72.68.84.219]) by vms173001.mailsrvcs.net (Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16 2009)) with ESMTPA id <0MHZ00HEU049J290@vms173001.mailsrvcs.net> for gentoo-catalyst@lists.gentoo.org; Sat, 09 Feb 2013 14:40:58 -0600 (CST) Received: by odin.tremily.us (Postfix, from userid 1000) id 37641878C35; Sat, 09 Feb 2013 15:40:57 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; t=1360442457; bh=ycqntLIEe2GW9NfY7cjOG6EFBwkp2hCt+4I72IGMXcc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:In-Reply-To: References; b=fRZtt2kRMuyXrIv5a0mNyNTistdEZqwyZtWMAIZqmc3WNYynStbZbq+gWBnjcw63n kvekLlwwFKnnVXP8uEGlJ/xNAaEIttCduzD1/Bko5fsuY/VFKo92783kGyz/swWHIu wdf9rsve7R0R9X1592IrYP24w6qoV4zlyZQa3nQo= From: "W. Trevor King" To: Catalyst Cc: "W. Trevor King" Subject: [gentoo-catalyst] =?UTF-8?q?=5BPATCH=201/4=5D=20doc/HOWTO=3A=20First=20pass=20at=20a=20gentle=20Catalyst=20introduction?= Date: Sat, 09 Feb 2013 15:40:30 -0500 Message-id: X-Mailer: git-send-email 1.7.12.4 In-reply-to: References: In-reply-to: References: Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-catalyst@lists.gentoo.org Reply-to: gentoo-catalyst@lists.gentoo.org MIME-version: 1.0 Content-type: text/plain; charset=UTF-8 Content-transfer-encoding: 8bit X-Archives-Salt: 5a0bf1e7-ef20-4bb8-9a8a-e3d9637aa8d7 X-Archives-Hash: d826276e3a5ab8a390d1968d01fc2b0c From: "W. Trevor King" --- 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 0000000..ea9c8f4 --- /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/