Funtoo:Metro/Initial Setup

Getting the necessary software

You will need git to clone Metro and some Python modules used by the scripts. Please make sure you have the following packages installed in your system:

root # emerge -av dev-vcs/git
root # emerge -av dev-python/lxml
root # emerge -av dev-python/requests

Cloning and configuring Metro

You can get the latest version of Metro from the git repository using git. Soon, it will also be available as an ebuild on your meta repository.

root # cd /root
root # git clone https://code.funtoo.org/bitbucket/scm/core/metro.git

Configuring Metro

The default options for metro are usually fine for most cases. If you are happy with the defaults, just copy the default configuration file to /root/.metro:

root # cp /root/metro/metro.conf /root/.metro

If you wish to tweak the settings then you should edit /root/.metro accordingly (see Configuring_Metro) to learn how to do that.

Now your system is ready to run Metro's automatic setup tool, which will take care of the rest of the preparation.

Setting up your build

Before you can start building your stage tarballs, an independent ego cloned from the git repository needs to be set up, and app-emulation/qemu needs to be installed with the correct USE flags for the architecture for which you are building the tarball.

These steps are done automatically by the setup script:

root # /root/metro/scripts/setup

Selecting a release

You can build a stage tarball for any of the available Funtoo releases. Currently, these are the only releases available:

.www.funtoo.org / funtoo

   1. 1.4-release-std
   2. next




















.

Selecting an Architecture

Choose a general architecture from the menu. You'll have a chance to choose a more specific sub-architecture in the next step.

.www.funtoo.org / funtoo / next


   1. arm-64bit
   2. riscv-64bit
   3. x86-64bit




















.

Selecting a Sub-Architecture

Choose the specific sub-architecture you wish to build your stage tarball for.

.www.funtoo.org / funtoo / next / x86-64bit

   1. amd64-bulldozer
   2. amd64-excavator
   3. amd64-k10
   4. amd64-piledriver
   5. amd64-steamroller
   6. amd64-zen
   7. amd64-zen2
   8. amd64-zen3
   9. core2_64
  10. generic_64
  11. intel64-broadwell
  12. intel64-haswell
  13. intel64-ivybridge
  14. intel64-nehalem
  15. intel64-sandybridge
  16. intel64-silvermont
  17. intel64-skylake
  18. intel64-westmere


.

Wait for the Setup to Complete

The setup script will go through several steps to set up your build. If you are running it for the first time, these can include creating a new meta repository, installing supporting software and downloading a tarball, so it may take some time to complete.

Here is a sample output:

Created file /home/mirror/funtoo/next/x86-64bit/generic_64/.control/strategy/build with contents 'local'
Created file /home/mirror/funtoo/next/x86-64bit/generic_64/.control/strategy/seed with contents 'stage3'
Created file /home/mirror/funtoo/next/x86-64bit/generic_64/.control/version/stage3 with contents '2022-09-13'
--2022-10-09 08:06:24--  https://build.funtoo.org/next/x86-64bit/generic_64/2022-09-13/stage3-generic_64-next-2022-09-13.tar.xz
Resolving build.funtoo.org... 89.187.187.14, 89.187.187.12, 89.187.187.19, ...
Connecting to build.funtoo.org[89.187.187.14]:443... connected.
 
HTTP request sent, awaiting response... 200 OK
Length: 701542432 (669M) [application/octet-stream]
Saving to: ‘/home/mirror/funtoo/next/x86-64bit/generic_64/2022-09-13/stage3-generic_64-next-2022-09-13.tar.xz’
 
funtoo/next/x86-64bit/g  100%[==================================================>] 669.04M  95.5MB/s    in 7.3s
 
2022-10-09 08:06:32 (92.0 MB/s) - ‘/home/mirror/funtoo/next/x86-64bit/generic_64/2022-09-13/stage3-generic_64-next-2022-09-13.tar.xz’ saved [701542432/701542432]
 
