Gentoo Linux Installation Guide (Advanced Optimization)

# vim: set filetype=bash  # Tell Vim to use bash syntax highlighting

# ========== System Architecture (Do not modify manually) ==========
# Default by Stage3, indicates target system architecture (Usually no need to modify)
CHOST="x86_64-pc-linux-gnu"

# ========== Compiler Optimization Parameters ==========
# -march=native    Optimize for current CPU architecture, best performance
#                  Note: Compiled programs may not run on other CPUs
# -O2              Recommended optimization level (Balances performance, stability, compilation time)
#                  Note: Avoid -O3, may cause compilation failure or runtime anomalies
# -pipe            Use pipes instead of temp files, speeds up compilation
COMMON_FLAGS="-march=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"      # C compiler options
CXXFLAGS="${COMMON_FLAGS}"    # C++ compiler options
FCFLAGS="${COMMON_FLAGS}"     # Fortran compiler options
FFLAGS="${COMMON_FLAGS}"      # Fortran 77 compiler options

# CPU Instruction Set Optimization (Auto generated, see Section 13.13 below)
# Run: emerge --ask app-portage/cpuid2cpuflags && cpuid2cpuflags >> /etc/portage/make.conf
# CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3"

# ========== Parallel Compilation Settings ==========
# MAKEOPTS: Controls parallel task count for make
#   -j<N>   Number of concurrent compilation tasks, Recommended = CPU Threads (Run nproc to check)
#   -l<N>   System load limit, prevents system overload (Optional, usually same as -j)
MAKEOPTS="-j8"  # Example: 8 Thread CPU

# Recommendation for insufficient memory:
#    16GB RAM + 8 Core CPU → MAKEOPTS="-j4 -l8"  (Halve parallel count)
#    32GB RAM + 16 Core CPU → MAKEOPTS="-j16 -l16"

# ========== Language and Localization Settings ==========
# LC_MESSAGES: Keep compilation output in English, easier for searching errors and community help
LC_MESSAGES=C

# L10N: Localization support (Affects software translation, docs, spell check etc.)
L10N="en en-US zh zh-CN zh-TW"

# LINGUAS: Legacy localization variable (Some software still depends on it)
LINGUAS="en en_US zh zh_CN zh_TW"

# ========== Mirror Settings ==========
# Taiwan Mirrors (Choose one):
#   NCHC (Taiwan): http://ftp.twaren.net/Linux/Gentoo/
GENTOO_MIRRORS="http://ftp.twaren.net/Linux/Gentoo/"

# ========== Emerge Default Options ==========
# --ask              Ask confirmation before run (Recommended keep, prevents misoperation)
# --verbose          Show detailed info (USE flag changes, dependencies etc.)
# --with-bdeps=y     Check build-time dependencies when updating (Avoid stale deps)
# --complete-graph=y Complete dependency graph analysis (Resolve complex conflicts)
EMERGE_DEFAULT_OPTS="--ask --verbose --with-bdeps=y --complete-graph=y"

# Advanced User Optional Settings (Requires sufficient memory):
#    --jobs=N           Parallel compile multiple packages (Recommended 2-4 if memory sufficient)
#    --load-average=N   System load limit (Recommended same as CPU cores)
# EMERGE_DEFAULT_OPTS="--ask --verbose --jobs=2 --load-average=8"

# ========== USE Flags (Global Feature Toggles) ==========
# Controls compilation options for all packages, affecting feature availability and dependencies
#
# System Base:
#   systemd        Use systemd init system (If using OpenRC change to -systemd)
#   udev           Modern device management (Recommended keep)
#   dbus           Inter-process communication (Required for desktop)
#   policykit      Permission management (Required for desktop)
#
# Network and Hardware:
#   networkmanager Graphical network management (Recommended for desktop)
#   bluetooth      Bluetooth support
#
# Development Tools:
#   git            Git version control (Must-have for developers)
#
# Kernel Selection:
#   dist-kernel    Use distribution default kernel (Strongly recommended for beginners)
#                  If not using this flag, need to manually configure kernel (See Chapter 7)
#
USE="systemd udev dbus policykit networkmanager bluetooth git dist-kernel"

