embedded gentoo [uclibc] | nothing beats this

A few uclibc embedded gentoo facts:

  • the compilation of the box takes around 15 minutes
  • at boot up, takes less than 3 megabytes of RAM
  • disk space: 17 megabytes
  • boots in under 8 seconds on a pentium3

link to stage3 tarballs archive
HTOP - Displaying System Statistics
# this is my make.conf, it should be the same in the stage3, if installing anything in the stage3, and even before updating, comment the line INSTALL_MASK=”*.h HACKING.gz TODO.gz”

CFLAGS="-Os -mtune=i386 -pipe"
CXXFLAGS="-Os -mtune=i386 -pipe"

GENTOO_MIRRORS="http://mirror.bytemark.co.uk/gentoo/ http://www.ibiblio.org/pub/Linux/distributions/gentoo"

USE="-ipv6 -python3 -cracklib -minimal"


# download my stage3, from the previous post links, and then prepare to chroot

mount -o bind /dev stage3-*/dev
mount -o bind /proc stage3-*/proc
chroot stage3-*

# update the system, and create the necessary path, if you come across any errors, post them here, and expect a reply soon

emerge -avuDN world
mkdir /mounted

# begin the installation
# install necessary packages

ROOT=/mounted/ emerge -auvND baselayout uclibc bash dropbear pam udev iptables coreutils nano util-linux shadow kbd net-tools grep procps gzip sed findutils mawk htop
mkdir /mounted/proc
mkdir /mounted/dev

# exit the chroot, and then unmount the dev and proc

umount stage3-*/dev
umount stage3-*/proc

# chroot again and continue stripping

chroot stage3-*/

# you’ll need to copy what’s already in my stage3 dev/ to the target dev/

