[gentoo-catalyst] [PATCH] doc/HOWTO.txt: Fix stage descriptions

[gentoo-catalyst] [PATCH] doc/HOWTO.txt: Fix stage descriptions

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Thanks to Zero_Chaos for clarification on #gentoo-releng.
---
 doc/HOWTO.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
index 5717f80..90593d7 100644
--- a/doc/HOWTO.txt
+++ b/doc/HOWTO.txt
@@ -137,10 +137,12 @@ 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.
+   (a profile's `packages.build` toolchain built with external seed
+   tools).
+2. Stage1 + bootstrapped Portage (`/usr/portage/scripts/bootstrap.sh`).
+3. Stage2 + base system compiled (the base `@system` built with stage2
+   tools).
+4. Stage3 + non-base packages (`@world`).
 
 For more details on the differences between the stages, look at the
 target helper scripts (e.g. `targets/stage1/*.sh`).
-- 
1.8.4

Re: [gentoo-catalyst] [PATCH] doc/HOWTO.txt: Fix stage descriptions

[Rick "Zero_Chaos" Farina]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12/19/2013 06:48 PM, W. Trevor King wrote:
> From: "W. Trevor King" <wking@tremily.us>
> 
> Thanks to Zero_Chaos for clarification on #gentoo-releng.
> ---
>  doc/HOWTO.txt | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
> index 5717f80..90593d7 100644
> --- a/doc/HOWTO.txt
> +++ b/doc/HOWTO.txt
> @@ -137,10 +137,12 @@ 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.
> +   (a profile's `packages.build` toolchain built with external seed
> +   tools).
> +2. Stage1 + bootstrapped Portage (`/usr/portage/scripts/bootstrap.sh`).
NACK- this isn't accurate. stage2 runs /usr/portage/scripts/bootstrap.sh
not stage1

- -Zero

> +3. Stage2 + base system compiled (the base `@system` built with stage2
> +   tools).
> +4. Stage3 + non-base packages (`@world`).
>  
>  For more details on the differences between the stages, look at the
>  target helper scripts (e.g. `targets/stage1/*.sh`).
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSs55aAAoJEKXdFCfdEflKkAkP/RUM9xdmYaeCfNIpJRwbaMyK
LfwAfwx2Uk9PLvO+79HpLLBDGprpC+IWwpm6v0sDI6e8EzDqPDqEVEsf3Gzi8BXt
kc1oKTGR7tc6GFu/tMaDgv6cnR3mNviloIjTIknnYQwdNzWRFQoyCYGfB6CqIFBm
/TztzUuulAbOflEpBPpPPaK/51zwSCghLoCswFw3sJon6B7DcgnKNccYjQSn5Ztj
uwFdM32fb8qC3mTE5wSReDT7HxXDeAoaFDCWUDuxBNHuZryZlPchkTkuCuKOMe+s
EgGFiNm0bM94S43G32cFBsjFYjYMMVyDCtnfXDGD9O1BbuZVQPqO1KAON3FtuJQ8
XHRPtTv8EOCGNrAPuEBoaukoOEb5yhk0LDoNWH6yCmfqDvsC/NCj0L+f6mf45kAp
mzZ7ildaYjFUPMrwol4UiMTkmiun3PAFepsk+RtSiugqqH2cKFxP6gKgGEkNY5Nz
dThPbJZunq4uVy8hU9q5ltVrLleHjGsCk0HVHcf2KUXWClEwEaRMN7vmhdoS2D4b
yIKODHfAqRRJpSJJQ8vV49tSFbjhl37fGiaDIJy2rq8RMlNw4ZHnCB8YMQ/DtTcS
T3y3kST4zvYEu9BKq7Q97lvWcD39Cr1g800RvlKh2SBivDBMHSHM2jZwCq8Mk7Dl
1UEOzqE9ayCQWQ/eE6ZZ
=yV3H
-----END PGP SIGNATURE-----