# Common Optional USE Flags:
#   Audio: pulseaudio / pipewire (Audio server, choose one)
#   Display: wayland / X (Display protocol, required for desktop)
#   Graphics: vulkan, opengl (Modern graphics API)
#   Video: vaapi, vdpau (Hardware video acceleration)
#   Print: cups (Printing system)
#   Container: flatpak, appimage (Third-party app support)
#   Disable: -doc, -test, -examples (Save compilation time and disk space)

# ========== License Settings ==========
# ACCEPT_LICENSE: Controls allowed software license types
#
# Common Settings:
#   "*"                Accept all licenses (Recommended for beginners to avoid license blocks)
#   "@FREE"            Only Free Software (Strict open source policy)
#   "@BINARY-REDISTRIBUTABLE"  Software allowed for free binary redistribution
#   "-* @FREE"         Reject all then explicitly allow (Strictest control)
#
# Recommended Strategy:
#   - Beginner/Desktop: Use "*" to avoid license issues
#   - Open Source Purist: Use "@FREE", set individual packages if closed source needed
#   - Detailed explanation see "13.12 ACCEPT_LICENSE Details" below
ACCEPT_LICENSE="*"

# Specific package license setting (Recommended method):
#    Create /etc/portage/package.license/ directory and add config files
#    See "13.12 ACCEPT_LICENSE Details" below for example

# ========== Portage Feature Settings (Optional) ==========
# FEATURES: Activate advanced Portage features
#   parallel-fetch    Parallel download source packages (Speed up update)
#   parallel-install  Parallel install multiple packages (Experimental, maybe unstable)
#   candy             Beautify emerge output (Color progress bar)
#   ccache            Compilation cache (Requires dev-build/ccache, speeds up recompilation)
#   splitdebug        Split debug info to separate files (Save space, easier debug)
# FEATURES="parallel-fetch candy"

# ========== Compilation Log Settings (Recommended Enable) ==========
# PORTAGE_ELOG_CLASSES: Log levels to record
#   info     General info (Success messages etc.)
#   warn     Warning info (Configuration issues, deprecated operations)
#   error    Error info (Compilation failures, dependency issues)
#   log      Normal log (All output)
#   qa       QA warning (ebuild issues, security warnings)
PORTAGE_ELOG_CLASSES="warn error log qa"

# PORTAGE_ELOG_SYSTEM: Log output method
#   save          Save to /var/log/portage/elog/ (Recommended, for later review)
#   echo          Display in terminal after compilation
#   mail          Send via email (Requires mail system config)
#   syslog        Send to system log
#   custom        Custom handling script
PORTAGE_ELOG_SYSTEM="save"

# Note: File must end with empty line (POSIX standard requirement)

What is ACCEPT_LICENSE?

#

According to GLEP 23, Gentoo allows system administrators to "control the license types of software they install". ACCEPT_LICENSE variable determines which licenses Portage allows.

Why do we need this?

• Gentoo repository contains thousands of packages involving hundreds of different licenses.
• You might only want to use Free Software (OSI approved) or need to accept certain closed source licenses.
• No need to approve each license one by one —— GLEP 23 introduced License Groups.

Common License Groups

#

License groups use @ prefix to distinguish from individual licenses:

Check Current System Setting

#

portageq envvar ACCEPT_LICENSE

Output example (Default):

@FREE

This means system defaults to only allowing @FREE group software.

Set ACCEPT_LICENSE

#

Can be set in:

1. System Global Setting (/etc/portage/make.conf)

# Accept all licenses (Including closed source)
ACCEPT_LICENSE="*"

# Or: Only Free Software + Redistributable Binaries
ACCEPT_LICENSE="-* @FREE @BINARY-REDISTRIBUTABLE"

# Or: Only Free Software (Default)
ACCEPT_LICENSE="@FREE"

2. Single Package Setting (/etc/portage/package.license)

Some packages may require specific licenses (e.g. Firmware, Graphics Drivers):

mkdir -p /etc/portage/package.license

Edit /etc/portage/package.license/kernel:

# unrar tool
app-arch/unrar unRAR

