Funtoo:Metro/Concepts and Terminology

Metro cannot create a stage tarball out of thin air. To build a new stage tarball, Metro must use an existing, older stage tarball called a "seed" stage. This seed stage typically is used as the build environment for creating the stage we want.

Metro can use two kinds of seed stages. Traditionally, Metro has used a stage3 as a seed stage. This stage3 is then used to build a new stage1, which in turn is used to build a new stage2, and then a new stage3. This is generally the most reliable way to build Gentoo Linux or Funtoo Linux, so it's the recommended approach.

Seeds and Build Isolation

Another important concept to mention here is something called build isolation. Because Metro creates an isolated build environment, and the build environment is explicitly defined using existing, tangible entities -- a seed stage and a portage snapshot -- you will get consistent, repeatable results. In other words, the same seed stage, portage snapshot and build instructions will generate an essentially identical result, even if you perform the build a month later on someone else's workstation.

Local Build

Say you wanted to build a new pentium4 stage3 tarball. The recommended method of doing this would be to grab an existing pentium4 stage3 tarball to use as your seed stage. Metro will be told to use this existing pentium4 stage3 to build a new stage1 for the same pentium4. For this process, the generic pentium4 stage3 would provide the build environment for creating our new stage1. Then, the new stage1 would serve as the build environment for creating the new pentium4 stage2. And the new pentium4 stage2 would serve as the build environment for creating the new pentium4 stage3.

In the Metro terminology this is called a local build, which means a stage3 of a given architecture is used to seed a brand new build of the same architecture. Incidentally this will be the first exercise we are going to perform in this tutorial.

A week later, you may want to build a brand new pentium4 stage3 tarball. Rather than starting from the original pentium4 stage3 again, you'd probably configure Metro to use the most-recently-built pentium4 stage3 as the seed. Metro has built-in functionality to make this easy, allowing it to easily find and track the most recent stage3 seed available.

Remote Build

Metro can also perform remote build, where a stage3 of a different, but binary compatible, architecture is used as a seed to build a different architecture stage3. Consequentiality the second exercise we are going to perform in this tutorial will be to build a core2 32bit stage3 tarball from the pentium4 stage3 tarball we have just built.

TODO: add caveats about what archs can be seeded and what can be not (maybe a table?)

Tailored Build

Last, it's also worthy noting that both in local and remote builds, Metro can be configured to add and/or remove individual packages to the final tarball. Let's say you can't live without app-misc/screen, at the end of this tutorial, we will show how to have your tailored stage3 to include it.