Re: [gentoo-catalyst] [PATCH] doc/HOWTO.txt: Fix stage descriptions

[Rick "Zero_Chaos" Farina]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12/19/2013 08:33 PM, Rick "Zero_Chaos" Farina wrote:
> On 12/19/2013 06:48 PM, W. Trevor King wrote:
>> From: "W. Trevor King" <wking@tremily.us>
> 
>> Thanks to Zero_Chaos for clarification on #gentoo-releng.
>> ---
>>  doc/HOWTO.txt | 10 ++++++----
>>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
>> diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
>> index 5717f80..90593d7 100644
>> --- a/doc/HOWTO.txt
>> +++ b/doc/HOWTO.txt
>> @@ -137,10 +137,12 @@ 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.
>> +   (a profile's `packages.build` toolchain built with external seed
>> +   tools).
>> +2. Stage1 + bootstrapped Portage (`/usr/portage/scripts/bootstrap.sh`).
> NACK- this isn't accurate. stage2 runs /usr/portage/scripts/bootstrap.sh
> not stage1
> 
NACK NACK, I can't read properly.  Since I was confused wking has agreed
on irc to a new format entirely to avoid people as stupid as me.

Waiting on V2
- -Zero
> 
>> +3. Stage2 + base system compiled (the base `@system` built with stage2
>> +   tools).
>> +4. Stage3 + non-base packages (`@world`).
> 
>>  For more details on the differences between the stages, look at the
>>  target helper scripts (e.g. `targets/stage1/*.sh`).
> 
> 
> 
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSs7DPAAoJEKXdFCfdEflKJyoP/3k4f6SsQF2Rk15rzsWlvrNX
dxMen6rBZqNT5BiEcgZngJzDPDdMYqCfYBis3qFVtTVQX+QIbEXPzJJ2kWgSpPQv
br0kVvUvhrzSEM8o0r4ohVkLNq5PfsAQqz4Zcbbs00Y05HX/3cF24HxrHzs6UyZA
AVibaTkFf4iZmDClCg9mhjTMRRJ5G4N1m0cuiipLp9Q71XQLS9wlZKLdjsxZx7w9
8coJpfkUj53SWJ7kG0Tvt00XSMioYmKI817VDQFR8QAuKWIEA0e2vFjm/CTMGlDS
S7NOAHE/TUe83iheqKYnVUluIjA8cRxjjZ9ZCmkSZS+Ti+uSvxPJ+h94803QwKnw
Fri6vk1W7d3+tIUtSSYVM7SV0G+LKjbIPsX9H77XUkRQTYMwHPTiO8DqCQXSVNbT
7R4eWWF5aWhX0sIUHyqZWK+bp8GIQ3mujLHJ7kJuuOVOL7Z7zcXlKn2Y2whQzLXb
sV8/bN3UIlq7nYvFWruUc+5bAtRKG/1SsiDuJIrawKQ5c67YG2tsDnNVVjYG/flQ
T6QHXgxvCwPPUESQjUK1wYUeuc1wRE+7JnAeILCfsyyy06LeOzc2FyzKx/osOX/o
45JjU+qiQ4VRPQTEzblhXjXGJ9KJ5sgVBB4a9sXUXGTbxMsJbbw5iShjf7ud7NRc
zhhwkW/UfQbuQbrt2Q87
=IOuA
-----END PGP SIGNATURE-----

[gentoo-catalyst] [PATCH v2] doc/HOWTO.txt: Fix stage descriptions

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Thanks to Zero_Chaos and dwfreed for clarification on #gentoo-releng.
---
 doc/HOWTO.txt | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
