| 1 |
commit: 002ff07eab5ca8074beef4722a215dcf4ee3f9d8 |
| 2 |
Author: W. Trevor King <wking <AT> tremily <DOT> us> |
| 3 |
AuthorDate: Thu Dec 19 23:38:48 2013 +0000 |
| 4 |
Commit: Brian Dolbec <brian.dolbec <AT> gmail <DOT> com> |
| 5 |
CommitDate: Tue Dec 31 17:58:58 2013 +0000 |
| 6 |
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git;a=commit;h=002ff07e |
| 7 |
|
| 8 |
doc/HOWTO.txt: Fix stage descriptions, and add extra context |
| 9 |
|
| 10 |
Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and |
| 11 |
review on #gentoo-releng. |
| 12 |
|
| 13 |
--- |
| 14 |
doc/HOWTO.txt | 35 ++++++++++++++++++++++++++++++----- |
| 15 |
1 file changed, 30 insertions(+), 5 deletions(-) |
| 16 |
|
| 17 |
diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt |
| 18 |
index 5717f80..8fe63c1 100644 |
| 19 |
--- a/doc/HOWTO.txt |
| 20 |
+++ b/doc/HOWTO.txt |
| 21 |
@@ -136,11 +136,36 @@ compiled toolchain, which is where Gentoo's stages come in. The “base |
| 22 |
system” contains the necessary build tools and supporting |
| 23 |
infrastructure to get things going. The stages are: |
| 24 |
|
| 25 |
-1. System must be bootstrapped and the base system must be compiled |
| 26 |
- (a new toolchain built with external seed tools). |
| 27 |
-2. Stage1 + bootstrapped (a new toolchain build with stage1 tools). |
| 28 |
-3. Stage2 + base system compiled (the base system built with stage2 tools). |
| 29 |
-4. Stage3 + non-base packages. |
| 30 |
+[options="header",frame="topbot",grid="none"] |
| 31 |
+|======================================================================================= |
| 32 |
+| Source | Action | Result |
| 33 |
+| seed stage3 | Build packages listed in your profile's `packages.build` | stage1 |
| 34 |
+| stage1 | Rebuild the toolchain with the package tree's `bootstrap.sh` | stage2 |
| 35 |
+| stage2 | Compile the base `@system` packages | stage3 |
| 36 |
+| stage3 | Compile additional `@world` packages | stage4 |
| 37 |
+|======================================================================================= |
| 38 |
+ |
| 39 |
+For stage1, Catalyst builds the stuff your profile says you need to |
| 40 |
+get started, using the tools in the seed stage3. It uses Portage's |
| 41 |
+ability to merge packages into an alternatively-rooted filesystem |
| 42 |
+(`/tmp/stage1root`, using `ROOT` in `make.conf`). This ensures that |
| 43 |
+only freshly-built packages end up in stage1. |
| 44 |
+ |
| 45 |
+A fresh stage1 has newly-compiled versions of everything you need to |
| 46 |
+build a full system, but all of the stage1 binaries were built with |
| 47 |
+tools from the seed stage3. For stage2, Catalyst rebuilds a number of |
| 48 |
+critial packages (GCC, glibc, binutils, ...) using the `bootstrap.sh` |
| 49 |
+script distributed with the package tree. Rebuilding the packages |
| 50 |
+using the packages themselves (instead of the seed stage3 tools) gives |
| 51 |
+an extra layer of separation from any crazy output that the seed |
| 52 |
+tooling may have generated. |
| 53 |
+ |
| 54 |
+Once we have a stage2, Catalyst builds all of the base system packages |
| 55 |
+for stage3, rebuilding any that were already built in stage2 (`emerge |
| 56 |
+-e @system`). The `@system` set of packages is defined by `packages` |
| 57 |
+files in your cascading profile. See |
| 58 |
+http://dev.gentoo.org/~ulm/pms/5/pms.html#x1-520005.2.6[the Package |
| 59 |
+Manager Specification] for details. |
| 60 |
|
| 61 |
For more details on the differences between the stages, look at the |
| 62 |
target helper scripts (e.g. `targets/stage1/*.sh`). |
Archives