Set up Gentoo

abstract: Gentoo is a source code metadistribution. So there are many possible Gentoos, But this is about sticking to the distribution kernel, UEFI, systemd, and grub, which narrows the possibilities to something manageable. Gentoo does not source build out of the box.

emerge –ask –verbose –update –deep –changed-use @world fails after compiling an enormous amount of code with a completely cryptic error message – pesumably because it will only run successfuly if no end of USE flags are correctly set and no end of packages previously emerged.

What are the USE flags and packages one must emerge so that emerge @world builds the same or similar system as
stage3-amd64-desktop-systemd-20250608T165347Z.tar.xz

That stage was built with bindist, and I strongly suspect that it cannot be built without bindist, that gentoo has lost its source code roots beyond practical recovery.

Presumably the binary distribution works,if one specifies the appropriate hardware in /etc/portage/binrepos.conf (except that I have no idea how one would specify the particular hardware, and the explanation given is cryptic and explains nothing) but the flags that would lead to the stage file being locally built are nowhere explained, nor are they the defaults.

When one attempts to install emerge sys-kernel/linux-firmware it demands a vast number of USE flags, whose options are unclear, and whose relevance to the my hardware is unknown and unexplained.

I surely don’t need to install most of these on an old and utterly vanilla system. Perhap I don’t need to install any of them. But it demands use flags be set or cleared for every redistributable package, some of which must be irrelevant to me, perhaps all of which are irrelevant to me.

I suspect that the kernel can only be built with the redistributable firmware, and the redistributable firmware can only be installed on one particular machine, that no one now knows how to reproduce.

Obviously some redistributable software assumes the presence of hardware, and other redstribable software assumes the presence of other hardware that cannot co-exist on a single machine, so having a single redistributable package to emerge makes no sense.

UEFI requires firmware. Firmware install does not work.

My attempt to build gentoo failed, possibly because the dist-kernel requires non free hardware drivers. The error message was an unintelligble “error 37”

Also compiling the dist kernel requires at least 20GB disk space, and maybe considerably more.

Unfortunately the Gentoo install pages are written by and for people who compile the kernel from source every day, and create new and unique Gentoo systems every few days, and are difficult to comprehend for other people.

Further they mostly discuss no end of variations, making it difficult for people to tease the standard path from all the other information

1 Outline of the process.

You format the target system with appropriate partitions and file systems. In the case of an UEFI system, a small efi partition a swap partition, and the rest is the root partition.

Then you untar the stage file to the root of the target root position and chroot into the target, so you now have a good simulation of being in the running linux system that you are in fact creating.

You then set up all the use flags that will tell the emerge packet manager what source files to download and what flags it will use to build them, to compile the real linux system on top of your simulated system, in the same way you would rebuild it as if it was already live, and reconfigure it in the same way you would reconfigure it if already live.

2 Installing firmware

The firmware files are needed for the kernel, for initramfs and efi

And they expect dracut, but we need to persuade them to accept gentoo

emerge sys-kernel/linux-firmware
emerge sys-firmware/sof-firmware

3 Installing the stage files

3.1 Boot the livecd

Which, this being gentoo, simply drops you into the command line as root and leaves you with no guidance.

Also, no ability to copy and paste, so you want to ssh in from another system. It is obvious that the people writing the instructions were not booting the livecd, but building a target linux system from their daily driver.

On the livecd system

passwd root
dogs
dogs
rc-service sshd start

to ssh in from your more useful system, first clear livecd out of ~/.ssh/known_hosts then

ssh root@livecd

mount /dev/sda3 /mnt/gentoo
mkswap /dev/sda2
mkdir --parents /mnt/gentoo/boot/efi
mount /dev/sda1 /mnt/gentoo/boot/efi

Mounts are global, affecting the livecd system and all the ssh sessions.

3.2 Install the stage files

In another terminal session on your more useful system scp ~/vms/installs/stage3-amd64-desktop-systemd-20250608T165347Z.tar.xz root@livecd:/mnt/gentoo

Back to the ssh session in which you mounted these file systems

cd /mnt/gentoo
tar -xvf stage*.xz

Now you have a good imitation of the file system of a real linux system.