index 5717f80..6b0fdf2 100644
--- a/doc/HOWTO.txt
+++ b/doc/HOWTO.txt
@@ -136,11 +136,14 @@ 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    | Bootstrap a profile's `packages.build` toolchain  | stage1
+| stage1         | Bootstrap Portage with Portage's `bootstrap.sh`   | stage2
+| stage2         | Compile the base `@system` packages               | stage3
+| stage3         | Compile additional `@world` packages              | stage4
+|============================================================================
 
 For more details on the differences between the stages, look at the
 target helper scripts (e.g. `targets/stage1/*.sh`).
-- 
1.8.4

[gentoo-catalyst] [PATCH v3] doc/HOWTO.txt: Fix stage descriptions

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Thanks to Zero_Chaos and dwfreed for clarification on #gentoo-releng.
---
Changes from v2:
* Don't mention "Portage" in stage1 → stage2 to avoid confusion
  between Porage-the-software and Portage-the-ebuild-tree.

 doc/HOWTO.txt | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
index 5717f80..20427cf 100644
--- a/doc/HOWTO.txt
+++ b/doc/HOWTO.txt
@@ -136,11 +136,14 @@ 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    | Bootstrap a profile's `packages.build` toolchain             | 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 more details on the differences between the stages, look at the
 target helper scripts (e.g. `targets/stage1/*.sh`).
-- 
1.8.4

Re: [gentoo-catalyst] [PATCH v3] doc/HOWTO.txt: Fix stage descriptions

[Rick "Zero_Chaos" Farina]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12/19/2013 11:17 PM, W. Trevor King wrote:
> From: "W. Trevor King" <wking@tremily.us>
> 
> Thanks to Zero_Chaos and dwfreed for clarification on #gentoo-releng.
> ---
> Changes from v2:
> * Don't mention "Portage" in stage1 → stage2 to avoid confusion
>   between Porage-the-software and Portage-the-ebuild-tree.
> 
>  doc/HOWTO.txt | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
> index 5717f80..20427cf 100644
> --- a/doc/HOWTO.txt
> +++ b/doc/HOWTO.txt
> @@ -136,11 +136,14 @@ 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    | Bootstrap a profile's `packages.build` toolchain             | 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 more details on the differences between the stages, look at the
>  target helper scripts (e.g. `targets/stage1/*.sh`).
> 
ACK. jmbsvicetto, can we still commit docs changes?

- -Zero
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSs8cwAAoJEKXdFCfdEflKRKkP/j6zTfJqsF+ib0gdFREnCtuL
fYvfCIS1tlSnNVlTBzjTk+z8PbGaS0x/lKnNtsfnzp1Mh0nYSLrMORP+AC3szog9
4SXX0wnisTH/tSifdm4I2PcGFsoVAJkscIVU0B9TXk9mmaXi4iEh6qH6AVi1sDFf
AbWlcVZK4/fsXmfmMXJ3gCglAddqB1Hwo+q2HfUMPSHZykFBIPov8jaF+XwkrY3K
i/WrWvPmg1R3KoOW/yDmOKq2si259j6R1tKEgKofBtB3MeNn/o4lpwc+mIn3HwwS
xfdkX0n93bAjP0AKAtxShNL0SRJF4wq/efNfZ86CfjL8hAZkxOrKRF75FIHH+zcg
WgYaTrWO5BaCy6X3PJzYGNU0fHU6zMSUUksl3PWxtMsOheC/uNklK0GsWhxsJ+Ob
ofaIByZO9avRBPvOtEvARjqWsBnAifL9QXCGQKSdxA9MO6fXM/SNaMkBSbd4FV8v
8LCUgNoiYQVQk1wZBMdCrqbS2NwjB95d9bolE5JBDDEn4hbAYYYdfJKsVPNPcB5k
GxOBzn0a47JE4yMRzAN41YvN2KAUOZjRW1rZIYidojwfMdW+E4qRCoGGYLghsnUd
xsTlloHOa/hoNqP1/pIuQYmSEUepYrrkhGTpBAs3arulq69VBr2yHYuepyn8rqTv
H5bHCEuPGCJKn+KWhDI0
=S8L7
-----END PGP SIGNATURE-----

