Gentoo for Banana Pi

Summary

Gentoo on ARM single-board computers provides maximum flexibility through source-based package management, but requires careful attention to build configuration, thermal management, and storage space. This page covers stage3 installation, USE flag optimization for ARM hardware, kernel compilation on limited resources, and troubleshooting common build failures. Most issues stem from insufficient cooling during long compiles, inadequate storage for build directories, or unstable power during multi-hour emerge sessions.

Who this is for

Advanced users who want fine-grained control over system configuration, developers building custom embedded systems, and anyone willing to invest time for an optimized, minimal system tailored to Banana Pi hardware.

What you'll do

• Install a Gentoo stage3 tarball on Banana Pi storage.
• Configure Portage with ARM-specific make.conf settings.
• Set up cross-compilation or native compilation strategy.
• Build a minimal kernel and bootloader configuration.
• Manage thermal throttling during long emerge sessions.
• Troubleshoot build failures, dependency conflicts, and storage limitations.

Requirements

• Storage: Minimum 8GB for base system; 16GB+ recommended for desktop packages. Fast storage (UHS-I SD or eMMC) significantly improves build times.
• Power: Stable 5V 2A supply. Voltage drops during compilation cause kernel panics.
• Network: Stable Ethernet connection. WiFi can timeout during large package fetches (gcc, llvm).
• Cooling: Heatsink strongly recommended. Compiling without cooling causes thermal throttling and failed builds.
• Time: Initial system setup takes 6-12 hours on Banana Pi hardware. Some packages (gcc, llvm, chromium) take 2-4 hours each.
• Host PC (optional): Cross-compilation from x86_64 Linux host dramatically speeds up initial builds.

Download Gentoo for Banana Pi

Step-by-step setup

1. Download and extract stage3 tarball

Download ARM stage3 from Gentoo mirrors:

# On your PC, download stage3-armv7a_hardfp
wget https://distfiles.gentoo.org/releases/arm/autobuilds/current-stage3-armv7a_hardfp/

# Verify signature (IMPORTANT)
gpg --verify stage3-armv7a_hardfp-*.tar.xz.DIGESTS.asc

# Extract to mounted SD card or eMMC
cd /mnt/gentoo
tar xpvf /path/to/stage3-armv7a_hardfp-*.tar.xz --xattrs-include='*.*' --numeric-owner

2. Configure make.conf for ARM

Edit /mnt/gentoo/etc/portage/make.conf:

CFLAGS="-O2 -pipe -march=armv7-a -mfpu=neon-vfpv4 -mfloat-abi=hard"
CXXFLAGS="${CFLAGS}"
MAKEOPTS="-j2"  # Banana Pi has 2 cores; j3 can cause OOM
EMERGE_DEFAULT_OPTS="--jobs=1 --load-average=2.0"

# Essential USE flags for SBC
USE="-X -gtk -qt5 -kde bindist"  # Start minimal, add GUI later if needed

# Accept licenses
ACCEPT_LICENSE="*"

# Portage directories
PORTDIR="/var/db/repos/gentoo"
DISTDIR="/var/cache/distfiles"
PKGDIR="/var/cache/binpkgs"

# Reduce build temp space usage
PORTAGE_TMPDIR="/var/tmp"

3. Chroot and configure base system

# Mount proc, sys, dev
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

# Copy resolv.conf for network access
cp /etc/resolv.conf /mnt/gentoo/etc/

# Chroot
chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) ${PS1}"

# Sync portage tree (first time takes 10-15 minutes)
emerge-webrsync
# or: emerge --sync

# Set profile
eselect profile list
eselect profile set default/linux/arm/17.0/armv7a  # Adjust to your arch

4. Build kernel (native or cross-compile)

Option A: Native compilation (slow but simpler):

emerge sys-kernel/gentoo-sources
cd /usr/src/linux

# Use existing Banana Pi config if available
wget https://raw.githubusercontent.com/lemaker/linux-bananapi/sunxi-3.4/arch/arm/configs/bananapi_defconfig
make bananapi_defconfig

# Or start from scratch
make menuconfig
# Essential: Enable Allwinner A20 support, dwmac-sunxi Ethernet, sunxi-mmc

# Compile (takes 1-2 hours on Banana Pi)
make -j2 zImage modules dtbs
make modules_install
cp arch/arm/boot/zImage /boot/
cp arch/arm/boot/dts/sun7i-a20-bananapi.dtb /boot/

5. Configure bootloader (U-Boot)

emerge sys-boot/u-boot

# Write U-Boot to SD card (adjust /dev/sdX)
dd if=/usr/lib/u-boot/Bananapi/u-boot-sunxi-with-spl.bin of=/dev/sdX bs=1024 seek=8

# Create boot.scr
cat > /boot/boot.cmd << 'EOF'
setenv bootargs console=ttyS0,115200 root=/dev/mmcblk0p1 rootwait panic=10
load mmc 0:1 0x43000000 zImage
load mmc 0:1 0x43000000 sun7i-a20-bananapi.dtb
bootz 0x43000000 - 0x43000000
EOF

mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr

6. Configure system essentials

# Set timezone
echo "Europe/London" > /etc/timezone
emerge --config sys-libs/timezone-data

# Set hostname
echo "hostname=\"bananapi\"" > /etc/conf.d/hostname

# Configure networking
emerge net-misc/dhcpcd
rc-update add dhcpcd default

# Set root password
passwd

