Gentoo Logo
Gentoo Logo Side

Gentoo Embedded x86 Guide


1. Introduction

What is Gentoo Embedded? 

From the Gentoo Embedded website :

This project manages embedded system support in Gentoo. The project is responsible for overseeing the build infrastructure for creating images to be installed onto embedded systems. Also included is the support of specific types of embedded systems and development tools.

What is x86 Gentoo Embedded? 

x86 Gentoo Embedded is simply embedded Gentoo for the x86 architecture (think Intel, AMD, and Via processors). It's main purpose is for embedded SBCs (single board computers) based on the x86 architecture were a small non-volatile (flash, compact flash, DiskOnChip) footprint is needed (as low as 10 MB).

Definitions and Terms 

Term Definition
rootfs root filing systems, / and everything underneath it
system_rootfs your regular rootfs, development computer
development_rootfs what you use to build the embedded_rootfs
embedded_rootfs rootfs you deploy to the target system
SBC single board computer (here it's an x86 based)

Overview of Process (steps) 

Step # Description
1 Prepare the development_rootfs from your system_rootfs
2 Build the development_rootfs
3 Build the embedded_rootfs
4 Build and install non-system programs to the embedded_rootfs
5 Build and install a kernel to the embedded_rootfs
6 Deploy embedded_rootfs to target

2. Step 1 - Prepare the development_rootfs from your system_rootfs

You must be root, and cd to the working directory (/opt). 

Code listing 2.1: need to root and set work directory

# su -
# cd /opt

Create development_rootfs 

Create the development_rootfs directory. I use i586 because of target is a Geode processor.

Code listing 2.2: Create the development_rootfs directory

# mkdir -p /opt/i586-gentoo-uclibc-linux/usr/portage

Download stage 1 embedded Gentoo tarball. 

Download the latest stage 1 tarball. It's a stage 1 tarball utilizing uclibc.

Code listing 2.3: download the latest stage 1 tarball

# wget \\

Untar stage. 

Untar the stage to the development_rootfs.

Code listing 2.4: untar the stage to the development_rootfs

# tar -xvjpf stage1-x86-uclibc-2005.0.tar.bz2 -C /opt/i586-gentoo-uclibc-linux/

Mount needed directories. 

Mount the proc and portage directories to your development_rootfs. Makes your system_rootfs's proc and portage directory available from inside of your development_rootfs (after chrooting).

Code listing 2.5: mount proc and portage

# mount --bind /proc /opt/i586-gentoo-uclibc-linux/proc/
# mount --bind /usr/portage /opt/i586-gentoo-uclibc-linux/usr/portage

Copy DNS info. 

Copy over DNS information to the development_rootfs.

Code listing 2.6: copy DNS info

# cp /etc/resolv.conf /opt/i586-gentoo-uclibc-linux/etc/resolv.conf


Chroot into the development_rootfs.

Code listing 2.7: chroot

# chroot /opt/i586-gentoo-uclibc-linux /bin/bash --login

3. Step 2 - Build the development_rootfs

Create new environment and load variables into memory. 

Code listing 3.1:

# env-update
# source /etc/profile

Modify make.conf. 

Modify make.conf file to your liking/needs. This is for my target, Geode x86 processor.


Code listing 3.2: make.conf

# nano -w /etc/make.conf

USE="bitmap-fonts minimal truetype-fonts mmx"
CFLAGS="-march=i586 -Os -pipe -fomit-frame-pointer -mmmx"


Set profile to use 2.6 kernel. 

Code listing 3.3: set profile to 2.6

# cd /etc/
# unlink make.profile
# ln -s ../usr/portage/profiles/uclibc/x86/2005.1 make.profile

Start the bootstrap script. 

Code listing 3.4: bootstrap

# cd /usr/portage/scripts
# ./ -p -v
# ./

Workaround - bootstraping
Failure compiling uclibc (gcc-config error: Could not run/locate "gcc")?
If you get a failure while bootstrap is compiling uclibc here are the steps
to work around the problem.
# gcc-config 1
# source /etc/profile
# ./

Emerge the system ebuild for the development_rootfs. 

Code listing 3.5: emerge system

# emerge -e system

Workaround - emerge system
During emerge -e system, python-fchksum fails complaing about
gcc-config error: Could not run/locate "i386-gentoo-linux-uclibc-gcc"
The following commands work around this problem.
# emerge python
# emerge -e system

4. Step 3 - Build the embedded_rootfs

Create the embedded_rootfs directory. 

Code listing 4.1: mkdir

# mkdir /embedded_rootfs

Emerge baselayout-lite into embedded_rootfs. 

Code listing 4.2: emerge baselayout-lite

# cd /usr/portage/sys-apps/baselayout-lite/
# ROOT=/embedded_rootfs emerge baselayout-lite-1.0_pre1.ebuild

Workaround - baselayout-lite
Baselayout-lite is still beta, so a few fixes are needed.
There needs to be a directory "log" in /var.
Inittab calls for /usr/bin/tail, but it needs to /usr/bin.
# mkdir /embedded_rootfs/var/log
# nano -w /embedded_rootfs/etc/inittab
tty3::respawn:/usr/bin/tail -f /var/log/messages
tty3::respawn:/bin/tail -f /var/log/messages

Emerge uclibc into the embedded_rootfs. 

Use the -K option because we don't get the extra files created by the build/emerge process into our embedded rootfs which needs to be as small as possible.

Code listing 4.3:

# ROOT=/embedded_rootfs emerge -K uclibc

Emerge busybox into the embedded_rootfs. 

First you must emerge it into your development_rootfs. This does not create the symlinks in our development embedded rootfs.

Code listing 4.4:

# emerge busybox
# ROOT=/embedded_rootfs emerge -K busybox

Create the symlinks for busybox in the embedded_rootfs. 

Code listing 4.5:

# mkdir /embedded_rootfs/proc
# mount -o bind /proc/ /embedded_rootfs/proc/
# chroot /embedded_rootfs /bin/busybox --install -s
# umount /embedded_rootfs/proc

Set time zone in your embedded_rootfs. 

Code listing 4.6:

# nano -w /embedded_rootfs/etc/TZ

Install a boot loader (usually grub or lilo). 

Once you copy/deploy your embedded_rootfs to your target SBC you will have to run grub on the command line to write to the master boot record (MBR). For some reason not all of /boot/grub is copied over to the embedded_rootfs, so a extra manual copy step is needed. The --nodeps gets rip of the run time need of ncurses.

Code listing 4.7:

# emerge --nodeps grub
# ROOT=/embedded_rootfs emerge -K --nodeps grub
# cp -R /boot/grub /embedded_rootfs/boot/

Modify your boot configure file. The example below is for a gurb, for a boot partition on /dev/hda1 and only one partition on the target SBC system.

Code listing 4.8:

# nano -w /embedded_rootfs/boot/grub/grub.conf
default 0
timeout 10

title=Linux 2.6.x
root (hd0,0)
kernel /vmlinuz-2.6.x root=/dev/hda1 vga=792

Set root password for the embedded_rootfs. 

Code listing 4.9:

# chroot /embedded_rootfs /bin/sh
# passwd
# exit
# rm /embedded_rootfs/etc/passwd-

Modify fstab. 

Below is mine, yours may vary.

Code listing 4.10:

# nano -w /embedded_rootfs/etc/fstab
/dev/hda1     reiserfs  defaults  0 0
none/proc     proc      defaults  0 0
none/sys      sysfs     defaults  0 0
none/dev/shm  tmpfs     defaults  0 0

Clean up the embedded_rootfs. 

Need to clean up extra files generated by portage that we don't need.

Code listing 4.11:

rm -R /embedded_rootfs/var/db/pkg/*
rm -R /embedded_rootfs/var/lib/portage/

5. Step 4 - Build and install non-system programs to the embedded_rootfs

Emerge other software you need for you embedded target. This is very wildly depending on your needs. Also your proprietary application will be done here.

Code listing 5.1:

# emerge foo*
# ROOT=/embedded_rootfs emerge -K foo*

6. Step 5 - Build and install a kernel to the embedded_rootfs

Install a kernel into embedded_rootfs. 

First we will emerge it into our development_rootfs, then configure and build it.

Code listing 6.1: emerge kernel, enter menuconfig

# emerge vanilla-sources
# cd /usr/src/
# cd linux
# make menuconfig

Configure your kernel for your TARGET SBC here. I HIGHLY suggest you configure the kernel to compile everything into the kernel, and nothing as a module.

Code listing 6.2: build and install kernel

# make
# make INSTALL_MOD_PATH=/embedded_rootfs modules_install
# cp /usr/src/linux/arch/i386/boot/bzImage /embedded_rootfs/boot/vmlinuz-2.6.x

A few notes on compiling your kernel. If deploying to a compact flash/DiskOnChip/SD use ext2, as the journaling filing systems "write" far to much for a flash device. If deploying to a hard drive use a journaling filing system, such as ext3 or reiserfs.

7. Step 6 - Deploy embedded_rootfs to target

Prepare a Gentoo (or any Linux distro) system on the target SBC using a harddrive. This is known as the target development rootfs. We will create a partition (/embedded_rootfs) that will server as our "test" partition to deploy our embedded_rootfs that we generate on our development_system.

Partition Mount Point Size
/dev/hda1 /embedded_rootfs 1 GB
/dev/hda2 /boot 100 MB
/dev/hda3 swap (size varies, 512 MB is a good number)
/dev/hda4 / (what is left, at least 1.5 GB per 2005.0 install guide specs)

Copy over your embedded_rootfs from you development system to your target system and the directory /embedded_rootfs. This needs to be done via NFS as need to preserve the permissions.

The following commands are done from the target development rootfs.

Code listing 7.1:

# mount -t reiserfs /dev/hda1 /mnt/embedded_rootfs
# mount -t nfs\
# /mnt/nfs_embedded_rootfs
# cp -adpR /mnt/nfs_embedded_rootfs/* /mnt/embedded_rootfs

Modify your target system's gurb.conf (or lilo.conf) for allow you to boot to the embedded_rootfs partition.

Reboot, and if all goes well you'll be greeted with a login prompt.


The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated 2005-11-02
Heath Holcomb

Ned Ludd

Lloyd Sargent

Yuri Vasilevski

Mike George

Marius Schaefer

Pierre Cassimans

Summary:  This document is a guide to build a x86 Gentoo embedded build.

Donate to support our development efforts.

The Gentoo Linux Store

php|architect is the monthly magazine for PHP professionals, available worldwide in print and electronic format. A percentage of all the sales will be donated back into the Gentoo project.

Tek Alchemy

Tek Alchemy offers dedicated servers and other hosting solutions running Gentoo Linux.

DDR Memory at

Purchase RAM from and a percentage of your sale will go towards further Gentoo Linux development.

Win4Lin at NeTraverse

Win4Lin from NeTraverse lets you run Windows applications under Gentoo Linux at native speeds.

Copyright 2001-2003 Gentoo Technologies, Inc. Questions, Comments, Corrections? Email