Re: [gentoo-catalyst] [PATCH v3] doc/HOWTO.txt: Fix stage descriptions

[Brian Dolbec]

[-- Attachment #1: Type: text/plain, Size: 1999 bytes --]

On Thu, 2013-12-19 at 20:17 -0800, W. Trevor King wrote:
> From: "W. Trevor King" <wking@tremily.us>
> 
> Thanks to Zero_Chaos and dwfreed for clarification on #gentoo-releng.
> ---
> Changes from v2:
> * Don't mention "Portage" in stage1 → stage2 to avoid confusion
>   between Porage-the-software and Portage-the-ebuild-tree.
> 
>  doc/HOWTO.txt | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
> index 5717f80..20427cf 100644
> --- a/doc/HOWTO.txt
> +++ b/doc/HOWTO.txt
> @@ -136,11 +136,14 @@ 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    | Bootstrap a profile's `packages.build` toolchain             | 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 more details on the differences between the stages, look at the
>  target helper scripts (e.g. `targets/stage1/*.sh`).


This looks good to me.  I like the table showing the steps.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

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

[W. Trevor King]

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

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

[W. Trevor King]

From: "W. Trevor King" <wking@tremily.us>

Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and
review on #gentoo-releng.
---
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 | 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

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

[W. Trevor King]

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`).
-- 
1.8.4

Re: [gentoo-catalyst] [PATCH v3] doc/HOWTO.txt: Fix stage descriptions

[Jorge Manuel B. S. Vicetto]

On Thu, 19 Dec 2013, Rick "Zero_Chaos" Farina wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 12/19/2013 11:17 PM, W. Trevor King wrote:
>> From: "W. Trevor King" <wking@tremily.us>
>>
>> Thanks to Zero_Chaos and dwfreed for clarification on #gentoo-releng.
>> ---
>> Changes from v2:
>> * Don't mention "Portage" in stage1 → stage2 to avoid confusion
>>   between Porage-the-software and Portage-the-ebuild-tree.
>>
>>  doc/HOWTO.txt | 13 ++++++++-----
>>  1 file changed, 8 insertions(+), 5 deletions(-)
>>
>> diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt
>> index 5717f80..20427cf 100644
>> --- a/doc/HOWTO.txt
>> +++ b/doc/HOWTO.txt
>> @@ -136,11 +136,14 @@ 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    | Bootstrap a profile's `packages.build` toolchain             | 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 more details on the differences between the stages, look at the
>>  target helper scripts (e.g. `targets/stage1/*.sh`).
>>
> ACK. jmbsvicetto, can we still commit docs changes?

Let's ensure they don't cause conflicts for dol-sen work. If not, let's 
commit this. So let's commit it to the pending branch.

> - -Zero
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.22 (GNU/Linux)
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iQIcBAEBAgAGBQJSs8cwAAoJEKXdFCfdEflKRKkP/j6zTfJqsF+ib0gdFREnCtuL
> fYvfCIS1tlSnNVlTBzjTk+z8PbGaS0x/lKnNtsfnzp1Mh0nYSLrMORP+AC3szog9
> 4SXX0wnisTH/tSifdm4I2PcGFsoVAJkscIVU0B9TXk9mmaXi4iEh6qH6AVi1sDFf
> AbWlcVZK4/fsXmfmMXJ3gCglAddqB1Hwo+q2HfUMPSHZykFBIPov8jaF+XwkrY3K
> i/WrWvPmg1R3KoOW/yDmOKq2si259j6R1tKEgKofBtB3MeNn/o4lpwc+mIn3HwwS
> xfdkX0n93bAjP0AKAtxShNL0SRJF4wq/efNfZ86CfjL8hAZkxOrKRF75FIHH+zcg
> WgYaTrWO5BaCy6X3PJzYGNU0fHU6zMSUUksl3PWxtMsOheC/uNklK0GsWhxsJ+Ob
> ofaIByZO9avRBPvOtEvARjqWsBnAifL9QXCGQKSdxA9MO6fXM/SNaMkBSbd4FV8v
> 8LCUgNoiYQVQk1wZBMdCrqbS2NwjB95d9bolE5JBDDEn4hbAYYYdfJKsVPNPcB5k
> GxOBzn0a47JE4yMRzAN41YvN2KAUOZjRW1rZIYidojwfMdW+E4qRCoGGYLghsnUd
> xsTlloHOa/hoNqP1/pIuQYmSEUepYrrkhGTpBAs3arulq69VBr2yHYuepyn8rqTv
> H5bHCEuPGCJKn+KWhDI0
> =S8L7
> -----END PGP SIGNATURE-----
>
>

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

[Jorge Manuel B. S. Vicetto]

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

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

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 513 bytes --]

On Tue, Dec 31, 2013 at 05:08:56PM +0000, Jorge Manuel B. S. Vicetto wrote:
> To "correct" my previous e-mail, I say we use this version, not the
> one I replied to before.

Works for me, but I think we should give Zero a bit more time to ack
it too, since he was interested in reviewing up to v3, but hasn't
chimed in yet on v6.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

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

[Rick "Zero_Chaos" Farina]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12/31/2013 12:15 PM, W. Trevor King wrote:
> On Tue, Dec 31, 2013 at 05:08:56PM +0000, Jorge Manuel B. S. Vicetto wrote:
>> To "correct" my previous e-mail, I say we use this version, not the
>> one I replied to before.
> 
> Works for me, but I think we should give Zero a bit more time to ack
> it too, since he was interested in reviewing up to v3, but hasn't
> chimed in yet on v6.
> 
Sorry, been a really miserable holiday, personally and professionally.
Yes, ACK, this is much better than the current and I think explains it
very well.

- -Zero

> Cheers,
> Trevor
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSwz2JAAoJEKXdFCfdEflKCL0QAJxCX4/IMY/OUkVWSdyU3EG2
aZ9B12FY3f339x286mhvXEorH0HpLW6tHEBoh03KZruNZrlzOVqxxmtxtFrdgJmd
vZjFQjaTQ+bKmWi8oAIvIM3s38Y88r6OD+sONSF8yCE8tlo2vhNQVV5wuKgQTAXz
dI7wyvGB5VvBRRg/tGGA0tP/vnG7DnDHqt+5+VMrs+/NcEaBXgT9FgrKuutuu0uP
5p0zzK5nQ8HxRVk1IwEIjdaykpD2FNHP9N12Yadhre2G4E+bqQD/jlDnHvGkwLmf
bU9Mr2KfCUJ7yYXMf+wZ/iz+b/gVYrCLR7yfu67kpB+4Qe0Cu98qrm7dJKBlpsh8
bWOl9uzh9XMziU7sRCuUG9oyTZl2aXPeZGleHDDGF0tjKqNIDr41PpG5NBtAex7d
dnViekuwlC4utMd1+tHB/8cgi1QghuXNCZjqnwyddF8STkZDKorxaFdeEjTrwwoG
o/X+1H1qIVNxd76LZ4XMN/uja7lQJx8BDI/f9kWsxCyoMp50WdLfjFDQZ4FE2EnT
zmyaJRFwDKF4G/3S3faYH16AzyFgkkvxDSyjV6H1Pd1tyQoGdORr3bfCsksGNwAf
JHzB/6UsLR1wgfyn5kqemFfCCncmlJ2Sq7YXCZsgwX0vwxW/P7rZB3SftH3StEOb
MNTim3siPxHLQ7SXFqkP
=rb0N
-----END PGP SIGNATURE-----

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

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 266 bytes --]

This landed in master on 2014-01-05 as commit
ee0825606bc7f2e2eb79ecd70aea4ec31a4c23cc.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]