You may wish to use the new [[Metro/AutoSetup|autosetup]] script which uses a curses based menu and allows for quickly setting up and running builds base on your choices without requiring any manual steps. Please see the [[Metro AutoSetup]] page for more details.
== How Metro Works ==
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 === <!--T:9-->
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 === <!--T:11-->
Say you wanted to build a new <tt>pentium4</tt> stage3 tarball. The recommended method of doing this would be to grab an existing <tt>pentium4</tt> stage3 tarball to use as your seed stage. Metro will be told to use this existing <tt>pentium4</tt> stage3 to build a new stage1 for the same <tt>pentium4</tt>. For this process, the generic <tt>pentium4</tt> 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 <tt>pentium4</tt> stage2. And the new <tt>pentium4</tt> stage2 would serve as the build environment for creating the new <tt>pentium4</tt> 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 <tt>pentium4</tt> stage3 tarball. Rather than starting from the original <tt>pentium4</tt> stage3 again, you'd probably configure Metro to use the most-recently-built <tt>pentium4</tt> 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 === <!--T:15-->
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 <tt>core2 32bit</tt> stage3 tarball from the <tt>pentium4</tt> 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 === <!--T:18-->
Last, it's also worthy noting that both in <tt>local</tt> and <tt>remote builds</tt>, Metro can be configured to add and/or remove individual packages to the final tarball.
Let's say you can't live without <tt>app-misc/screen</tt>, at the end of this tutorial, we will show how to have your tailored stage3 to include it.
= Configuring Metro = <!--T:28-->