3.3 setup target linux for chroot

Mount the livecd fake file systems from livecd into the imitation system.

cp -f --dereference /etc/resolv.conf /mnt/gentoo/etc/
mount --types proc /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --bind /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run

3.4 and now you can chroot in

chroot /mnt/gentoo /bin/bash

# you cannot paste chroot and subsequent commands in one block
# or the subsequent commands get applied to the rooted environment
# instead of the chrooted environment
source /etc/profile
export PS1="(chroot) ${PS1}"
alias ll="ls -hal"

And now our fake linux system can run the same software as the real one.

3.5 initialise emerge

# initialise the emerge source package manager
emerge-webrsync
# select the profile to be built, which will
# guide what emerge downloads and builds
eselect profile list
eselect profile set 24
# eselect profile set default/linux/amd64/17.1/desktop/systemd
eselect profile show

3.6 locales

ls -l /usr/share/zoneinfo
ls -l /usr/share/zoneinfo/Asia

ls -l /etc/localtime  # Should point to a valid timezone
# do not use GMT* timezones
ln -sf ../usr/share/zoneinfo/Asia/Singapore /etc/localtime  # Recreate if needed
nano /etc/locale.gen
locale-gen
locale -a
eselect locale list
eselect locale set en_US.utf8
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

3.7 and now start intializing the USE flags

nano /etc/portage/make.conf

# These settings were set by the catalyst build script that automatically
# built this stage.
# Please consult /usr/share/portage/config/make.conf.example for a more
# detailed example.
COMMON_FLAGS="-O2 -pipe"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"

# NOTE: This stage was built with the bindist USE flag enabled

# This sets the language of build output to English.
# Please keep this setting intact when reporting bugs.
LC_MESSAGES=C.utf8

RUSTFLAGS="${RUSTFLAGS} -C target-cpu=native"
ACCEPT_LICENSE="-* @FREE @BINARY-REDISTRIBUTABLE"
USE="
    efi
    dist-kernel   # to stop you from unintentionally doing all the weirdness gentoo allows
    systemd       # Required for systemd integration
    X             # X11 support (XFCE is X11-based)
    elogind       # Session management (optional but useful)
    udisks        # Auto-mount USB drives in Thunar
    dbus          # Required for systemd/XFCE communication
    policykit     # Privilege elevation (e.g., mounting disks)
    networkmanager # GUI networking (recommended for desktops)
    -consolekit   # Disable (conflicts with systemd/elogind)
    -wayland      # Wayland is evil, and whatsoever links to it is broken
    pulseaudio   # Sound system
    alsa         # ALSA audio support
    dbus         # IPC for desktop apps
    -bluetooth    # Bluetooth support
    -wifi         # Wi-Fi support
    "

3.8 fstab

lsblk -o name,type,size,fstype,mountpoint,UUID
nano /etc/kernel/cmdline

root=UUID=5ad053f8-9b4b-4088-a9f4-9a6a0b9aa8b5 rootfstype=ext4 noresume

mkdir -p /media/cdrom0
nano /etc/fstab

# /etc/fstab: static file system information.
#
# See the manpage fstab(5) for more information.
#
# NOTE: The root filesystem should have a pass number of either 0 or 1.
#       All other filesystems should have a pass number of 0 or greater than 1.
#
# NOTE: Even though we list ext4 as the type here, it will work with ext2/ext3
#       filesystems.  This just tells the kernel to use the ext4 driver.
#
# NOTE: You can use full paths to devices like /dev/sda3, but it is often
#       more reliable to use filesystem labels or UUIDs. See your filesystem
#       documentation for details on setting a label. To obtain the UUID, use
#       the blkid(8) command.
# <file system>                             <mount point>   <type>  <options>           <dump>  <pass>
# /boot/efi was on /dev/sda1 during installation
UUID=7A16-B37A                              /boot/efi       vfat    umask=0077          0       1
# swap was on /dev/sda2 during installation
UUID=51952fce-186c-430c-8539-8aebd06626fd   none            swap    sw                  0       0
# / was on /dev/sda3 during installation
UUID=5ad053f8-9b4b-4088-a9f4-9a6a0b9aa8b5   /               ext4    errors=remount-ro   0       1
/dev/sr0                    /media/cdrom0       udf,iso9660 users,auto,nofail   0       0

