The Funtoo Linux project has transitioned to "Hobby Mode" and this wiki is now read-only.
Funtoo:Metro/Initial Setup
Funtoo:Metro/AutoSetup
The autosetup script provides a fast and convenient way of quickly setting up the metro build repository with a seed stage so that it is ready to start a metro build.
It is recommended to work from a container or an fchroot environment. If you'd like to use a container, please follow the steps found at LXD to set up an lxd container from a Funtoo image. Or you can just use an fchroot environment, following the instructions.
If you are using an LXD container to build a stage tarball for an architecture incompatible with the host, you need to make sure that your LXD setup supports that architecture or the build will fail.
Setting up an fchroot Environment
Installing sys-apps/fchroot
Funtoo offers a convenient tool called sys-apps/fchroot
to work in chroot environments, which will take care of any mounts you need to set up and also setting up the network within the chroot environment. Fchroot actually goes well beyond what a regular chroot can do (see Frankenchroot). In order to install it, just emerge the package:
root # emerge -av sys-apps/fchroot
Downloading the latest stage3 tarball
Choose a stage3 tarball from https://build.funtoo.org. The "Next release" x86-64bit generic build is a good choice in most cases:
user $ wget https://build.funtoo.org/next/x86-64bit/generic_64/2022-09-13/stage3-generic_64-next-2022-09-13.tar.xz
Then, create a directory and unpack the tarball into it:
user $ mkdir metro-chroot user $ tar xJpvf stage3-generic_64-next-2022-09-13.tar.xz -C metro-chroot
Entering and setting up the fchroot enviroment
By using Funtoo's sys-apps/fchroot
, you don't need to worry about mounting filesystems and setting up the network before chrooting. That will be done automatically for you. All you need to do after you entered the environment is to create a meta repository using ego sync
:
root # fchroot metro-chroot/ fchroot # ego sync
Getting the necessary software
You will need git to clone Metro and some Python modules used by the scripts. If you are working from a stage3 tarball fchroot environment, dev-vcs/git
and dev-python/requests
are already provided for you. Please make sure you have the following packages installed in your system:
fchroot # emerge -av dev-vcs/git fchroot # emerge -av dev-python/lxml fchroot # 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.
fchroot # cd /root fchroot # 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:
fchroot # cp /root/metro/metro.conf /root/.metro
If you wish to tweak the settings then you should manually copy /path/to/metro/metro.conf to /root/.metro and edit accordingly (see Configuring_Metro).
Now your system is ready to run Metro's automatic setup tool, which will take care of the rest of the preparation.
Automatically setting up your build
Before you can start building your stage tarballs, you need to set up an independent ego
, cloned from the git repository, install app-emulation/qemu
with the correct USE flags for the architecture for which you are building the tarball.
These steps are done automatically by the setup
script:
fchroot # /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
.www.funtoo.org / funtoo / next 1. arm-64bit 2. riscv-64bit 3. x86-64bit .
Selecting a Subarchitecture
.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
Building a new release
In the example above, a "next x86-64bit generic_64" build has been set up to build a new Gnome stage3 tarball using an existing stage3 tarball downloaded from https://build.funtoo.org. If your satisfied with that, you can just go ahead and run the command as suggested:
fchroot # /root/metro/scripts/ezbuild.sh next x86-64bit generic_64 freshen+gnome
Otherwise, continue reading to learn how to create a stage3 tarball with different specs.
The first 3 arguments in the example above: 'next', 'x86-64bit' and 'intel64-ivybridge' correspond to the options chosen using the setup script. If you'd like to run ezbuild.sh
for a different release, architecture or subarchitecture, 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 spec for your stage tarball.
Checking the logs
ezbuild.sh
is very quiet. If you were expecting it to give 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
.
fchroot # 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 chose “freshen+gnome”, so we can expect to find stage3-freshen.txt
and gnome.txt
.
If you'd like to know all the targets that are selected for that build, you can check the file .targets
at (in our example):
fchroot # 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, a fully new stage3 tarball, completely built from sources.
Build Targets
You can create different flavors of stage3, 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. You can find the available targets 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.
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
normally:
root # /home/root/metro/scripts/ezbuild.sh next x86-64bit intel64-ivybridge freshen+gnome
When you want 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.
When you want to go back, just restore your session:
root # screen -T ${TERM} -r Metro
Where is my Stage Tarball?
When the build completes, 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:
fchroot # ls /home/mirror/funtoo/next/x86-64bit/intel64-skylake/2022-10-08/
Where to Go From Here
Alternatively, you can set up a buildbot to do it:
root #