Cloning into '/root/ego'...
remote: Enumerating objects: 3385, done.
remote: Counting objects: 100% (3385/3385), done.
remote: Compressing objects: 100% (1382/1382), done.
remote: Total 3385 (delta 2093), reused 2902 (delta 1727), pack-reused 0
Receiving objects: 100% (3385/3385), 760.96 KiB [ 27.18 MiB/s, done.
Resolving deltas: 100% (2093/2093), done.
 
Metro build for release next, x86-64bit, generic_64 has been initialized.
To build a new release, use ezbuild (or set up buildbot):
 
 scripts/ezbuild.sh next x86-64bit generic_64 freshen+gnome

Building a new release

In the example above, a "next x86-64bit generic_64" build has been set up to build a new Gnome stage4 tarball on top of an existing stage3 tarball downloaded from https://build.funtoo.org. If you're satisfied with those settings, you can just go ahead and run the command as suggested:

root # /root/metro/scripts/ezbuild.sh next x86-64bit generic_64 freshen+gnome

Otherwise, continue reading to learn how to create a stage3 or stage4 tarball with different specs.

The first 3 arguments in the example above: 'next', 'x86-64bit' and 'intel64-ivybridge' correspond to the options you chose when you ran the setup script. If you'd like to run ezbuild.sh for a different release, architecture or sub-architecture, you need to run the setup script again with the appropriate options.

The 4th argument corresponds to a combination of the stages to build + the target specs for your stage tarball.

Checking the logs

The ezbuild.sh script is very quiet. If you were expecting to get a lot of output like a usual emerge session, it may look like your computer froze. You can check what ezbuild.sh is doing by watching the logs, which can be found in a path with the following structure: /home/mirror/funtoo/<release>/<arch>/<subarch>/<date>/log/<stage>-<target>.txt.

root # tail -f /home/mirror/funtoo/next/x86-64bit/intel64-skylake/2022-10-08/log/stage3-freshen.txt

Under the same directory, you will find a log file for every spec file involved in the build you chose. In the case of the example above, we had chosen “freshen+gnome”, so we can expect to find stage3-freshen.txt and gnome.txt.

If you'd like to know all the targets that were selected for your build, check the file .targets at (in our example):

root # cat /home/mirror/funtoo/next/x86-64bit/intel64-skylake/2022-10-08/.targets

Choosing a Target

Stages to Build

There are 2 options for this argument: 'freshen' and 'full'.

“Freshen” will basically run a @world update on an existing stage3 tarball to generate a fresh, updated version of the same tarball.

“Full” will build a stage3 from scratch, starting by building a stage1, then a stage2 and finally, from that, an entirely new stage3 tarball, completely built from source.

Build Targets

You can create different flavors of a stage3 or stage4, with the software and settings necessary for different purposes. For example, a Gnome Desktop stage3 tarball, an LXD container image, an OpenVZ container image, etc. The available targets can be found at /root/metro/targets/gentoo. You can also create your custom targets. See Metro Data Model to learn how to do that.

Using Gnu Screen

Depending on the arguments you passed to ezbuild.sh, the build process may take several hours to complete.

If you are running ezbuild.sh from another machine through an ssh session, you might want to use a terminal multiplexer like app-misc/tmux or app-misc/screen, which will allow you to close the terminal and even log out from the remote machine machine. Here is how you can do it using Gnu Screen:

Emerging app-misc/screen:

root # emerge -av app-misc/screen

Running app-misc/screen:

root # screen -T ${TERM} -S Metro

This will open a screen session where you can run ezbuild.sh:

root # /home/root/metro/scripts/ezbuild.sh next x86-64bit intel64-ivybridge freshen+gnome

Now, if you'd like to leave the terminal, just press Ctrl+A and then Ctrl+D to detach the screen session. Once you've detached, you are free to leave you ssh session and/or close your terminal. The script will keep running inside the detached session.

When you want to go back, log back in if you are working from a remote host and just restore your session:

root # screen -T ${TERM} -r Metro

Where is my Stage Tarball?

When the build completes, by default the stage tarball can be found in a path with the following structure: /home/mirror/funtoo/<release>/<arch>/<subarch>/<date>/. In our example, it will be found at:

root # ls /home/mirror/funtoo/next/x86-64bit/intel64-skylake/2022-10-08/

If you'd like your tarballs to go elsewhere, you can change your configuration in {{f|/root/.metro} (see Configuring Metro).

Where to Go From Here

Additional Architectures

The automatic setup script doesn't offer all the possible architectures you could be building a stage tarball for. Read the instructions on Manual Setup to learn how to set up a build for any of the supported platforms. In theory, you can actually set up Metro to build a stage tarball for any platform supported by the GCC (and QEMU, if it's the target platform is different from the host platform).

Custom Targets

Study Metro Data Model to learn how to create new custom targets, which you can then use for your own customized builds.

Automation (Buildbots)

You can set up multiple builds and have Metro automatically build each one of them or just refresh the ones that are outdated. Read the instructions at Automation to learn how to do that.