3.9 grub

nano /etc/portage/package.use/sys-boot/grub

LUKS="no"   No include LUKS (encryption) support.   Required for /dev/mapper unlocking.
LVM="no"    No include LVM (Logical Volume Manager).    Needed if using LVM volumes.
DISKLABEL="yes" Include GPT/UUID tools. Helps with /dev/disk/by-uuid.
# MODULES_OVERRIDE="nvme ahci"  Force-add kernel modules.   Ensures NVMe/SATA drivers are included.
SYMLINK="yes"   Symlink /boot/vmlinuz to latest kernel. Simplifies GRUB config.

/etc/portage/package.use/sys-kernel/gentoo-kernel initramfs firmware /etc/portage/package.use/sys-boot/grub grub_platforms_efi-64

3.10 genkernel

nano /etc/genkernel.conf

LUKS="no"   No include LUKS (encryption) support.   Required for /dev/mapper unlocking.
LVM="no"    No include LVM (Logical Volume Manager).    Needed if using LVM volumes.
DISKLABEL="yes" Include GPT/UUID tools. Helps with /dev/disk/by-uuid.
# MODULES_OVERRIDE="nvme ahci"  Force-add kernel modules.   Ensures NVMe/SATA drivers are included.
SYMLINK="yes"   Symlink /boot/vmlinuz to latest kernel. Simplifies GRUB config.

nano /etc/portage/package.use/sys-kernel/genkernel

firmware uefi

nano /etc/portage/package.use/sys-kernel/installkernel

genkernel

And then you should be able to

emerge sys-kernel/linux-firmware
emerge sys-firmware/sof-firmware

Without it bellyaching about use flags.

3.11 dracut

Dracut is not required to build the stage3-desktop-systemd configuration.

genkernel is simpler

On the other hand, dracut has the great advantage of not being gentoo specific.

nano etc/dracut.conf

add_dracutmodules+=" systemd "      #will this fail if we do not first emerge systemd?
add_drivers+=" ahci nvme virtio_scsi "  # Include disk drivers
hostonly="no"  # Include all drivers (safer for desktops)
kernel_cmdline="/etc/kernel/cmdline"

nano  /etc/portage/package.use/installkernel

sys-kernel/installkernel grub dracut

3.12 building

# find if your use flags are stupid
emerge --info
emerge -av sys-apps/systemd
# save before sof firmware, who knows the consequences?
emerge -av sys-firmware/sof-firmware

emerge -av
    sys-kernel/gentoo-kernel \
    sys-kernel/installkernel \
    sys-fs/udev \
    net-misc/networkmanager \
    x11-base/xorg-server \
    x11-wm/xfce4-meta \
    media-sound/pulseaudio \
    sys-power/acpid \
    app-admin/eselect \
    sys-apps/dbus \
    sys-kernel/genkernel \
    sys-firmware/sof-firmware

emerge --sync

emerge -avuDN @world
qlist -Iv  # List installed packages

df -h .
emerge --depclean

emerge -av lightdm  # XFC
emerge net-misc/openssh
systemctl enable NetworkManager
systemctl enable lightdm
systemctl enable sshd

4 Grub

Make sure /boot/efi points to the expected location (because using grub)

emerge -av sys-kernel/genkernel sys-boot/grub

genkernel --install --symlink --no-lvm --no-luks all
#--install  Installs kernel/initramfs to /boot.
#--symlink  Updates /boot/vmlinuz symlink.
#--no-lvm --no-luks Explicitly skips LVM/LUKS (not needed).
# all   Builds kernel + initramfs.
#Expected files in boot:
#   vmlinuz-* (kernel)
#   initramfs-*.img

grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Gentoo
#Expected files in efi:
#   /boot/efi/EFI/Gentoo/grubx64.efi (GRUB EFI binary)

grub-mkconfig -o /boot/grub/grub.cfg
# /boot/grub/grub.cfg should have the correct UUID and the correct initramfs
reboot