Re: [gentoo-catalyst] [PATCH v6] doc/HOWTO.txt: Fix stage descriptions, and add extra context

["Jorge Manuel B. S. Vicetto" <jmbsvicetto@gentoo.org>]

On Fri, 20 Dec 2013, W. Trevor King wrote:

> From: "W. Trevor King" <wking@tremily.us>
>
> 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`).

To "correct" my previous e-mail, I say we use this version, not the one I 
replied to before.

Jorge