# Linux Firmware (Contains non-free firmware)
sys-kernel/linux-firmware linux-fw-redistributable

# Intel Microcode
sys-firmware/intel-microcode intel-ucode

Practical Application

#

In our make.conf example, we used ACCEPT_LICENSE="*" (Accept all). If you want strict control:

1. Change make.conf to ACCEPT_LICENSE="@FREE"
2. When installing software, if blocked by license, Portage will prompt which license is needed.
3. Add exception in /etc/portage/package.license/ as needed.

Example (Installing proprietary NVIDIA driver):

The following license changes are necessary to proceed:
 x11-drivers/nvidia-drivers NVIDIA-r2

Solution:

echo "x11-drivers/nvidia-drivers NVIDIA-r2" >> /etc/portage/package.license/nvidia

CPU_FLAGS_X86 is used by Gentoo to describe "which x86 instruction sets your CPU actually supports". Some packages use it to enable (or disable) corresponding optimizations like AES, AVX, SSE4.2 etc.

• Quick Setup: Please follow Base Part 5.3.

After completion, you usually see a line in /etc/portage/make.conf:

CPU_FLAGS_X86="aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sse sse2 sse3 sse4_1 sse4_2 ssse3"

Notes

#

1. Avoid Duplicate Appends: cpuid2cpuflags >> ... appends to end of file. Remove duplicates if ran multiple times.
2. Portability: Do not copy CPU_FLAGS_X86 across different machines. Run detection on each machine.
3. Architecture Specific: Only for x86/amd64.
   • ARM/RISC-V: Do NOT set CPU_FLAGS_X86. Refer to Wiki for corresponding flags.

Edit /etc/fstab, add the following line (size recommended to be half of memory, e.g. 16G):

tmpfs   /var/tmp/portage   tmpfs   size=16G,uid=portage,gid=portage,mode=775,noatime   0 0

Mount directory:

mount /var/tmp/portage

1. Create config directories:

   mkdir -p /etc/portage/env
   mkdir -p /var/tmp/notmpfs
   

2. Create notmpfs.conf:

   echo 'PORTAGE_TMPDIR="/var/tmp/notmpfs"' > /etc/portage/env/notmpfs.conf
   

3. Apply config to specific software: Edit /etc/portage/package.env (Create file if it is a directory):

   vim /etc/portage/package.env
   

   Write:

   www-client/chromium notmpfs.conf
   app-office/libreoffice notmpfs.conf
   dev-qt/qtwebengine notmpfs.conf
   

Some packages are known to be incompatible with LTO. Create /etc/portage/env/nolto.conf:

# Disable LTO and related warnings
DISABLE_LTO="-Wno-error=odr -Wno-error=lto-type-mismatch -Wno-error=strict-aliasing -fno-lto"
CFLAGS="${CFLAGS} ${DISABLE_LTO}"
CXXFLAGS="${CXXFLAGS} ${DISABLE_LTO}"
FCFLAGS="${FCFLAGS} ${DISABLE_LTO}"
FFLAGS="${FFLAGS} ${DISABLE_LTO}"
LDFLAGS="${LDFLAGS} ${DISABLE_LTO}"

Create /etc/portage/package.env/no-lto:

# Packages incompatible with LTO
# Still use Clang but disable LTO

app-misc/jq no-lto.conf
app-shells/zsh no-lto.conf
dev-build/ninja no-lto.conf
dev-cpp/abseil-cpp no-lto.conf
# ... (Add more packages as needed)
x11-drivers/nvidia-drivers no-lto.conf

Create /etc/portage/env/low-memory.conf:

# Reduce parallel tasks
MAKEOPTS="-j4"
COMMON_FLAGS="-O2 -pipe"

Create /etc/portage/package.env/low-memory:

# Browsers
www-client/chromium low-memory.conf
# Large projects
dev-lang/rust low-memory.conf

Enable in menuconfig:

General setup
  → Compiler optimization level
     → [*] Optimize for performance (-O2)  # Or -O3, but may be unstable

  → Link Time Optimization (LTO)
     → [*] Clang ThinLTO                   # Requires LLVM=1

Kernel hacking
  → Compile-time checks and compiler options
     → [*] Optimize harder

