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 B53281387B2 for ; Mon, 6 Jan 2014 02:00:56 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 07E78E0BF4; Mon, 6 Jan 2014 02:00:56 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 20FE8E0BF3 for ; Mon, 6 Jan 2014 02:00:55 +0000 (UTC) Received: from hornbill.gentoo.org (hornbill.gentoo.org [94.100.119.163]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 22E8E33F71E for ; Mon, 6 Jan 2014 02:00:54 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by hornbill.gentoo.org (Postfix) with ESMTP id 617F3E5537 for ; Mon, 6 Jan 2014 02:00:52 +0000 (UTC) From: "Brian Dolbec" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Brian Dolbec" Message-ID: <1388723968.ee0825606bc7f2e2eb79ecd70aea4ec31a4c23cc.dol-sen@gentoo> Subject: [gentoo-commits] proj/catalyst:master commit in: doc/ X-VCS-Repository: proj/catalyst X-VCS-Files: doc/HOWTO.txt X-VCS-Directories: doc/ X-VCS-Committer: dol-sen X-VCS-Committer-Name: Brian Dolbec X-VCS-Revision: ee0825606bc7f2e2eb79ecd70aea4ec31a4c23cc X-VCS-Branch: master Date: Mon, 6 Jan 2014 02:00:52 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 93de6d0d-dfb0-4f9a-b645-eeede31389b6 X-Archives-Hash: acf8f50da0d4f378658cf2d3a615f3cd Message-ID: <20140106020052.XPQCkLPmKMGNdJKFIn3WsVZonPI0XcDRIiTOXUHz3Hg@z> commit: ee0825606bc7f2e2eb79ecd70aea4ec31a4c23cc Author: W. Trevor King tremily us> AuthorDate: Thu Dec 19 23:38:48 2013 +0000 Commit: Brian Dolbec gmail com> CommitDate: Fri Jan 3 04:39:28 2014 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=ee082560 doc/HOWTO.txt: Fix stage descriptions, and add extra context Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and review on #gentoo-releng. --- 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`).