# Install essentials
emerge app-admin/sudo sys-process/cronie sys-apps/mlocate
rc-update add cronie default

7. Verify and reboot

# Exit chroot
exit

# Unmount
umount -l /mnt/gentoo/dev{/shm,/pts,}
umount -R /mnt/gentoo

# Remove SD card, insert in Banana Pi, boot
# Connect serial console to see boot messages

Concrete example (basic build health)

emerge --info | head -n 40
df -h

# Monitor thermal throttling during compilation
watch -n 2 'cat /sys/class/thermal/thermal_zone0/temp'

# Check available storage during emerge
df -h /var/tmp/portage

Troubleshooting

Builds fail mid-compile with "internal compiler error" or segfault

• Symptoms: gcc/g++ crashes during compilation; "Killed" message; random build failures.
• Steps:
  1. Check thermal throttling: cat /sys/class/thermal/thermal_zone0/temp. Banana Pi throttles at 80'C. Add heatsink.
  2. Verify power supply stability. Voltage drops cause memory errors. Use 5V 2A supply with short cable.
  3. Check memory: free -h. If swap is thrashing, reduce MAKEOPTS="-j1".
  4. Test storage: badblocks -sv /dev/mmcblk0. Failing SD cards cause silent corruption.
  5. Reduce compiler optimization: Change CFLAGS from -O2 to -O1 or -O0 temporarily.

Disk full during emerge

• Symptoms: "No space left on device" during compilation; /var/tmp/portage fills up.
• Steps:
  1. Check space: df -h /var/tmp. Some packages (chromium, llvm) need 4-6GB build space.
  2. Mount external storage: mount /dev/sda1 /mnt/external && PORTAGE_TMPDIR=/mnt/external/portage emerge pkg.
  3. Clean old build artifacts: eclean-dist --deep && eclean-pkg --deep.
  4. Use binary packages from Gentoo binhost: Add GENTOO_MIRRORS="https://gentoo.osuosl.org/" and emerge --getbinpkg pkg.

Network stalls during package fetch

• Symptoms: emerge hangs on "Fetching"; timeout errors; incomplete downloads.
• Steps:
  1. Use Ethernet instead of WiFi. WiFi dongles can lose connection during heavy CPU load.
  2. Change mirror: Edit GENTOO_MIRRORS in make.conf. Try mirrors geographically closer.
  3. Increase fetch timeout: FETCHCOMMAND and RESUMECOMMAND in make.conf.
  4. Download distfiles on host PC and copy to /var/cache/distfiles/ on Banana Pi.

Kernel panic on boot after emerge world

• Symptoms: Boots to "Kernel panic - not syncing: VFS: Unable to mount root fs".
• Steps:
  1. Check /boot/boot.scr root= parameter matches actual partition: blkid.
  2. Verify kernel modules installed: ls /lib/modules/$(uname -r)/.
  3. Rebuild initramfs if using one: genkernel --install initramfs.
  4. Recompile kernel with required drivers built-in (not as modules): MMC, filesystem (ext4), Ethernet.

FAQ

Should I cross-compile or compile natively on the Banana Pi?

Cross-compilation on an x86_64 host is 10-20x faster for initial system setup. Native compilation is simpler (no toolchain setup) but painfully slow for large packages. Hybrid approach: cross-compile kernel and toolchain, then compile remaining packages natively.

What MAKEOPTS value should I use?

Start with -j2 (number of CPU cores). If builds fail with "Killed" or OOM errors, reduce to -j1. The dual-core Banana Pi with 1GB RAM struggles with parallel builds of large packages.

How do I prevent thermal throttling during long compiles?

Add a heatsink (passive cooling helps significantly). Monitor temperature: watch cat /sys/class/thermal/thermal_zone0/temp. Keep below 75'C. Consider external fan for sustained heavy workloads. Compile at night when ambient temperature is lower.

Can I use distcc to distribute compilation across multiple machines?

Yes. Set up distcc on faster x86_64 hosts with ARM cross-compiler. Configure MAKEOPTS="-j8" and FEATURES="distcc" in make.conf. Significantly speeds up large packages. Requires network stability.

Why does emerge keep rebuilding the same packages?

Check for circular dependencies: emerge -pvt world. Update Portage: emerge --oneshot portage. Run emerge --depclean to remove orphaned packages. Check /etc/portage/package.use for conflicting USE flags.

How much storage do I need for a Gentoo desktop environment?

Minimal CLI system: 2-3GB. Base system + Xorg: 6-8GB. Xorg + lightweight WM (i3, openbox): 10-12GB. Full desktop (XFCE, MATE): 16-20GB. KDE/GNOME not recommended on 1GB RAM Banana Pi.

Can I install proprietary software like Chrome or Spotify?

Some proprietary packages available in Portage with appropriate ACCEPT_LICENSE settings. Chrome (not Chromium) not available for ARM. Spotify requires x86_64. Use open-source alternatives: Chromium, mpd/ncmpcpp.

How do I update Gentoo system?

emerge --sync && emerge -uDN @world. Run weekly. Large updates (gcc, glibc, Python) may require 4-8 hours. Always keep backup SD card with working system.

External reference

• Gentoo Handbook (wiki.gentoo.org)
• Gentoo ARM Handbook
• Gentoo on Raspberry Pi (similar ARM setup)

Related guides

• Downloads hub
• Banana Pi resources
• Quick Start Guide

Author: LeMaker Documentation Team
Last updated: 2026-01-20