Difference between pages "Funtoo Linux FAQ" and "Metro"

(Difference between pages)
(How do I start using Funtoo Linux?)
 
 
Line 1: Line 1:
== Common Misconceptions, Rumors, etc. ==
+
[[Metro]] is the build system for Funtoo Linux and [[Gentoo Linux]] stages. It automates the bootstrapping process.
  
=== Does Funtoo Linux use a Red Hat kernel? ===
+
This tutorial will take you through installing, setting up and running [[Metro]].
  
Funtoo Linux users are free to choose their own kernel, and we offer additional kernels from other Linux distributions such as Debian, Red Hat Enterprise Linux and others. These are documented on the [[Funtoo Linux Kernels]] page.
+
These other Metro documents are also available:
  
=== Does Funtoo use an overlay? ===
+
{{#ask: [[Category:Metro]]
 +
|format=ul
 +
}}
  
An overlay is a Portage tree that is added "on top of" an existing Portage tree. Funtoo Linux allows you to use overlays, and we use overlays for development, but we deliver a single Funtoo Portage tree via git. This tree is generated automatically from the Gentoo Portage tree and a number of other overlays, and merged into a single tree. This is the tree that you get when you run <tt>emerge --sync</tt>.
+
= Preface =
  
=== Can I Turn my Gentoo system into Funtoo Linux by using <tt>funtoo-overlay</tt>? ===
+
== How Metro Works ==  
  
We do have a primary development repository called <tt>funtoo-overlay</tt>, and its name is somewhat of a misnomer. You can't simply use it as an overlay on top of a Gentoo Portage tree to create a Funtoo Linux system.
+
Metro is the Funtoo Linux automated build system, and is used to build Funtoo Linux stage tarballs.
  
