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 D858F138247 for ; Sat, 21 Dec 2013 05:15:23 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 67ED6E0B36; Sat, 21 Dec 2013 05:15:23 +0000 (UTC) Received: from QMTA11.westchester.pa.mail.comcast.net (qmta11.westchester.pa.mail.comcast.net [76.96.59.211]) by pigeon.gentoo.org (Postfix) with ESMTP id E81CCE0B36 for ; Sat, 21 Dec 2013 05:15:22 +0000 (UTC) Received: from omta10.westchester.pa.mail.comcast.net ([76.96.62.28]) by QMTA11.westchester.pa.mail.comcast.net with comcast id 45AP1n0020cZkys5B5FNR3; Sat, 21 Dec 2013 05:15:22 +0000 Received: from odin.tremily.us ([24.18.63.50]) by omta10.westchester.pa.mail.comcast.net with comcast id 45FL1n00S152l3L3W5FM40; Sat, 21 Dec 2013 05:15:22 +0000 Received: by odin.tremily.us (Postfix, from userid 1000) id 955F7DA43B4; Fri, 20 Dec 2013 21:15:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; t=1387602920; bh=WN1J/wtAVgYW6FYvkhk1YyNKFev+ux94BX6xDIBebL4=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=oD1aFSn5XiwJcP21XXjEv5U/DZp8myq7+v1oR7kMzOxEXAtKCzZakBec9PvZIX85U +5mnCBqObJ0wDati3QsIHixhaUGU/f0ap//MqfsfL7GQZFZ9hijwY3RCKDUp/UEEVr bndR0SulXbfokraVHs87xmFJzStmC+iMeZEyjdmo= From: "W. Trevor King" To: Catalyst Cc: "W. Trevor King" Subject: [gentoo-catalyst] [PATCH v6] doc/HOWTO.txt: Fix stage descriptions, and add extra context Date: Fri, 20 Dec 2013 21:15:19 -0800 Message-Id: <2aa25f5a4b3808d93195967a7c82c64c8b5ea5b6.1387602958.git.wking@tremily.us> X-Mailer: git-send-email 1.8.3.2 In-Reply-To: <912044f862302c1a55275f8cc269a3b3132cf033.1387601926.git.wking@tremily.us> References: <912044f862302c1a55275f8cc269a3b3132cf033.1387601926.git.wking@tremily.us> 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 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; s=q20121106; t=1387602922; bh=XLZZ+Rd+R0fH8pMLXmb69YA4PS+2PekFZ1jju8cM5KE=; h=Received:Received:Received:From:To:Subject:Date:Message-Id: MIME-Version:Content-Type; b=VQ5/SB4gWoevKcAcVEb+c2eSYYdwmOCoVb/gloONJf5BWAnvGACHu3DnVRlVDaIGX R9U3owZTDr/yUHK1D5Hh/FPIeiNNIRJ1vb8ogNkb2K8/b6LATuUSCL+sT7VFS6yQ4w lr8HVlN4OyaCcK0Yal1WqMGZg8HRjn0M3CNqDp8AP/6K/fWO1PdRG8OzUUr46SWogp QMR2gKeJK6NTiwfi0DkEXY0Nj6BRJPeoR/1RSwLJeqZ5e95SX0BtmlB2zWgvw9rSpC 11kL45FQDvNCDZhKwIKRWQmkZVio3JNix1gCQ7mhQy2ZoAvRtU3TOhgBe1JfK2sd2E yEzj+d1WPTmIw== X-Archives-Salt: 0bea2371-2818-4915-8fe2-1ae7a9bb6867 X-Archives-Hash: ff2d1d27fa849d24b23e2ff2f8369ca4 From: "W. Trevor King" Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and review on #gentoo-releng. --- Oops, I accidentally re-pushed the v4 patch as v5. Here's the new patch for real. Changes since v4: * List glibc in the packages.build excerpt * Mention that stage3 is an `emerge -e`, so stuff from stage2 is getting rebuilt. doc/HOWTO.txt | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt index 5717f80..8fe63c1 100644 --- a/doc/HOWTO.txt +++ b/doc/HOWTO.txt @@ -136,11 +136,36 @@ 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. +[options="header",frame="topbot",grid="none"] +|======================================================================================= +| Source | Action | Result +| seed stage3 | Build packages listed in your profile's `packages.build` | stage1 +| stage1 | Rebuild the toolchain with the package tree's `bootstrap.sh` | stage2 +| stage2 | Compile the base `@system` packages | stage3 +| stage3 | Compile additional `@world` packages | stage4 +|======================================================================================= + +For stage1, Catalyst builds the stuff your profile says you need to +get started, using the tools in the seed stage3. It uses Portage's +ability to merge packages into an alternatively-rooted filesystem +(`/tmp/stage1root`, using `ROOT` in `make.conf`). This ensures that +only freshly-built packages end up in stage1. + +A fresh stage1 has newly-compiled versions of everything you need to +build a full system, but all of the stage1 binaries were built with +tools from the seed stage3. For stage2, Catalyst rebuilds a number of +critial packages (GCC, glibc, binutils, ...) using the `bootstrap.sh` +script distributed with the package tree. Rebuilding the packages +using the packages themselves (instead of the seed stage3 tools) gives +an extra layer of separation from any crazy output that the seed +tooling may have generated. + +Once we have a stage2, Catalyst builds all of the base system packages +for stage3, rebuilding any that were already built in stage2 (`emerge +-e @system`). The `@system` set of packages is defined by `packages` +files in your cascading profile. See +http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-520005.2.6[the Package +Manager Specification] for details. For more details on the differences between the stages, look at the target helper scripts (e.g. `targets/stage1/*.sh`). -- 1.8.4