cp -r /dev/* /mounted/dev/

# begin unmercilessly throwing out things

rm -rf /mounted/var/db/*
rm -rf /mounted/var/log/*
rm -rf /mounted/usr/include/
rm -rf /mounted/usr/lib/pkgconfig/
cp -pr /mounted/usr/share/keymaps/i386/qwerty/ ./
rm -rf /mounted/usr/share/keymaps/*
mkdir /mounted/usr/share/keymaps/i386/
mv ./qwerty/ /mounted/usr/share/keymaps/i386/
rm -rf /mounted/usr/share/nano/
rm -rf /mounted/var/lib/portage/
rm -rf /mounted/var/lib/gentoo/
rm -rf /mounted/var/lib/misc/
rm -rf /mounted/var/cache/*
rm -rf /mounted/usr/share/terminfo/
rm -rf /mounted/usr/share/baselayout/
rm -rf /mounted/usr/share/consoletrans/
rm -rf /mounted/usr/share/openrc
rm -rf /mounted/usr/sbin/fdformat
rm -rf /mounted/var/lib/misc/
rm -rf /mounted/etc/logrotate.d/
rm -rf /mounted/etc/portage/

# i got the necessary libs for ext4 by doing ldd /sbin/fsck.ext4, if you use another filesystem, do the needful
# installing e2fsprogs hogs too much of valuable space

cp /sbin/fsck.ext4 /mounted/sbin/
cp /lib/libext2fs.so.2* /mounted/lib/
cp /lib/libcom_err.so.2* /mounted/lib/
cp /lib/libblkid.so.1* /mounted/lib/
cp /lib/libuuid.so.1* /mounted/lib/
cp /lib/libe2p.so.2* /mounted/lib/
cp /lib/libpthread* /mounted/lib/
cp /lib/ld-uClibc* /mounted/lib/

# copy, remove and then place the needed stuff for terminal fonts, etc.

cp /mounted/usr/share/unimaps/iso01.uni ./
cp /mounted/usr/share/consolefonts/default8x16.psfu.gz ./
rm -rf /mounted/usr/share/unimaps/*
rm -rf /mounted/usr/share/consolefonts/*
mv ./default8x16.psfu.gz /mounted/usr/share/consolefonts/
mv ./iso01.uni /mounted/usr/share/unimaps/

# all done

# I’m done, what now?
# Most importantly, get your kernel configured correctly, if anyone would want to use my kernel config as a base, comment, and I will upload it
# chroot into the target system(in this example, chroot /mounted), and run passwd, set the system root password, modify your /etc/fstab, here’s an example:

# <fs>   <mountpoint>  <type>  <opts>  <dump/pass>
/dev/hda1 / ext4 noatime,nodelalloc 0 1
none /dev/pts devpts mode=0620 0 0
shm /dev/shm tmpfs nodev,nosuid,noexec 0 0

# now follow the gentoo handbook, and setup your network configuration, and whatever was missed out here

My kernel configuration for the Intel Pentium family is here :)


52 responses to “embedded gentoo [uclibc] | nothing beats this”

  1. Jude, there is a Gentoo bug for putting together an official tiny stage3 and profile. Could you take a look?


    1. Thanks for the link Grant, I’m following that bug.

  2. guess Avatar


    i*m new to embedded Gentoo. I just chrooted into yout latest stage3 (august 2011), synced and tried to upgrade. Now world wants to pull in a lot of new packages. I assume this is normal because of new added dependencies.

    Now uclibc fails to build. I already tried to comment MAKEOPTS but it didn’t help. Here’s the build log: http://pastebin.com/JfhFP3cG

    Any help is appreciated.


    1. judepereira Avatar

      Could you try to mask that version of uclibc? Some of them are unstable, and do not compile well.
      Also, I’ll soon put up updated stages for this month, May 2012.

      1. guess Avatar

        Thanks for your hint. I had to put “>=sys-libs/uclibc-0.9.27-r1” into package.mask in order to get things going. All versions newer than that do always fail to build.

        Btw. “emerge –with-bdeps=y -avuDN world” pulls in “dev-util/pkgconfig-0.26” which requires “dev-libs/glib-2.32.1”. Do you think this is fine? I’d have to unmask glib in “package.accept_keywords” in order to get it emerged.

        In regards to to pax-utils: this is required by “sys-apps/portage” and “sys-apps/sandbox”.

        If you are interested this is what a world update looks like atm (prior to masking uclibc and pkgconfig): http://pastebin.com/x6kykGT6

        If you want to you could a /root/.bashrc to the stages. This saves three manual steps after chrooting. :)

        source /etc/profile;
        export PS1=”ne[00;91m[chroot@embedded]e[00mn$PS1″

        1. judepereira Avatar

          The newer versions of uclibc need to include a patch that fixes most of the issues. You can stick to stable uclibc, which compiles and works just fine.
          You could try unmasking glib by putting that specific version in package.keywords, it should compile well.

          Regarding the three lines to the bashrc, I can’t do it manually as I use the catalyst spec files to build the entire stage3, from a stage2.

          I don’t get why would portage and sandbox need pax-utils, as it doesn’t compile very well(not sure of the newer versions).

          1. guess Avatar

            The pointer to pax-utils was rather meant for Acroyear249. :) I had no problems to build it.

            As far as I can tell pax-utils is required by these packages/versions:

            dev # equery d pax-utils
            * These packages depend on pax-utils:
            sys-apps/portage- (>=app-misc/pax-utils-0.1.17)
            sys-apps/sandbox-2.5 (>=app-misc/pax-utils-0.1.19)

            dev # grep -i pax-utils /usr/portage/sys-apps/portage/portage-*
            /usr/portage/sys-apps/portage/portage- >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage- >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage- >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage- >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage-2.2.0_alpha101.ebuild: >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage-2.2.0_alpha89.ebuild: >=app-misc/pax-utils-0.1.17
            /usr/portage/sys-apps/portage/portage-9999.ebuild: >=app-misc/pax-utils-0.1.17

            dev # grep -i pax-utils /usr/portage/sys-apps/sandbox/sandbox-*
            /usr/portage/sys-apps/sandbox/sandbox-1.6-r2.ebuild: >=app-misc/pax-utils-0.1.19″ #265376
            /usr/portage/sys-apps/sandbox/sandbox-2.3-r1.ebuild: >=app-misc/pax-utils-0.1.19″ #265376
            /usr/portage/sys-apps/sandbox/sandbox-2.4.ebuild: >=app-misc/pax-utils-0.1.19″ #265376
            /usr/portage/sys-apps/sandbox/sandbox-2.5.ebuild: >=app-misc/pax-utils-0.1.19″ #265376

            Btw. are you around on an IRC channel? Maybe we could have a chat there. :)

            1. judepereira Avatar

              Oh, pax-utils wasn’t involved when I build my embedded filesystem. Maybe some use flags are pulling it in?

              Yes, we could certainly have a chat on the IRC, I’ve just got back from my vacations, so I’ll take another day to get my internet connection working.

              1. guess Avatar

                portage lists pax-utils in RDEPEND while sandbox has it in DEPEND. Both have no useflags involved, so pax-utils seem to be mandatory.

                The sandbox ebuilds point to a bug report in regards to pax-utils: https://bugs.gentoo.org/show_bug.cgi?id=265376

  3. Acroyear249 Avatar

    Hello tried to follow your guide but emerge -aDuN world fails as following:

    # emerge -DuN world
    Calculating dependencies… done!

    >>> Verifying ebuild manifests

    >>> Starting parallel fetch

    >>> Emerging (1 of 10) app-misc/pax-utils-0.3.0
    openpty failed: ‘out of pty devices’
    * pax-utils-0.3.0.tar.xz RMD160 SHA1 SHA256 size ;-) … [ ok ]
    >>> Unpacking source…
    >>> Unpacking pax-utils-0.3.0.tar.xz to /var/tmp/portage/app-misc/pax-utils-0.3.0/work
    >>> Source unpacked in /var/tmp/portage/app-misc/pax-utils-0.3.0/work
    >>> Compiling source in /var/tmp/portage/app-misc/pax-utils-0.3.0/work/pax-utils-0.3.0 …
    make -j3 CC=i386-gentoo-linux-uclibc-gcc USE_CAP=
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o paxelf.o -c paxelf.c
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o paxmacho.o -c paxmacho.c
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o paxinc.o -c paxinc.c
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o xfuncs.o -c xfuncs.c
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o scanelf.o -c scanelf.c
    scanelf.c:63: error: ‘AT_FDCWD’ undeclared here (not in a function)
    scanelf.c: In function ‘fopenat_r’:
    scanelf.c:95: warning: implicit declaration of function ‘openat’
    scanelf.c:95: warning: nested extern declaration of ‘openat’
    scanelf.c:95: error: ‘O_CLOEXEC’ undeclared (first use in this function)
    scanelf.c:95: error: (Each undeclared identifier is reported only once
    scanelf.c:95: error: for each function it appears in.)
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o dumpelf.o -c dumpelf.c
    scanelf.c: In function ‘lookup_cache_lib’:
    scanelf.c:831: warning: implicit declaration of function ‘fstatat’
    scanelf.c:831: warning: nested extern declaration of ‘fstatat’
    scanelf.c: In function ‘lookup_config_lib’:
    scanelf.c:926: warning: implicit declaration of function ‘faccessat’
    scanelf.c:926: warning: nested extern declaration of ‘faccessat’
    scanelf.c:926: error: ‘AT_SYMLINK_NOFOLLOW’ undeclared (first use in this function)
    i386-gentoo-linux-uclibc-gcc -march=i386 -Os -pipe -D_GNU_SOURCE -DVERSION=”0.3.0″ -o pspax.o -c pspax.c
    scanelf.c: In function ‘scanelf_fileat’:
    scanelf.c:1651: error: ‘O_CLOEXEC’ undeclared (first use in this function)
    scanelf.c: In function ‘scanelf_dirat’:
    scanelf.c:1682: error: ‘AT_SYMLINK_NOFOLLOW’ undeclared (first use in this function)
    scanelf.c:1692: error: ‘O_CLOEXEC’ undeclared (first use in this function)
    scanelf.c:1696: warning: implicit declaration of function ‘fdopendir’
    scanelf.c:1696: warning: nested extern declaration of ‘fdopendir’
    scanelf.c:1696: warning: assignment makes pointer from integer without a cast
    scanelf.c: In function ‘_load_ld_cache_config’:
    scanelf.c:1803: error: ‘O_CLOEXEC’ undeclared (first use in this function)
    scanelf.c: In function ‘parseargs’:
    scanelf.c:2194: error: ‘O_CLOEXEC’ undeclared (first use in this function)
    make: *** [scanelf.o] Error 1
    make: *** Waiting for unfinished jobs….
    emake failed
    * ERROR: app-misc/pax-utils-0.3.0 failed (compile phase):
    * (no error message)
    * Call stack:
    * ebuild.sh, line 85: Called src_compile
    * environment, line 708: Called die
    * The specific snippet of code:
    * emake CC=”$(tc-getCC)” USE_CAP=$(use caps && echo yes) || die
    * If you need support, post the output of ’emerge –info =app-misc/pax-utils-0.3.0′,
    * the complete build log and the output of ’emerge -pqv =app-misc/pax-utils-0.3.0′.
    * The complete build log is located at ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/temp/build.log’.
    * The ebuild environment file is located at ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/temp/environment’.
    * S: ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/work/pax-utils-0.3.0’

    >>> Failed to emerge app-misc/pax-utils-0.3.0, Log file:

    >>> ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/temp/build.log’

    * Messages for package app-misc/pax-utils-0.3.0:

    * ERROR: app-misc/pax-utils-0.3.0 failed (compile phase):
    * (no error message)
    * Call stack:
    * ebuild.sh, line 85: Called src_compile
    * environment, line 708: Called die
    * The specific snippet of code:
    * emake CC=”$(tc-getCC)” USE_CAP=$(use caps && echo yes) || die
    * If you need support, post the output of ’emerge –info =app-misc/pax-utils-0.3.0′,
    * the complete build log and the output of ’emerge -pqv =app-misc/pax-utils-0.3.0′.
    * The complete build log is located at ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/temp/build.log’.
    * The ebuild environment file is located at ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/temp/environment’.
    * S: ‘/var/tmp/portage/app-misc/pax-utils-0.3.0/work/pax-utils-0.3.0’

    any ideas?

    1. judepereira Avatar

      Hi acroyear249,
      Have you tried the stable version, 0.2.3 of pax-utils? Also, can you find out why is pax-utils being pulled into the dependencies?

      Also, if the above fails, change MAKEOPTS=-j3 to -j1, as some code does not compiled well with -j3(because of incomplete code generated from other threads).

  4. Just a note, i would NOT recommend using the unstable branch, as there’s a TON of patches
    that have not been applied yet there. It’s not for the faint of heart.
    Tough with a bit of work, and some creative editing of c code, you can get it to work.

  5. Piel kop Avatar
    Piel kop

    Nice work thanks.
    Any idea if your work and papuglinux.net uClibc Gentoo distro can be merged somehow ?
    Also is there a way to get a amd64 / x86_64 and what would be the steps needed ?

    I would like to rebuild or build a complete small amd64 desktop uClibc distro for my own
    use + all needed packages as bin just to see if I can and if it can work.

    MadRocker JetDroid

    1. judepereira Avatar

      What you can simply do is to get the world file from that linux distribution, and have those extra packages installed.

      As of the amd64 stages, I’ll create those stages and upload them here within a week.

      1. Any progress or ETA for the amd64 stages?

        1. judepereira Avatar

          Hi Piper,
          Not yet, I haven’t got the time. I’ve got work in the morning and college in the afternoon.
          I’ll try to create them as soon as I finish my present project, but I believe that x86 should serve better, as I don’t think that you’d need over 4GB of RAM for this, as uClibC by itself has a very small memory footprint.

  6. Which uClibc version are you using? In the portage tree, there’s only, but according to uClibc. the latest release is 0.9.32, released day before yesterday. Have you tried updating to the latest? I’ll update my stages to use the latest one shortly.

  7. Thanks, that seemed to work but now it fails to emerge mesa.
    I had to patch mesa to get around loc errors but now it just dies with an undefined reference to exp2f.

    I applied a exp2f patch to uClibc but it still gives that error.

  8. What happens if you disable the udev flag for xorg?

  9. Hi, I’ve been following your steps and I have a nice small bootable Gentoo system.
    However, xorg depends on later versions of udev which all seem to depend on glibc.

    Any thoughts?

  10. Hrm. All of my attempts to rebuild using emerge -avuDN world result in:

    “C compiler cannot create executables” when rebuilding busybox, uclibc, or diffutils. :\
    Any ideas?

    1. There are many possible reasons for that, the most common one is that you’ve either mounted your partition with the noexec option(check /etc/fstab) or that the user doesn’t have the necessary permissions to do so, try doing it as root, and remove the noexec parameter from your fstab.

  11. goddisignz Avatar

    There is no older version of pam. All older ebuilds seem to be dead.
    Any other solution?

    1. goddisignz Avatar

      Ok, I found an old ebuild file but had to download all patches by hand.
      If anyone else has the same problem just download these two files:


      first one is the ebuild file and the patches.
      second one can be made executable and run or you can just run the code inside.

  12. goddisignz Avatar

    How did you get sys-libs/pam to install in /mounted/.
    It always fails due to undefined reference to ‘innetgr’. I searched the web were some people tell innetgr is not available in uclibc. But nobody tells you how to solve this.
    Is this right? How did you manage this?

    1. sys-libs/pam-1.1.1-r2 compiled fine against sys-auth/pambase-20100724, it worked like a charm, although now I’ve stopped using PAM for authentication. The latest PAM 1.1.3 may not compile, well, so try dropping down to the earlier releases, not every version compiles well with uclibc.

    2. just browse and use http://git.overlays.gentoo.org/gitweb/?p=proj/embedded-cross.git, lot of x-compilation problems have been patched there.

      1. Thanks for pointing that out Leho, haven’t had time yet to play around with that overlay.

  13. Here is an outline of what you’ll have to get done, install grub, then create an image that can be written to a hard disk, test this image with qemu, if it works successfully at first, then dd this image to a hard disk, and boot it in your other geode box. You’ll have to set a right kernel configuration, as the bus devices in the geode are different, or maybe set up a generic kernel.

    You can try this out with qemu by:
    $ sudo qemu -cpu qemu32 -m 32M -hda mgentoo.img

    Once it works fine here, it should work perfectly with the other box(if you’ve selected the right drivers, etc.).

  14. goddisignz Avatar

    Could you give me a useful link where is explained how to install this new tiny system to an other pc, like my geode-box?

  15. Hello! And Thank you for your great work!

    I have errors about portage profile when try to do this:

    emerge -avuDN world

    Should I download and unpack portage snapshot in chrooted environment as usual? Or I missing something?

    It would be nice to see article about how you make your stage3.

    Thank you!

    1. Yes, you need to download the portage tree and place it in /usr, without it, emerge can’t find the uclibc profile.

      I will demonstrate on how to make a stage3 as soon as I get some time, exams are all over the place.

  16. goddisignz Avatar

    I am working on an AMD x86_64 (Ubuntu but downloaded and unpacked portage) and want to build an embedded system for an AMD Geode GX.
    Do I have to install a cross compiler? I just tried to use CHOST=”i586-gentoo-linux-uclibc” in my make.conf and UCLIBC_CPU=”586″ and added -march=i586 to my CFLAGS and CXXFLAGS.
    emerge -auvDN world never works due to non-working compiler.
    It would be nice if someone give me a hint or better a solution.



    1. The AMD Geode is an x86 compatible processor, so I would suggest that you download my latest updated stage3, and chroot into it, this tutorial will get you well working, as basically a stage3 means a compact yet minimal base system. You can chroot into it and work on it independent of your host machine, I myself update the stage3’s on an Intel 64-bit CPU.

  17. darookee Avatar

    It got this (http://pastebay.com/108330) error while doing emerge -uvaDN world from coreutils-8.6

    I also get this before the emerge starts:
    !!! All ebuilds that could satisfy “>=dev-lang/perl-5.10.1” have been masked.
    but this does not seem to be critical…


    1. pthreads has always posed a threat to uclibc, I suggest you wait for another coreutils update, then try to compile that, or downgrade to a coreutils that works fine. Not every version of an application is supported by uclibc, some are known to have bugs and never to compile properly.

  18. embedded-newbie Avatar

    Hello and thank you for your stages.

    During the last months, I have repeatedly tried to create my first embedded system. Everything seems ok but I cannot set the root password: any time I type passwd inside the /mounted chroot, I get this output after the password insertion:
    crypt method not supported by libcrypt? (SHA512)

    Thus, I cannot login in the embedded system, which seems to boot fine apart from that. I have both followed blindly your neat and clear howto and tried to customize it through the tinygentoo and the ratgentoo pages. The problem is always the same.
    To remain on the safe side, I used the very same kernel config of my working desktop installation.

    I am sure this must be a very silly error, but I cannot find where I do wrong.

    Thanks in advance for every suggestions.

    1. Actually even I faced the very same problem when I first started writing this tutorial, the solution is simple; recompile sys-auth/pambase with sha512 support enabled, i. e.,
      echo sys-auth/pambase sha512 >> /etc/portage/package.use
      ROOT=/mounted emerge -avuDN world

      1. what about the SHA512 libcrypt error when you don’t want to have PAM on the system?

      2. yeah, ENCRYPT_METHOD MD5 in /etc/login.defs

      3. I’m glad you got around that :)

      4. so yeah for an intermediate update, zfs-fuse doesn’t compile on uclibc (anymore?) because of missing __malloc_hook, so i had to set a glibc based appliance up :/. maybe this uclibc setup will be useful for something else..

        1. What appliance are you trying to setup? Maybe I could help you.

        2. well zfs-fuse says it all in this case. i’m lkraav@skype, perhaps we could chat, always good to have a skilled gentoo person in the contact list!

  19. Eskild Jacobsen Avatar
    Eskild Jacobsen


    This is a very nice, project. I have one suggestion though, it would be very interesting if you could upload your kernel-config and modify it to only use libata instead of ide-drivers. This way you could use sda in fstab for all drives (and get rid of that annoying hda/sda -issue), this should increase portability somewhat. Anyway thank you, for your nice work :-)


    1. I will certainly upload my kernel-config, will have to configure a generic one, will be a bit big, but if you want the kernel config for just the intel celeron/pentium family of processors, I have it perfectly set up. Will upload both, as soon as my exams are done(I have my exams on at college).

      1. Hello! your kernel config @Error 404 – Not Found

        pls, re-upload it. thanks

    2. Eskild, I have uploaded my kernel-config, take a look at the last line of the article.

  20. Hola, Todo dinбmica y muy positiva! :)

    Translated(from Spanish): Hello everything works great and very positive! :)

  21. […] This post was mentioned on Twitter by Jude Pereira. Jude Pereira said: New blog post: [going embedded with mGentoo] http://judepereira.com/blog/going-embedded-with-mgentoo/ […]