Gentoo Wiki


This page is used as a temporary spot to place information regarding Gentoo Embedded. For official documentation, check the Embedded Gentoo Project Page.


Some Goals of Embedded Gentoo

Gentoo Embedded Basics

The Gentoo Embedded Project has a broad goal of improving support for embedded in Gentoo. One of the things that makes this so broad and hard to define is that embedded itself is such a broad topic. Embedded to some people is using hardware with limited resources to do useful things. To some other people it's using microcontrollers.

What are we out to support? Yes. That is to say, we want to support everything we can humanly support in order to give our users the choice that they've come to expect from Gentoo.

Along with this choice comes the responsibility to know what you want. There are many ways to do different things. It's up to you to find the best way to make Gentoo suit your needs.

That being said, we are going to try to cover some common ways to do what people seem to ask us about most.

Getting Started Making An Image That's Suitable For Deployment

This section assumes a few things. We aren't cross-compiling. We are compiling for a system that our current stage supports.

An example situation being compiling an image for an epia or soekris board from a normal x86 host.

To do this, we start out with a full stage3 (you can of course start with whatever stage you want, but for sake of speed...) that uses uclibc as it's libc. We can put this straight on a computer for normal use, or we can unpack it into a directory and chroot into it. Once we have the system ready to go we use the magic of portage and it's ROOT environment variable.

To start off, let's say we want a fairly simple rootfs for a device. We could do something like the following:

ROOT="/tmp/minime" emerge uclibc busybox baselayout-lite dropbear

With the current (2006-06-28) portage tree, you'll probably want to do this. First, unmask baselayout-lite-1.0_pre1.ebuild. Currently, it has KEYWORDS="-*" in it so it won't be mergeable by default. (2007-04-01) Bug #160519 shows us that it need to be KEYWORDS="**" as of now. Then, run the following command. The "make-symlinks" USE flag tells the busybox ebuild to create symlinks for all the tools - by default these aren't created to allow merging to / without frying all of your existing system tools:

ROOT="/tmp/minime" USE="make-symlinks" emerge uclibc busybox baselayout-lite dropbear

Now obviously you'll want to run that with the --pretend parameter and make sure it's going to do what you want. You may need to tweak USE flags or other things to get it the way you want.

Once you get it the way you want, and you run the command, you'll then have a rootfs ready for your customizations in /tmp/minime. Just add a kernel of some sort. Then some things that you'll want to tweak are the normal stuff from baselayout that you would edit in a regular Gentoo install (fstab, network initialization stuff, hostname/domainname, etc.)

Emerge other applications that are necessary. Keep using the ROOT= environment variable. With newer versions of portage, you can keep files from being installed with the environment variable INSTALL_MASK

After you install stuff and edit the config files to your liking, you are ready to transfer this to your device. This is the tricky part. There are so many ways to do this. You can create a jffs2 image out of the files in /tmp/minime. You can rsync them over. You can even burn them straight to a cd, and boot off of it. I'll leave this step up to you to figure out.

Setting Up The Environment

At a high level, from start to finish, the steps are

  1. create a cross-compiler environment (binutils + libc + compiler) (use crossdev)
  2. emerge the cross-compiled run-time environment (binutils + libc) to the staging area (use emerge or a stage-tarball)
  3. emerge the basic root file system to the staging area (use emerge or a stage-tarball)
  4. emerge/install other packages to the staging area (use emerge)
  5. pack up the staging area file system and flash to your device
 emerge '>=crossdev-0.9'
 crossdev --help
 crossdev --target ppc-unknown-linux-gnu

Notice: If linux-headers fails to build, switch gcc profile to the one you'll be using for your embedded system with gcc-config, and the run "crossdev --target <architecture>" once more.

 use a stage-tarball OR
 # check your USE variable!
 # Many variables are needed for the root:
 ROOT="/tmp/minime" emerge uclibc busybox baselayout-lite dropbear
 # When compiling glibc, you might notice that 'prefix' == /usr. This is OK, even if $ROOT points elsewhere
 CFLAGS_FOR_BUILD=${CFLAGS} CBUILD="yourownsystem" \
 CHOST="yourspecialsystem" CFLAGS="yournewcflags" \ 
 CXXFLAGS=${CFLAGS} ROOT="/tmp/minime" INSTALL_MASK="*.h" \ 
 emerge mypackage

Where yourspecialsystem the target you specified in the crossdev stage. The yournewcflags should be your new cflags for this system. yourownsystem should be the something like x86_64-pc-linux-gnu. If you are crosscompiling binutils CFLAGS_FOR_BUILD need to be set too.

Yes, it is integrated into the main portage tree

Developing an Embedded-Gentoo System

Some questions posted to the mailing list that would be worth answering:

There is a fine tutorial here: TinyGentoo, it uses /usr/portage/profiles/uclibc/x86/2005.1/2.4

sstrip from elfkickers. (use with care)

Packagename: elfkickers (Home)

Some Links

Retrieved from ""

Last modified: Thu, 02 Oct 2008 10:06:00 +0000 Hits: 48,702