Add extra documentation

gentoo-2024.8/gentoo.txt

@@ -1,5 +1,13 @@
 # vim:set ft=sh:
 
+# Overview of bootstrap:
+# step 0: Build live-bootstrap as a starting point
+# step 1: Update python, install portage and extra dependencies for later stages
+# step 2: Create an x86_64 cross-toolchain in /cross
+# step 3: Cross-compile a minimal x86_64 system in /gentoo
+# step 4: Boot into the final system and finish installation
+
+# Build live-bootstrap
 git clone -b 1.0 --depth=1 --recursive https://github.com/fosslinux/live-bootstrap
 cd live-bootstrap
 ./rootfs.py -c --external-sources --cores $(nproc)
@@ -12,10 +20,7 @@ env -i chroot target bzip2 -9v /target.tar
 mv target/external/repo .
 mv target/target.tar.bz2 .
 
-# Goal:
-# install cross compiler in /cross
-# cross compiled system in /gentoo
-
+# Chroot into the live-bootstrap system
 cd target
 mount -t proc proc proc
 mount -t sysfs sysfs sys
@@ -30,6 +35,7 @@ curl -LO http://distfiles.gentoo.org/snapshots/squashfs/gentoo-20240801.xz.sqfs
 curl -LO https://github.com/plougher/squashfs-tools/archive/refs/tags/4.6.1/squashfs-tools-4.6.1.tar.gz
 cd /tmp
 
+# This patch avoids using the _ctypes module in portage
 cat > portage.patch << 'EOF'
 +++ b/lib/portage/util/compression_probe.py
 @@ -1,13 +1,13 @@
@@ -58,6 +64,7 @@ cat > portage.patch << 'EOF'
  }
 EOF
 
+# Build squashfs-tools to extract the ::gentoo tree
 tar xf /var/cache/distfiles/squashfs-tools-4.6.1.tar.gz
 cd squashfs-tools-4.6.1
 make -C squashfs-tools install \
@@ -66,21 +73,24 @@ make -C squashfs-tools install \
 cd ..
 rm -rf squashfs-tools-4.6.1
 
+# Unpack the ::gentoo tree
 unsquashfs /var/cache/distfiles/gentoo-20240801.xz.sqfs
 mkdir -p /var/db/repos
 rm -rf /var/db/repos/gentoo
 mv squashfs-root /var/db/repos/gentoo
 
+# Install temporary copy of portage
 tar xf /var/cache/distfiles/portage-3.0.65.tar.bz2
 cd portage-3.0.65
 patch -p1 -i ../portage.patch
 cd ..
 ln -sf portage-3.0.65 portage
 
-# Configure portage
+# Add portage user/group
 echo 'portage:x:250:250:portage:/var/tmp/portage:/bin/false' >> /etc/passwd
 echo 'portage::250:portage' >> /etc/group
 
+# Configure portage
 mkdir -p /etc/portage/make.profile
 cat > /etc/portage/make.profile/make.defaults << 'EOF'
 FEATURES="-news -sandbox -usersandbox -pid-sandbox -parallel-fetch"
@@ -210,7 +220,7 @@ exec pkg-config "$@"
 EOF
 chmod +x /cross/usr/bin/x86_64-bootstrap-linux-gnu-pkg-config
 
-# Compile final system (hopefully)
+# Configure cross-compilation for final system
 mkdir -p /gentoo.cfg/etc/portage
 ln -sf ../../../var/db/repos/gentoo/profiles/default/linux/amd64/23.0 /gentoo.cfg/etc/portage/make.profile
 cat > /gentoo.cfg/etc/portage/make.conf << 'EOF'
@@ -230,6 +240,7 @@ ac_cv_file__dev_ptc=no
 fi
 EOF
 
+# Cross-compile just enough to build everything
 py=$(PORTAGE_CONFIGROOT=/gentoo.cfg portageq envvar PYTHON_SINGLE_TARGET | sed 's/^python//;s/_/./g')
 PORTAGE_CONFIGROOT=/gentoo.cfg ROOT=/gentoo SYSROOT=/gentoo emerge -O1n \
     sys-apps/baselayout \
@@ -282,11 +293,12 @@ ln -sf ../../var/db/repos/gentoo/profiles/default/linux/amd64/23.0 /gentoo/etc/p
 echo 'nameserver 1.1.1.1' > /gentoo/etc/resolv.conf
 echo 'C.UTF8 UTF-8' > /gentoo/etc/locale.gen
 
-# Copy repo
+# Copy ::gentoo repo
 rsync -aP /var/db/repos/ /gentoo/var/db/repos
 
-# From here you just chroot into /gentoo, and run "emerge -e @world", untangling dependencies until it works
-# This is an example:
+# This is the point where you have to move from the x86 system to the x86_64 system.
+# Make sure that you are running a x86_64 kernel before chrooting, or booting it.
+
 cd /gentoo
 mount -t proc proc proc
 mount -t sysfs sysfs sys
@@ -316,7 +328,7 @@ emerge -1 sys-devel/binutils
 emerge -o sys-devel/gcc
 EXTRA_ECONF=--disable-bootstrap emerge -O1 sys-devel/gcc
 emerge -1 $(portageq expand_virtual / virtual/libc)
-emerge -1 dev-lang/perl
+emerge -1 dev-lang/perl  # https://bugs.gentoo.org/937918
 
 # Rebuild everything (stage3)
 USE='-filecaps -http2' emerge -e @system