Kernel Compression (Affects boot speed and size):

General setup
  → Kernel compression mode
     → [*] ZSTD  # Recommended: High compression ratio and fast decompression
     # Others: LZ4 (Fastest), XZ (Smallest), GZIP (Best compatibility)

Error 1: Missing Dependency

*** No rule to make target 'debian/canonical-certs.pem'

Solution: Disable signing keys

scripts/config --disable SYSTEM_TRUSTED_KEYS
scripts/config --disable SYSTEM_REVOCATION_KEYS
make olddefconfig

Error 2: LTO Compilation Fail

ld.lld: error: undefined symbol

Solution: Some modules usually incompatible with LTO, disable LTO or set problematic module to =y (instead of =m)

Error 3: Clang version too old

error: unknown argument: '-mretpoline-external-thunk'

Solution: Upgrade LLVM/Clang or use GCC

1. Enable mdraid support Create /etc/dracut.conf.d/mdraid.conf:

# Enable mdraid support for RAID arrays
add_dracutmodules+=" mdraid "
mdadmconf="yes"

2. Force Load RAID Drivers Create /etc/dracut.conf.d/raid-modules.conf:

# Ensure RAID modules are included and loaded
add_drivers+=" raid1 raid0 raid10 raid456 "
force_drivers+=" raid1 "
# Install modprobe configuration
install_items+=" /usr/lib/modules-load.d/ /etc/modules-load.d/ "

3. Configure Kernel Command Line (UUID) Need to find RAID UUID and add to kernel args. Create /etc/dracut.conf.d/mdraid-cmdline.conf:

# Kernel command line parameters for RAID arrays
# Replace with your actual RAID UUID (Check via mdadm --detail --scan)
kernel_cmdline="rd.md.uuid=68b53b0a:c6bd2ca0:caed4380:1cd75aeb rd.md.uuid=c8f92d69:59d61271:e8ffa815:063390ed"

4. Regenerate initramfs

dracut --force

Setup Mode allows modifying Secure Boot keys. If Disabled:

Method 1: Clear existing keys (Recommended) In BIOS/UEFI settings find:

• Clear Secure Boot Keys
• Reset to Setup Mode
• Delete All Keys

Verify Setup Mode Reboot and check again:

sbctl status

Confirm Setup Mode: ✘ Enabled.

18.2.1 Generate Self-Signed Cert

#

Step 1: Install tools

emerge --ask app-crypt/sbsigntools sys-apps/kmod[openssl]

Step 2: Generate Certs

mkdir -p /etc/kernel/certs
cd /etc/kernel/certs

# Generate Private Key
openssl req -new -x509 -newkey rsa:2048 -keyout MOK.key -out MOK.crt \
  -days 36500 -nodes -subj "/CN=My Kernel Signing Key/"

# Convert to DER
openssl x509 -in MOK.crt -outform DER -out MOK.der

# Permissions
chmod 600 MOK.key

18.2.2 Configure Kernel Module Signing

#

Step 1: Enable Support /etc/portage/package.use/kernel:

virtual/dist-kernel modules-sign
sys-kernel/installkernel dracut

Step 2: Configure Paths /etc/portage/make.conf:

MODULES_SIGN_KEY="/etc/kernel/certs/MOK.key"
MODULES_SIGN_CERT="/etc/kernel/certs/MOK.der"
MODULES_SIGN_HASH="sha512"

Step 3: Recompile

emerge --ask @module-rebuild
emerge --ask sys-kernel/gentoo-kernel-bin

18.2.4 Enroll MOK (Machine Owner Key)

#

Step 1: Install Shim

emerge --ask sys-boot/shim

Step 2: Copy Shim

cp /usr/share/shim/shimx64.efi /efi/EFI/gentoo/
cp /usr/share/shim/mmx64.efi /efi/EFI/gentoo/

Step 3: Import Cert

mokutil --import /etc/kernel/certs/MOK.der

Set temporary password.

Step 4: Create Boot Entry Use efibootmgr to point to shimx64.efi.

Step 5: Reboot and Enroll In MOK Manager (Blue screen after reboot): Enroll MOK → Continue → Yes → Enter password → Reboot.