From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <gentoo-catalyst+bounces-2944-garchives=archives.gentoo.org@lists.gentoo.org> Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id B891D138247 for <garchives@archives.gentoo.org>; Sat, 21 Dec 2013 04:39:14 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 0E68CE0A4A; Sat, 21 Dec 2013 04:39:14 +0000 (UTC) Received: from qmta02.westchester.pa.mail.comcast.net (qmta02.westchester.pa.mail.comcast.net [76.96.62.24]) by pigeon.gentoo.org (Postfix) with ESMTP id 8CAA6E0A4A for <gentoo-catalyst@lists.gentoo.org>; Sat, 21 Dec 2013 04:39:13 +0000 (UTC) Received: from omta02.westchester.pa.mail.comcast.net ([76.96.62.19]) by qmta02.westchester.pa.mail.comcast.net with comcast id 44cw1n0010QuhwU514fCdi; Sat, 21 Dec 2013 04:39:12 +0000 Received: from odin.tremily.us ([24.18.63.50]) by omta02.westchester.pa.mail.comcast.net with comcast id 44fB1n00Q152l3L3N4fCXB; Sat, 21 Dec 2013 04:39:12 +0000 Received: by odin.tremily.us (Postfix, from userid 1000) id A0436DA40A3; Fri, 20 Dec 2013 20:39:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; t=1387600750; bh=pYc9SjsPPWxqyKYUtKBmWyHk3x1oLfOw5o89//P3tzQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=qB9FdtD9Q8LXxY40drA6kagyb3IHa/yEpZs0GWYI/7OESUEvZcMunLiJtBfMjernn K++NmH62ZoYx/KZtzihWNbHHia14/fyTsZ6OLop3Z3DkCpe+E0/Opuh6RS/AhaTkW2 J4YOQCEkHNBcfMbglg5wMyFKultl/j2+j8F2ludI= From: "W. Trevor King" <wking@tremily.us> To: Catalyst <gentoo-catalyst@lists.gentoo.org> Cc: "W. Trevor King" <wking@tremily.us> Subject: [gentoo-catalyst] [PATCH v4] doc/HOWTO.txt: Fix stage descriptions, and add extra context Date: Fri, 20 Dec 2013 20:39:09 -0800 Message-Id: <69cf58e88de190d7308dd8f0c5523fd62c127eda.1387600437.git.wking@tremily.us> X-Mailer: git-send-email 1.8.3.2 In-Reply-To: <3614940041744d107ceff3e460e8549204c9b498.1387512969.git.wking@tremily.us> References: <3614940041744d107ceff3e460e8549204c9b498.1387512969.git.wking@tremily.us> Precedence: bulk List-Post: <mailto:gentoo-catalyst@lists.gentoo.org> List-Help: <mailto:gentoo-catalyst+help@lists.gentoo.org> List-Unsubscribe: <mailto:gentoo-catalyst+unsubscribe@lists.gentoo.org> List-Subscribe: <mailto:gentoo-catalyst+subscribe@lists.gentoo.org> List-Id: Gentoo Linux mail <gentoo-catalyst.gentoo.org> 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=1387600752; bh=IPDP2JLEFTgUQXnfni1jgCBCThiM5765u/EBmElXgJI=; h=Received:Received:Received:From:To:Subject:Date:Message-Id: MIME-Version:Content-Type; b=fiuHA8l+qqvqEP31UO4db+OElrAK0rFvCYTl+WthvVQ/EUTV8EOgTdzNcRPIXWixl bVxgYPLHRX0XozpG4v0EXKUzbvaka4wmGoVpO1foTz0G+H3sLIKdPd0YYlFlOHmgXU JGRa5AokPGgf0CKniTWHZGeOurpNlz/RTDrSjGMo7GznTFZNkB4MRrUMHjm//DifoV FP/DvSQZb0NLErCcwOztk5OTN/NAVOdyVS5INcGa9rOuSW7VLyFPi/tTrhJWB8c/51 gLJOZQp0Rd9RRZfx4BpxhiA7MdhVvWgZSyfuVvYMSnmFsgWfhAMW7Oz34MtMqcRdam 4SYCpkUAbJkPQ== X-Archives-Salt: 1c70b79e-1053-47f6-bef2-5ba46de434e9 X-Archives-Hash: f81f287bf615b1090a9c02c3ad95d67c From: "W. Trevor King" <wking@tremily.us> Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and review on #gentoo-releng. --- Changes from v3: * Don't mention "bootstrap" or "toolchain" in the seed stage3 → stage1 table action. jmbsvicetto points out that bootstrap may be confused with the bootstrap.sh script used for stage1 → stage2, and that there are non-toolchain packages in packages.build. Why there are non-toolchain packages in packages.build is beyond my comprehension, but it's good to match reality ;). * Add a few explanantory paragraphs going into detail about exactly what's going on and how it's technically happening. This should be enough so that an experienced PMS-tree user can get a feel for which packages will be build in which stage without having to look at the targets/stage*/*.sh scripts at all. doc/HOWTO.txt | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt index 5717f80..1573d59 100644 --- a/doc/HOWTO.txt +++ b/doc/HOWTO.txt @@ -136,11 +136,35 @@ 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, 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, stages3 is a standard `emerge` of the base +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