== Using Funtoo Linux, Portage and Git ==
+
[[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.
  
=== How do I start using Funtoo Linux? ===
+
[[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.
 +
{{fancyimportant|'''After switching metro builds to Funtoo profile, Gentoo stages are no longer provided'''!}}
  
For information on how to start using Funtoo Linux, see [[Funtoo Linux Installation]].
+
== Seeds and Build Isolation ==
  
=== Is it possible to convert an existing Gentoo Linux install to Funtoo Linux? ===
+
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.
  
Yes, it is possible, but I am no longer supporting this method as it can be problematic and is always sub-optimal to installing Funtoo Linux from a stage3.
+
== Local Build ==
  
=== I can't use <tt>emerge --sync</tt> to download an initial Portage tree. ===
+
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.
  
Make sure you have the following in <tt>/etc/portage/make.conf</tt>:
+
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.
<pre>
+
SYNC="git://github.com/funtoo/ports-2012.git"
+
</pre>
+
  
{{Fancynote| Recent versions of portage do not require hard-coded SYNC variables. In fact, after you have synced and to, you should remove the SYNC line from your make.conf.}}
+
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.
  
=== I try to emerge something and Portage complains that a digest is not found. ===
+
== Remote Build ==  
  
You are using a Funtoo mini-manifest tree and forgot to enable mini-manifest. To do this, add the following to <tt>/etc/portage/make.conf</tt>:
+
[[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.
<pre>
+
FEATURES="mini-manifest"
+
</pre>
+
  
=== What is mini-manifest? ===
+
TODO: add caveats about what archs can be seeded and what can be not (maybe a table?)
  
Funtoo's default Portage tree has gone on a diet - Manifests now include only entries for distfiles (source tarballs.) For everything else, we rely on git's internal integrity-checking mechanisms which is based on SHA1 digests.
+
== Tailored Build ==
  
In addition, our mini-Portage tree does not include ChangeLogs for additional space savings. This allows us to offer a Portage tree snapshot that is under 30MB in size when compressed.
+
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.
  
=== How do I update my git-based Portage tree? ===
+
== Installing Metro ==
  
If you already have an existing git-based Portage tree, you can update it by typing:
+
'''The recommended and supported method''' is to use the Git repository of [[Metro]]. 
 +
 
 +
Ensure that {{Package|dev-vcs/git}} and {{Package|dev-python/boto}} (optional; required for EC2 support) are installed on your system:
  
 
<console>
 
<console>
###i## emerge --sync
+
# ##i##emerge dev-vcs/git
 +
# ##i##emerge dev-python/boto
 
</console>
 
</console>
  
=== I set up my initial git-based Portage tree, but <tt>/usr/portage</tt> seems to be empty. ===
+
Next, clone the master git repository as follows:
 
+
You forgot to type:
+
  
 
<console>
 
<console>
###i## cd /usr/portage
+
# ##i##cd /root
###i## git checkout funtoo.org
+
# ##i##git clone git://github.com/funtoo/metro.git
 +
# ##i##cp /root/metro/metro.conf ~/.metro
 
</console>
 
</console>
Funtoo Linux's portage tree snapshot ships with a mostly empty branch active by default to reduce the size of the resultant snapshot tarball.
 
  
=== What is different with Funtoo's UTF-8 support? ===
+
You will now have a directory called <tt>/root/metro</tt> that contains all the [[Metro]] source code.
  
Funtoo Linux has UTF-8 enabled by default, even for the <tt>root</tt> user. This allows UTF-8 files to be edited without issue, <tt>root</tt> GNU screen sessions to display UTF-8 character sets properly, etc. The classic sort order of <tt>ls -a</tt> has been preserved by setting <tt>LC_COLLATE</tt> to <tt>POSIX</tt>. All other locale settings inherit the system default defined in the <tt>LANG</tt> variable, which is set to <tt>en_US.UTF-8</tt>.
+
Metro is now installed. It's time to customize it for your local system.
  
=== What if I want to use a non-English locale/language? ===
+
= Configuring Metro =
  
I recommend two things. First, it's strongly recommended that you always use a UTF-8-based locale.
+
{{Note|Metro is not currently able to build Gentoo stages. See {{Bug|FL-901}}.}}
  
The next thing I recommend is to try to avoid changing the global system LANG setting, and instead set the LANG setting on a per-user basis by adding the desired LANG setting to your <tt>~/.bashrc</tt>. This will preserve English log output in <tt>/var/log</tt> and make it easier to search for more common matching English strings on the Internet when you need help.
+
[[User:Drobbins|Daniel Robbins]] maintains [[Metro]], so it comes pre-configured to successfully build [[Funtoo Linux]] releases. Before reading further, you might want to customize some basic settings like the number of concurrent jobs to fit your hardware's capabilities or the directory to use for produced stage archives. This is accomplished by editing <tt>~/.metro</tt> which is the [[Metro]]'s master configuration file.
  
If you really want to change the default system LANG setting (taking into account the paragraph above,) then it's recommended that you create your own <tt>/etc/env.d/02locale</tt> file that contains something like this:
+
Please note that <code>path/install</code> must point to where metro was installed. Point <code>path/distfiles</code> to where your distfiles reside. Also set <code>path/mirror/owner</code> and <code>path/mirror/group</code> to the owner and group of all the files that will be written to the build repository directory, which by default (as per the configuration file) is at <code>/home/mirror/funtoo</code>. The cache directory normally resides inside the temp directory -- this can be modified as desired. The cache directory can end up holding many cached .tbz2 packages, and eat up a lot of storage. You may want to place the temp directory on faster storage, for faster compile times, and place the cache directory on slower, but more plentiful storage.
<pre>
+
LANG="fr_CA.UTF-8"
+
</pre>
+
You will need to run <tt>env-update</tt> and <tt>source /etc/profile</tt> to apply changes immediately to any open shells, and reboot to apply changes fully.
+
  
=== What is different with Funtoo's Ruby? ===
+
{{file|name=.metro|desc=Metro configuration|body=
 +
# Main metro configuration file - these settings need to be tailored to your install:
  
Funtoo Linux tracks Gentoo's Ruby, but we do have one change for ruby-1.9 and greater - the binary name is changed with /usr/bin/ruby1.9 instead of Gentoo's /usr/bin/ruby19. This makes the versioning consistent with Python binaries and MacOS X. This means that for ruby-1.9 and greater. While the path to the binary has changed, all Portage variables are the same as Gentoo, so you should use &quot;ruby19&quot; for the <tt>RUBY_TARGETS</tt> setting in <tt>/etc/make.conf</tt>.
+
[section path]
 +
install: /root/metro
 +
tmp: /var/tmp/metro
 +
cache: $[path/tmp]/cache
 +
distfiles: /var/src/distfiles
 +
work: $[path/tmp]/work/$[target/build]/$[target/name]
  
=== Ruby 1.9 is masked. How do I use it? ===
+
[section path/mirror]
  
Add the following to <tt>/etc/portage/make.conf</tt>:
+
: /home/mirror/funtoo
<pre>
+
owner: root
RUBY_TARGETS="ruby19"
+
group: repomgr
</pre>
+
dirmode: 775
  
Then unmask ruby-1.9 as follows:
+
[section portage]
  
<console>
+
MAKEOPTS: auto
###i## install -d /etc/portage
+
###i## echo "dev-lang/ruby:1.9" >> /etc/portage/package.unmask
+
</console>
+
If you are using Funtoo stable, then you will also need to do this:
+
  
<console>
+
[section emerge]
###i## echo "dev-lang/ruby:1.9" >> /etc/portage/package.keywords
+
</console>
+
  
=== Why is Funtoo Linux still an older udev? ===
+
options: --jobs=4 --load-average=4 --keep-going=n
  
Funtoo Linux currently uses udev-160 and generally updates udev less frequently than in Gentoo Linux.
+
# This line should not be modified:
 +
[collect $[path/install]/etc/master.conf]
 +
}}
  
=== What is the minimum kernel version I can use with Funtoo Linux? ===
+
== Arch and Subarch ==
 
+
Without making changes to the default version of the udev package, Funtoo Linux is compatible with kernel versions 2.6.27 and greater. To use earlier kernels or enterprise kernels, see below.
+
 
+
=== I need to use a kernel earlier than 2.6.27. What should I do? ===
+
 
+
To use a RHEL5 or RHEL5-based kernel, you will need to use udev-146 or earlier. Funtoo Linux provides these versions in its portage tree. All you need to do is add the following line to <tt>/etc/portage/package.mask</tt>:
+
<pre>
+
>=sys-fs/udev-160
+
</pre>
+
 
+
Then, emerge {{Package|sys-fs/udev}}:
+
  
 +
In the following example we are creating a pentium4 stage 3 compiled for x86-32bit binary compatibility. Pentium4 is a subarch of the x86-32bit architecture. Once you have metro installed you may find a full list of each subarch in your <tt>/root/metro/subarch</tt> directory each subarch will have the file extension .spec
 +
Example:
 
<console>
 
<console>
###i## emerge udev
+
###i## ls /root/metro/subarch
 +
# ls subarch/
 +
amd64-bulldozer-pure64.spec  armv7a.spec          core-avx-i.spec        i686.spec        pentium.spec
 +
amd64-bulldozer.spec        armv7a_hardfp.spec  core2_32.spec          k6-2.spec        pentium2.spec
 +
amd64-k10-pure64.spec        athlon-4.spec        core2_64-pure64.spec    k6-3.spec        pentium3.spec
 +
amd64-k10.spec              athlon-mp.spec      core2_64.spec          k6.spec          pentium4.spec
 +
amd64-k8+sse3.spec          athlon-tbird.spec    corei7-pure64.spec      native_32.spec    pentiumpro.spec
 +
amd64-k8+sse3_32.spec        athlon-xp.spec      corei7.spec            native_64.spec    prescott.spec
 +
amd64-k8-pure64.spec        athlon.spec          generic_32.spec        niagara.spec      ultrasparc.spec
 +
amd64-k8.spec                atom_32.spec        generic_64-pure64.spec  niagara2.spec    ultrasparc3.spec
 +
amd64-k8_32.spec            atom_64-pure64.spec  generic_64.spec        nocona.spec      xen-pentium4+sse3.spec
 +
armv5te.spec                atom_64.spec        generic_sparcv9.spec    opteron_64.spec  xen-pentium4+sse3_64.spec
 +
armv6j.spec                  btver1.spec          geode.spec              pentium-m.spec
 +
armv6j_hardfp.spec          btver1_64.spec      i486.spec              pentium-mmx.spec
 
</console>
 
</console>
  
You can now reboot with a RHEL5-based kernel and udev will still work properly. <tt>udev-135</tt> is also available for even earlier kernels.
+
= First stages build (local build) =
  
=== How do I use a RHEL5-based kernel, such as openvz-sources-2.6.18* with Funtoo? ===
+
To get this all started, we need to bootstrap the process by downloading an initial seed stage3 to use for building and place it in its proper location in <tt>/home/mirror/funtoo</tt>, so that [[Metro]] can find it. We will also need to create some special &quot;control&quot; files in <tt>/home/mirror/funtoo</tt>, which will allow [[Metro]] to understand how it is supposed to proceed.
  
The steps required to do this, including downgrading udev and emerging gcc-4.1.2, can be found in the [[RHEL5 Kernel HOWTO]]
+
== Step 1: Set up pentium4 repository (local build) ==
  
=== Why is package.mask a directory? ===
+
Assuming we're following the basic steps outlined in the previous section, and building an unstable funtoo (<tt>funtoo-current</tt>) build for the <tt>pentium4</tt>, using a generic <tt>pentium4</tt> stage3 as a seed stage, then here the first set of steps we'd perform:
  
I decided to convert <tt>/usr/portage/profiles/package.mask</tt> to a directory as soon as I discovered that this was a supported feature in the current Portage. This allows us to maintain package.mask data more effectively.
+
<console>
 +
# ##i##install -d /home/mirror/funtoo/funtoo-current/x86-32bit/pentium4
 +
# ##i##install -d /home/mirror/funtoo/funtoo-current/snapshots
 +
# ##i##cd /home/metro/mirror/funtoo/funtoo-current/x86-32bit/pentium4
 +
# ##i##install -d 2011-12-13
 +
# ##i##cd 2011-12-13
 +
# ##i##wget -c http://ftp.osuosl.org/pub/funtoo/funtoo-current/x86-32bit/pentium4/2011-12-13/stage3-pentium4-funtoo-current-2011-12-13.tar.xz
 +
# ##i##cd ..
 +
# ##i##install -d .control/version
 +
# ##i##echo "2011-12-13" > .control/version/stage3
 +
# ##i##install -d .control/strategy
 +
# ##i##echo local >  .control/strategy/build
 +
# ##i##echo stage3 > .control/strategy/seed
 +
</console>
  
=== Git complains and aborts when I emerge --sync. ===
+
OK, let's review the steps above. First, we create the directory <tt>/home/mirror/funtoo/funtoo-current/x86-32bit/pentium4</tt>, which is where Metro will expect to find unstable <tt>funtoo-current</tt> pentium4 builds -- it is configured to look here by default. Then we create a specially-named directory to house our seed x86 stage3. Again, by default, Metro expects the directory to be named this way. We enter this directory, and download our seed x86 stage3 from funtoo.org. Note that the <tt>2010-12-24</tt> version stamp matches. Make sure that your directory name matches the stage3 name too. Everything has been set up to match Metro's default filesystem layout.
  
It appears that a previous git merge was interrupted or did not complete, leaving your portage tree in an intermediate state. Typically, this can be fixed by typing:
+
Next, we go back to the <tt>/home/mirror/metro/funtoo-current/x86-32bit/pentium4</tt> directory, and inside it, we create a <tt>.control</tt> directory. This directory and its subdirectories contain special files that Metro references to determine certain aspects of its behavior. The <tt>.control/version/stage3</tt> file is used by Metro to track the most recently-built stage3 for this particular build and subarch. Metro will automatically update this file with a new version stamp after it successfully builds a new stage3. But because Metro didn't actually ''build'' this stage3, we need to set up the <tt>.control/version/stage3</tt> file manually. This will allow Metro to find our downloaded stage3 when we set up our pentium4 build to use it as a seed. Also note that Metro will create a similar <tt>.control/version/stage1</tt> file after it successfully builds an pentium4 funtoo-current stage1.
  
<console>
+
We also set up <tt>.control/strategy/build</tt> and <tt>.control/strategy/seed</tt> files with values of <tt>local</tt> and <tt>stage3</tt> respectively. These files define the building strategy Metro will use when we build pentium4 funtoo-current stages. With a build strategy of <tt>local</tt>, Metro will source its seed stage from funtoo-current pentium4, the current directory. And with a seed strategy of <tt>stage3</tt>, Metro will use a stage3 as a seed, and use this seed to build a new stage1, stage2 and stage3.
###i## cd /usr/portage
+
###i## git reset --hard origin/funtoo.org
+
</console>
+
This should restore your portage tree to a consistent state and allow future <tt>emerge --sync</tt> commands to complete successfully.
+
  
If this doesn't work, then you may have a conflicted merge. Maybe you modified some local ebuilds? To view conflicts, type <tt>git diff --stat</tt> from within the <tt>/usr/portage</tt> directory. You can choose to either resolve these conflicts or revert back to the official Funtoo Portage tree.
+
== Step 2: Building the pentium4 stages ==
  
If you want to throw away your local changes and simply use the Funtoo Portage tree, you'll need to remove all the files in <tt>/usr/portage</tt> besides the <tt>.git</tt> directory, and then trying the <tt>git reset --hard origin/funtoo.org</tt> command again, as follows:
+
Incidentally, if all you wanted to do at this point was to build a new pentium4 funtoo-current stage1/2/3 (plus openvz and vserver templates). You would begin the process by typing:
  
 
<console>
 
<console>
###i## cd /usr/portage
+
# ##i##cd /root/metro
###i## mv distfiles ..
+
# ##i##scripts/ezbuild.sh funtoo-current pentium4
###i## rm -rf * .gitignore
+
###i## git reset --hard origin/funtoo.org
+
###i## mv ../distfiles .
+
 
</console>
 
</console>
Now everything should be working again.
 
  
=== How do I tell if a problem I am having originates from Gentoo or Funtoo? ===
+
If you have a slow machine, it could take several hours to be completed because several "heavy" components like gcc or glibc have to be recompiled in each stage. Once a stage has been successfully completed, it is placed in the <tt>"${METRO_MIRROR}/funtoo-current/x32-bit/pentium4/YYYY-MM-DD"</tt> subdirectory, where <tt>YYYY-MM-DD</tt> is today's date at the time the <tt>ezbuild.sh</tt> script was started or the date you put on the ezscript.sh command line.
  
You can tell if there are any Funtoo changes to an ebuild by browsing the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay]. All the Funtoo-specific ebuilds can be found in our overlay. If you see an ebuild in my overlay, then we use my version ''instead of'' the Gentoo version. If you don't see it in the funtoo overlay, then it comes from Gentoo.
+
= Building for another binary compatible architecture (remote build) =
  
=== How can I see the differences between the Gentoo and Funtoo Portage trees? ===
+
As written above, [[Metro]] is able to perform '''remote build''' building different architecture stage3 from a binary compatible seeding stage3 (e.g. using a pentium4 stage3 to seed a <tt>Intel Core2 32bits</tt> stage3).
  
In the old days, this was tricky, but now you just look at the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay] for a complete repository of all the Funtoo-specific stuff. Everything ''not'' in the Funtoo overlay comes from Gentoo, with a few exceptions -- see [[Portage Tree]] for details.
+
In the Metro terminology this is called a '''remote build''' (a stage 3 of a different, but binary compatible, architecture is used as a seed).
 +
What's not compatible? You can't use a <tt>Sparc</tt> architecture to generate an <tt>x86</tt> or <tt>ARM</tt> based stage and vice-versa. If you use a 32bit stage then you don't want to seed a 64bit build from it. Be sure that you are using a stage from the same architecture that you are trying to seed. Check [http://ftp.osuosl.org/pub/funtoo/funtoo-current/ Funtoo-current FTP Mirror] for a stage that is from the same Architecture that you will be building.
  
=== Is Paludis compatible with the Funtoo Portage tree? ===
+
{{Note|Often, one build (ie. funtoo-current) can be used as a seed for another build such as funtoo-stable. However, hardened builds require hardened stages as seeds in order for the build to complete successfully.}}
  
Paludis does not appear to be compatible with the Funtoo Portage tree, unfortunately. It does not support the <tt>package.mask</tt> directory without additional hooks, and also does not support merging device nodes. These features are supported by Portage and we use both of these capabilities. I think that both <tt>package.mask</tt> (and <tt>package.keywords</tt>, etc.) directories are a good idea, and I also think it's a good idea for the package manager to support device nodes, which is particularly useful for the <tt>udev</tt> and <tt>baselayout</tt> ebuilds. Funtoo Linux has separate versions of these packages, and these ebuilds are easier to maintain if device nodes are correctly supported by the package manger, and the <tt>package.mask</tt> directory is a great help to us as well.
+
== Step 1: Set up Core_2 32bit repository ==
  
We could maintain a patched version of Paludis that would be useable with the Funtoo Portage tree, but I don't want to get into the business of supporting a non-standard package manager as the upstream project seems not seem very supportive of getting these compatibility issues resolved, and thus this could turn into a maintenance burden for Funtoo. So I'd rather just not support Paludis for now.
+
In this example, we're going to use this pentium4 funtoo-current stage3 to seed a new Core_2 32bit funtoo-current build. To get that done, we need to set up the pentium4 build directory as follows:
  
=== What about pkgcore? ===
+
<console>
 +
# ##i## cd /home/mirror/funtoo/funtoo-current/x86-32bit
 +
# ##i##install -d core2_32
 +
# ##i##cd core2_32
 +
# ##i##install -d .control/strategy
 +
# ##i##echo remote > .control/strategy/build
 +
# ##i##echo stage3 > .control/strategy/seed
 +
# ##i##install -d .control/remote
 +
# ##i##echo funtoo-current > .control/remote/build
 +
# ##i##echo x86-32bit > .control/remote/arch_desc
 +
# ##i##echo pentium4 > .control/remote/subarch
 +
</console>
  
Pkgcore is not currently compatible with Funtoo Linux but efforts are under way to resolve this.
+
The steps we follow are similar to those we performed for a ''local build'' to set up our pentium4 directory for local build. However, note the differences. We didn't download a stage, because we are going to use the pentium4 stage to build a new Core_2 32bit stage. We also didn't create the <tt>.control/version/stage{1,3}</tt> files because Metro will create them for us after it successfully builds a new stage1 and stage3. We are still using a <tt>stage3</tt> seed strategy, but we've set the build strategy to <tt>remote</tt>, which means that we're going to use a seed stage that's not from this particular subdirectory. Where are we going to get it from? The <tt>.control/remote</tt> directory contains this information, and lets Metro know that it should look for its seed stage3 in the <tt>/home/mirror/funtoo/funtoo-current/x86-32bit/pentium4</tt> directory. Which one will it grab? You guessed it -- the most recently built ''stage3'' (since our seed strategy was set to <tt>stage3</tt>) that has the version stamp of <tt>2010-12-24</tt>, as recorded in <tt>/home/mirror/funtoo-current/x86-32bit/pentium4/.control/version/stage</tt>. Now you can see how all those control files come together to direct Metro to do the right thing.
  
=== How do I report a bug? ===
+
{{Note|<code>arch_desc</code> should be set to one of: <code>x86-32bit</code>, <code>x86-64bit</code> or <code>pure64</code> for PC-compatible systems. You must use a 32-bit build as a seed for other 32-bit builds, and a 64-bit build as a seed for other 64-bit builds.}}
  
The best way to report your bug is to describe the issue you are having on the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list]. Another option is to ask for support in the [irc://irc.freenode.net/funtoo #funtoo]. In general, it's best to contact us first about an issue you are having, rather than opening a Gentoo bug report, unless you are quite familiar with the issue and are fairly certain that it is not a Funtoo Linux issue.
+
== Step 2: Building the Core_2 32bit stages ==
  
If you report a bug to Gentoo that may impact Funtoo Linux in some way, please post information about it to the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] so we are aware of the issue.
+
Now, you could start building your new Core_2 32bit stage1/2/3 (plus openvz and vserver templates) by typing the following:
  
* More informations: [[Reporting Bugs|Guidelines for Reporting Bugs]].
+
<console>
 +
# ##i##/root/metro/scripts/ezbuild.sh funtoo-current core2_32
 +
</console>
  
=== How do I become a Funtoo developer? ===
+
In that case, the produced stages are placed in the <tt>/home/mirror/funtoo/funtoo-current/x32-bit/core2_32/YYYY-MM-DD</tt> subdirectory.
  
Funtoo is a personal project of mine, so I'm the only real developer. However, I involve everyone on the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo] in what I am doing so that patches, feedback, requests, etc. can be shared. My advice is to get involved in the Funtoo community on the mailing list and irc channel.
+
== Step 3: The Next Build ==
  
== General Funtoo Stuff ==
+
At this point, you now have a new Core_2 32bit stage3, built using a "remote" pentium4 stage3. Once the first remote build completes successfully, metro will automatically change <code>.control/strategy/build</code> to be <code>local</code> instead of <code>remote</code>, so it will use the most recently-built Core_2 32bit stage3 as a seed for any new Core_2 32bit builds from now on.
  
=== What is funtoo.org? ===
+
= Build your own tailored stage3 =
  
Funtoo.org is the online home of Daniel Robbins (me) and is a place to put all my stuff.
+
Metro can be easily configured for building custom stage3 by including additional packages. Edit the following configuration file <tt>/root/metro/etc/builds/funtoo-current/build.conf</tt>:
 +
{{file|name=funtoo-current/build.conf|body=
 +
[collect ../../fslayouts/funtoo/layout.conf]
  
=== What kind of stuff? ===
+
[section release]
  
Well, I have Funtoo Linux, which is a Gentoo Linux variant. Then I have technical articles -- some new, and some updated versions of originals that appeared on IBM developerWorks.
+
author: Daniel Robbins <drobbins@funtoo.org>
  
Then I have [[Metro]], an operating system build tool, and I have [[Keychain]], which is a tool to help you manage RSA and DSA keys for ssh.
+
[section target]
  
So Funtoo is not just Funtoo Linux.
+
compression: xz
  
=== What is 'Funtoo' all about? And 'Funtoo Linux'? ===
+
[section portage]
  
<tt>Funtoo</tt> by itself refers to this site, or the larger <tt>Funtoo</tt> project run by Daniel Robbins. That's just a fancy way of saying that <tt>Funtoo</tt> refers to all the stuff I'm doing.
+
FEATURES:
 +
SYNC: $[snapshot/source/remote]
 +
USE:
  
''Funtoo Linux'' refers specifically to my variant of Gentoo Linux.
+
[section profile]
  
If you see me use the phrase <tt>Funtoo Portage tree</tt> or <tt>Funtoo ebuild</tt>, I'm just talking about our separate (and slightly different) Portage tree, or our version of an ebuild.
+
format: new
 +
path: gentoo:funtoo/1.0/linux-gnu
 +
arch: $[:path]/arch/$[target/arch_desc]
 +
build: $[:path]/build/current
 +
flavor: $[:path]/flavor/core
 +
mix-ins:
  
=== What is 'tnufoo'? ===
+
[section version]
  
<tt>tnufoo</tt> is <tt>funtoo</tt> rotated 180 degrees vertically.
+
python: 2.7
  
=== How many developers are working on Funtoo Linux? ===
+
[section emerge]
  
Funtoo Linux development is led by Daniel Robbins, along with a [[Core Team]] that also makes significant contributions to Funtoo Linux development and Funtoo infrastructure.
 
  
=== Is Funtoo Linux a fork of Gentoo Linux? ===
+
[section snapshot]
  
It depends on your definition of <tt>fork</tt>. Officially, I am calling Funtoo Linux a <tt>Gentoo Linux variant</tt>, meaning that it is more like another flavor of Gentoo than a fork.
+
type: live
 +
compression: xz
  
We share our changes and bug fixes with the Gentoo project, so Gentoo is free to merge in any of our changes at any time. We also merge in Gentoo's changes every 12 hours.
+
[section snapshot/source]
  
I could officially call Funtoo Linux a fork of Gentoo Linux, but Gentoo could merge most of our changes into Gentoo proper and then what would Funtoo Linux be? It'd be my variant of Gentoo, that's what it'd be. So let's just call it a variant of Gentoo.
+
type: git
 +
branch: funtoo.org
 +
# branch to have checked out for tarball:
 +
branch/tar: origin/master
 +
name: ports-2012
 +
remote: git://github.com/funtoo/ports-2012.git
 +
options: pull
  
=== What is the best way to interact with the Funtoo community? ===
+
[section metro]
  
I recommend joining the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and, if desired, hanging out in the [irc://irc.freenode.net/funtoo #funtoo] on freenode.
+
options:  
 +
options/stage: cache/package
 +
target: gentoo
  
The [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] as well as the [irc://irc.freenode.net/funtoo #funtoo] are unmoderated, open discussion forums for both Funtoo Linux users and developers. In addition, these are ''also'' the official lists for discussing other Funtoo projects such as [[Metro]] and [[Keychain]].
+
[section baselayout]
  
=== What Architectures does Funtoo Linux support? ===
+
services: sshd
  
While Funtoo Linux can run on any architecture that Gentoo Linux supports, we are only maintaining Funtoo Linux for x86 and amd64 architectures. Adding support for other architectures may require a little bit of unmasking work in our Portage tree -- or not. We're not testing anything but x86 and amd64, so we don't know :)
+
[section multi]
  
=== How should a developer use package.mask? ===
+
snapshot: snapshot
  
We currently have four files in the package.mask directory -- <tt>gentoo</tt>, <tt>funtoo</tt>, <tt>funtoo-cautionary</tt> and <tt>sunrise</tt>. Gentoo is an almost pristine version of the upstream gentoo package.mask. It differs from gentoo only in that we will remove stuff from it that we no longer want in it, but we don't ''add'' masks to this file. So if there is a mask in <tt>gentoo</tt>, you know it came upstream from Gentoo.
+
[section files]
  
<tt>funtoo</tt> is where we place our masks. <tt>funtoo-cautionary</tt> is where we place masks that are designed to shield us from upstream unstable version changes to core packages, since we don't want to simply follow Gentoo unstable -- instead, we want to control when gcc and glibc switch to new versions. <tt>sunrise</tt> contains a bunch of sunrise and other miscellaneous masks from the <tt>mpd</tt> overlays. It is currently sort of our &quot;junk drawer&quot; that we'll get around to cleaning up at some point.
+
motd/trailer: [
  
=== Do you use the normal Gentoo system profiles? ===
+
>>> Send suggestions, improvements, bug reports relating to...
  
I've made some minor changes to the Funtoo Linux <tt>profiles/</tt> directory, and I'll continue to make improvements as time goes on. The most recent change I made (as of 17 Jul 2009) was to add <tt>net-dns/openresolv</tt> to the core system profile. Since Funtoo development focuses primarily on the core system, you can expect our system profiles to be somewhat different from Gentoo's. However, from a user perspective, you use them the same way and we have the same profile names that are in Gentoo.
+
>>> This release:                 $[release/author]
 
+
>>> Funtoo Linux (general):        Funtoo Linux (http://www.funtoo.org)
=== Is Funtoo Linux More Stable Than Gentoo Linux? ===
+
>>> Gentoo Linux (general):       Gentoo Linux (http://www.gentoo.org)
 
+
]
That is a hard question to answer directly, as one person's definition of &quot;stable&quot; may be different than another person's, and I do not know how you intend to use Funtoo Linux. So rather than tackle the question head-on, I can give you some additional information that may help you decide:
+
 
+
* The goal of Funtoo Linux is to allow me to improve the Gentoo core system and tools. That does mean that I will be periodically changing various parts of Gentoo plumbing from time to time. When I do this, I try to be careful and provide notices of upcoming major changes on the mailing list, Atom feed and on the Web site.
+
* Both Funtoo Linux and Gentoo Linux have a stable and unstable (<tt>~</tt> - called "current" in Funtoo) tree
+
* The Funtoo and Gentoo trees are 99% identical. However, there are signficant differences in certain areas, particularly the core system and Perl, Python and Ruby.
+
* Funtoo and Gentoo trees do have some significant differences for core packages, particularly <tt>openrc</tt>, <tt>baselayout</tt>, <tt>udev</tt> and <tt>lvm2</tt>.
+
* If it is important to you, Metro is tested daily to ensure that it can build Funtoo Linux (and Gentoo Linux) successfully. However, these builds are not performed in advance of the changes hitting the public git-based Portage tree.
+
* Any Metro Funtoo Linux build failures found are typically fixed in the Funtoo Portage within 0-1 days. Gentoo build failures are only fixed if they are related to an issue with Metro. So there is very fast response in Funtoo to core system build failures. In Gentoo, this process is not as integrated.
+
* Funtoo merges in upstream changes from Gentoo Portage every 12 hours.
+
* I focus on testing the core, non-GUI/non-X system. Sometimes Funtoo will trail behind in udev revisions that cutting-edge desktop users want to run.
+
* Both Funtoo Linux stable and current have OpenRC, dhcpcd-5 and OpenResolv integrated by default.
+
* Funtoo Linux current tries to upgrade certain core packages such as <tt>udev</tt>, <tt>gcc</tt> and <tt>glibc</tt> much less frequently and in a more controlled manner than Gentoo unstable. This may or may not be a benefit to you, depending on what you are looking for. Basically, I am trying to offer the package updates of Gentoo Linux unstable without as much of the (too frequent, in my opinion) core system changes that can often cause problems for people.
+
* The Funtoo receives Gentoo changes once every 12 hours. In contrast, the Gentoo rsync tree receives updates hourly. This means that the changes in the Funtoo tree are compressed into a single monolithic event, whereas the Gentoo tree undergoes more continual, but less signficant, change every hour.
+
* Significant build-related bugs found by Funtoo that also impact Gentoo Linux are sent upstream to [http://bugs.gentoo.org bugs.gentoo.org].
+
 
+
=== Do you use Gentoo's Guide XML for Documentation? ===
+
 
+
I originally created Gentoo's Guide XML format (which I originally created for Gentoo) for documentation, and started to transition away from it in favor of [http://docutils.sourceforge.net/rst.html ReStructuredText]. However, now I am trying to support Guide XML ''and'' [http://docutils.sourceforge.net/rst.html ReStructuredText] as they are both useful for different types of things.
+
 
+
Many funtoo.org articles and documents are maintained in ReStructuredText format. HTML versions of the ReStructuredText documentation are generated by first converting the <tt>.rst</tt> file to XML using <tt>rst2xml.py</tt> (part of the docutils distribution), and then using XSLT to convert the resultant XML to HTML.
+
 
+
To view the plaintext [http://docutils.sourceforge.net/rst.html ReStructuredText] version of a document, append <tt>/index.rst</tt> to any funtoo.org URL. For example, here is the [http://www.funtoo.org/en/funtoo/faq/index.rst ReStructuredText version of this document]
+
 
+
=== Are you looking for translators? ===
+
 
+
Many kind people have provided translations of the funtoo.org pages, and the old version of the site used to contain these translations. However, after much consideration, I've decided to not provide translated versions of funtoo.org pages, for several reasons:
+
 
+
* Translated documents tend to become out-of-date
+
* Updating the translated documents is quite a bit of work
+
* Most people online seem to have at least a basic grasp of English
+
 
+
For these reasons, I'm going to focus on improving the quantity and quality of English documentation, and not focus on translations for now.
+
 
+
== Forking the Portage Tree ==
+
 
+
=== I want to fork the Portage tree. How do I do this? ===
+
 
+
The old way used to involve forking our huge, complete Portage tree. Currently, the best way to do it involves forking the [http://www.github.com/funtoo/funtoo-overlay funtoo-overlay], which is much smaller, or creating your own overlay. I have scripts that combine the Funtoo overlay and the Gentoo tree to create a unified Portage tree.
+
 
+
=== I have forked my own Portage tree. How do I generate metadata for it? ===
+
 
+
You should only do this if you are creating a unified Portage tree for distribution to users. Otherwise, it is much more efficient to use an overlay for this purpose.
+
 
+
First, add <tt>FEATURES=&quot;metadata-transfer&quot;</tt> to your <tt>/etc/make.conf</tt> file. Then type the following commands:
+
 
+
<console>
+
###i## cd /usr/portage
+
###i## egencache --update --jobs=4
+
###i## cd metadata/cache
+
###i## git add .
+
###i## git commit -a
+
</console>
+
<tt>egencache</tt> is part of {{Package|sys-apps/portage}} and was kindly integrated by Zack Medico, Portage maintainer.
+
  
=== Where can I learn more about <tt>git</tt>? ===
+
[collect ../../multi-targets/$[multi/mode:zap]]
 +
}}
  
So, you want to learn more about <tt>git</tt>, do you? A collection of excellent git resources is now available on the [[Git Guide]].
+
= Building Gentoo stages =
  
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
 +
[[Category:Metro]]

Revision as of 18:53, February 20, 2015

Metro is the build system for Funtoo Linux and Gentoo Linux stages. It automates the bootstrapping process.

This tutorial will take you through installing, setting up and running Metro.

These other Metro documents are also available:

{{#ask: |format=ul }}

Preface

How Metro Works

Metro is the Funtoo Linux automated build system, and is used to build Funtoo Linux stage tarballs.

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.

Important

After switching metro builds to Funtoo profile, Gentoo stages are no longer provided!

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.

Installing Metro

The recommended and supported method is to use the Git repository of Metro.

Ensure that Package:Git and dev-python/boto (package not on wiki - please add) (optional; required for EC2 support) are installed on your system:

# emerge dev-vcs/git
# emerge dev-python/boto

Next, clone the master git repository as follows:

# cd /root
# git clone git://github.com/funtoo/metro.git
# cp /root/metro/metro.conf ~/.metro

You will now have a directory called /root/metro that contains all the Metro source code.

Metro is now installed. It's time to customize it for your local system.

Configuring Metro

Note

Metro is not currently able to build Gentoo stages. See FL-901.

Daniel Robbins maintains Metro, so it comes pre-configured to successfully build Funtoo Linux releases. Before reading further, you might want to customize some basic settings like the number of concurrent jobs to fit your hardware's capabilities or the directory to use for produced stage archives. This is accomplished by editing ~/.metro which is the Metro's master configuration file.

Please note that path/install must point to where metro was installed. Point path/distfiles to where your distfiles reside. Also set path/mirror/owner and path/mirror/group to the owner and group of all the files that will be written to the build repository directory, which by default (as per the configuration file) is at /home/mirror/funtoo. The cache directory normally resides inside the temp directory -- this can be modified as desired. The cache directory can end up holding many cached .tbz2 packages, and eat up a lot of storage. You may want to place the temp directory on faster storage, for faster compile times, and place the cache directory on slower, but more plentiful storage.

.metro - Metro configuration
# Main metro configuration file - these settings need to be tailored to your install:

[section path]
install: /root/metro
tmp: /var/tmp/metro
cache: $[path/tmp]/cache
distfiles: /var/src/distfiles
work: $[path/tmp]/work/$[target/build]/$[target/name]

[section path/mirror]

: /home/mirror/funtoo
owner: root
group: repomgr
dirmode: 775

[section portage]

MAKEOPTS: auto 

[section emerge]

options: --jobs=4 --load-average=4 --keep-going=n

# This line should not be modified:
[collect $[path/install]/etc/master.conf]

Arch and Subarch

In the following example we are creating a pentium4 stage 3 compiled for x86-32bit binary compatibility. Pentium4 is a subarch of the x86-32bit architecture. Once you have metro installed you may find a full list of each subarch in your /root/metro/subarch directory each subarch will have the file extension .spec Example:

# ls /root/metro/subarch
# ls subarch/
amd64-bulldozer-pure64.spec  armv7a.spec          core-avx-i.spec         i686.spec         pentium.spec
amd64-bulldozer.spec         armv7a_hardfp.spec   core2_32.spec           k6-2.spec         pentium2.spec
amd64-k10-pure64.spec        athlon-4.spec        core2_64-pure64.spec    k6-3.spec         pentium3.spec
amd64-k10.spec               athlon-mp.spec       core2_64.spec           k6.spec           pentium4.spec
amd64-k8+sse3.spec           athlon-tbird.spec    corei7-pure64.spec      native_32.spec    pentiumpro.spec
amd64-k8+sse3_32.spec        athlon-xp.spec       corei7.spec             native_64.spec    prescott.spec
amd64-k8-pure64.spec         athlon.spec          generic_32.spec         niagara.spec      ultrasparc.spec
amd64-k8.spec                atom_32.spec         generic_64-pure64.spec  niagara2.spec     ultrasparc3.spec
amd64-k8_32.spec             atom_64-pure64.spec  generic_64.spec         nocona.spec       xen-pentium4+sse3.spec
armv5te.spec                 atom_64.spec         generic_sparcv9.spec    opteron_64.spec   xen-pentium4+sse3_64.spec
armv6j.spec                  btver1.spec          geode.spec              pentium-m.spec
armv6j_hardfp.spec           btver1_64.spec       i486.spec               pentium-mmx.spec

First stages build (local build)

To get this all started, we need to bootstrap the process by downloading an initial seed stage3 to use for building and place it in its proper location in /home/mirror/funtoo, so that Metro can find it. We will also need to create some special "control" files in /home/mirror/funtoo, which will allow Metro to understand how it is supposed to proceed.

Step 1: Set up pentium4 repository (local build)

Assuming we're following the basic steps outlined in the previous section, and building an unstable funtoo (funtoo-current) build for the pentium4, using a generic pentium4 stage3 as a seed stage, then here the first set of steps we'd perform:

# install -d /home/mirror/funtoo/funtoo-current/x86-32bit/pentium4
# install -d /home/mirror/funtoo/funtoo-current/snapshots
# cd /home/metro/mirror/funtoo/funtoo-current/x86-32bit/pentium4
# install -d 2011-12-13
# cd 2011-12-13
# wget -c http://ftp.osuosl.org/pub/funtoo/funtoo-current/x86-32bit/pentium4/2011-12-13/stage3-pentium4-funtoo-current-2011-12-13.tar.xz
# cd ..
# install -d .control/version
# echo "2011-12-13" > .control/version/stage3
# install -d .control/strategy
# echo local >  .control/strategy/build
# echo stage3 > .control/strategy/seed

OK, let's review the steps above. First, we create the directory /home/mirror/funtoo/funtoo-current/x86-32bit/pentium4, which is where Metro will expect to find unstable funtoo-current pentium4 builds -- it is configured to look here by default. Then we create a specially-named directory to house our seed x86 stage3. Again, by default, Metro expects the directory to be named this way. We enter this directory, and download our seed x86 stage3 from funtoo.org. Note that the 2010-12-24 version stamp matches. Make sure that your directory name matches the stage3 name too. Everything has been set up to match Metro's default filesystem layout.

Next, we go back to the /home/mirror/metro/funtoo-current/x86-32bit/pentium4 directory, and inside it, we create a .control directory. This directory and its subdirectories contain special files that Metro references to determine certain aspects of its behavior. The .control/version/stage3 file is used by Metro to track the most recently-built stage3 for this particular build and subarch. Metro will automatically update this file with a new version stamp after it successfully builds a new stage3. But because Metro didn't actually build this stage3, we need to set up the .control/version/stage3 file manually. This will allow Metro to find our downloaded stage3 when we set up our pentium4 build to use it as a seed. Also note that Metro will create a similar .control/version/stage1 file after it successfully builds an pentium4 funtoo-current stage1.

We also set up .control/strategy/build and .control/strategy/seed files with values of local and stage3 respectively. These files define the building strategy Metro will use when we build pentium4 funtoo-current stages. With a build strategy of local, Metro will source its seed stage from funtoo-current pentium4, the current directory. And with a seed strategy of stage3, Metro will use a stage3 as a seed, and use this seed to build a new stage1, stage2 and stage3.

Step 2: Building the pentium4 stages

Incidentally, if all you wanted to do at this point was to build a new pentium4 funtoo-current stage1/2/3 (plus openvz and vserver templates). You would begin the process by typing:

# cd /root/metro
# scripts/ezbuild.sh funtoo-current pentium4

If you have a slow machine, it could take several hours to be completed because several "heavy" components like gcc or glibc have to be recompiled in each stage. Once a stage has been successfully completed, it is placed in the "${METRO_MIRROR}/funtoo-current/x32-bit/pentium4/YYYY-MM-DD" subdirectory, where YYYY-MM-DD is today's date at the time the ezbuild.sh script was started or the date you put on the ezscript.sh command line.

Building for another binary compatible architecture (remote build)

As written above, Metro is able to perform remote build building different architecture stage3 from a binary compatible seeding stage3 (e.g. using a pentium4 stage3 to seed a Intel Core2 32bits stage3).

In the Metro terminology this is called a remote build (a stage 3 of a different, but binary compatible, architecture is used as a seed). What's not compatible? You can't use a Sparc architecture to generate an x86 or ARM based stage and vice-versa. If you use a 32bit stage then you don't want to seed a 64bit build from it. Be sure that you are using a stage from the same architecture that you are trying to seed. Check Funtoo-current FTP Mirror for a stage that is from the same Architecture that you will be building.

Note

Often, one build (ie. funtoo-current) can be used as a seed for another build such as funtoo-stable. However, hardened builds require hardened stages as seeds in order for the build to complete successfully.

Step 1: Set up Core_2 32bit repository

In this example, we're going to use this pentium4 funtoo-current stage3 to seed a new Core_2 32bit funtoo-current build. To get that done, we need to set up the pentium4 build directory as follows:

#  cd /home/mirror/funtoo/funtoo-current/x86-32bit
# install -d core2_32
# cd core2_32
# install -d .control/strategy
# echo remote > .control/strategy/build
# echo stage3 > .control/strategy/seed
# install -d .control/remote
# echo funtoo-current > .control/remote/build
# echo x86-32bit > .control/remote/arch_desc
# echo pentium4 > .control/remote/subarch

The steps we follow are similar to those we performed for a local build to set up our pentium4 directory for local build. However, note the differences. We didn't download a stage, because we are going to use the pentium4 stage to build a new Core_2 32bit stage. We also didn't create the .control/version/stage{1,3} files because Metro will create them for us after it successfully builds a new stage1 and stage3. We are still using a stage3 seed strategy, but we've set the build strategy to remote, which means that we're going to use a seed stage that's not from this particular subdirectory. Where are we going to get it from? The .control/remote directory contains this information, and lets Metro know that it should look for its seed stage3 in the /home/mirror/funtoo/funtoo-current/x86-32bit/pentium4 directory. Which one will it grab? You guessed it -- the most recently built stage3 (since our seed strategy was set to stage3) that has the version stamp of 2010-12-24, as recorded in /home/mirror/funtoo-current/x86-32bit/pentium4/.control/version/stage. Now you can see how all those control files come together to direct Metro to do the right thing.

Note

arch_desc should be set to one of: x86-32bit, x86-64bit or pure64 for PC-compatible systems. You must use a 32-bit build as a seed for other 32-bit builds, and a 64-bit build as a seed for other 64-bit builds.

Step 2: Building the Core_2 32bit stages

Now, you could start building your new Core_2 32bit stage1/2/3 (plus openvz and vserver templates) by typing the following:

# /root/metro/scripts/ezbuild.sh funtoo-current core2_32

In that case, the produced stages are placed in the /home/mirror/funtoo/funtoo-current/x32-bit/core2_32/YYYY-MM-DD subdirectory.

Step 3: The Next Build

At this point, you now have a new Core_2 32bit stage3, built using a "remote" pentium4 stage3. Once the first remote build completes successfully, metro will automatically change .control/strategy/build to be local instead of remote, so it will use the most recently-built Core_2 32bit stage3 as a seed for any new Core_2 32bit builds from now on.

Build your own tailored stage3

Metro can be easily configured for building custom stage3 by including additional packages. Edit the following configuration file /root/metro/etc/builds/funtoo-current/build.conf:

funtoo-current/build.conf
[collect ../../fslayouts/funtoo/layout.conf]

[section release]

author: Daniel Robbins <drobbins@funtoo.org>

[section target]

compression: xz

[section portage]

FEATURES: 
SYNC: $[snapshot/source/remote]
USE:

[section profile]

format: new
path: gentoo:funtoo/1.0/linux-gnu
arch: $[:path]/arch/$[target/arch_desc]
build: $[:path]/build/current
flavor: $[:path]/flavor/core
mix-ins:

[section version]

python: 2.7

[section emerge]


[section snapshot]

type: live
compression: xz

[section snapshot/source]

type: git
branch: funtoo.org
# branch to have checked out for tarball:
branch/tar: origin/master
name: ports-2012 
remote: git://github.com/funtoo/ports-2012.git
options: pull

[section metro]

options: 
options/stage: cache/package
target: gentoo

[section baselayout]

services: sshd

[section multi]

snapshot: snapshot

[section files]

motd/trailer: [

 >>> Send suggestions, improvements, bug reports relating to...

 >>> This release:                  $[release/author]
 >>> Funtoo Linux (general):        Funtoo Linux (http://www.funtoo.org)
 >>> Gentoo Linux (general):        Gentoo Linux (http://www.gentoo.org)
]

[collect ../../multi-targets/$[multi/mode:zap]]

Building Gentoo stages