Gentoo for All the Unusual Reasons

You might think of Gentoo as a bleeding-edge distribution for development workstations, but the simple packaging system can make it a good choice for any production system that needs to stay up to date.

and you have your new version.

Gentoo has copies of the source tarballs required for all of its various packages on its mirrors around the world. Normally, Portage gets the source from one of them. If, however, you're building something that isn't in Gentoo's mirrors, no problem. Portage simply reaches out to the original upstream download site.

Portage uses md5sums to ensure that you get uncorrupted downloads. That's what the third command above (ebuild ... digest) is for; it downloads the source and then computes the md5sum for you. Because you're the one doing the version bump, it's up to you to make sure you actually have an uncorrupted download. Therefore, you should probably do ebuild ... unpack first to get the download, make sure it's okay, then do the digest command.

Finally, if you want a software package your OS doesn't provide, you have to write your own. With Gentoo, writing a custom .ebuild is easy.

All about ebuilds

Gentoo's package descriptions are written in bash. The various instructions go in functions that are called by Portage along the way. The major ones are:


and they are called in order. To tell Portage how to build your software, write functions for each of the steps, proceeding each with a bit of information, such as the SRC_URI discussed previously.

To compile your sources, you might use:

src_compile () {
        ./configure --prefix=/usr

The amazing thing about these shell scripts is they can provide sensible defaults by overloading functions. In fact, the default for src_compile() is pretty much what I showed above, which is perfect for many packages. In fact, you could write an ebuild that relies on the defaults and has no custom functions defined at all.

Sometime you might want to ./configure a package differently depending on what sort of system you have. Portage has an environment variable called USE, set in /etc/make.conf and overrideable on the command line, that contains tokens you can use to describe and customize your system. Say you've got a package that can be told to build differently depending on whether you want, say, X Window System support or IPv6 support. Your src_compile() function might look something like this:

src_compile () {
        use X    && conf="${conf} --with-x"
        use ipv6 || conf="${conf} --without-ipv6"

        ./configure --prefix=/usr ${conf}

You can see various features of shell scripting being used. In this example, if your system has X on it, this package is told to go ahead and build in X support. If it's a server, and you don't need any of that, your software is built without that extra overhead. The USE variables be can overridden on the command line, so you have even more precise control if you need it.

src_unpack() works the same. If you don't include one, Portage plows ahead, untars the source tarball in the default place, changes directories and sets the working directory environment variable, $WORKDIR accordingly. On the other hand, if something unusual has to happen—say, a patch is applied— you then can write a simple unpack function yourself:

src_unpack () {
        unpack ${A}
        epatch ${FILESDIR}/fixit.patch


I conclude with a full example. I had a client that exclusively used's implementation of the SSH2 protocol. So, I needed to install it on a number of machines. See Listing 1.

An ebuild starts by setting a number of environment variables, including:

  • SLOT: typically used for libraries. When an ebuild author knows multiple versions of the same packages can be installed on a system at the same time, he or she can assign a slot number to distinguish them. On one of my systems I have Berkeley DB version 1.85 (SLOT 1), version 3.2.9 (SLOT 3), version 4.0.14 (SLOT 4) and even version 4.1.25_p1 (SLOT 4.1). Plenty of software is out there that was written to use the older APIs; there's no reason they shouldn't be able to be installed. If a newer version in the 4.0 series is released as stable, say version 4.0.17, as long as it stays in SLOT 4 my system offers me the upgrade from 4.0.14, without removing the other versions installed. Admittedly, Berkeley DB is one of the more complicated examples out there, but it demonstrates the power behind Gentoo's slot implementation. Most ebuilds don't need any of this and say SLOT=“0”.

  • KEYWORDS: where you indicate support for different architectures. In the example, I've shown that this ebuild is known as working and stable on x86 series platforms. The ~ in ~ppc means that it's masked. I know previous versions build on PowerPC systems, but I don't have one handy to test with, so others may want to take caution before deciding to install this version. In the official Portage tree, an ebuild like this stays in this state for a few weeks until people using PowerPCs are able to test the ebuild. After several positive reports, the ebuild would be unmasked.

  • DEPEND, RDEPEND: where dependencies are listed. It's a fairly complete grammar and particular versions of necessary packages can be listed. The most common modifiers are >=, which indicates that at least that version must be installed, usually because of an API that our program depends on; and !, used to show that this package conflicts with the presence of another. Both cannot be installed at the same time.

  • RDEPEND: runtime dependencies, things that have to be installed to use the package. DEPEND are dependencies to build it in the first place; the difference shows up only when you're installing binary packages built elsewhere.

  • RESTRICT: various fine-grained controls of Portage's features are possible. In this case, because this is an ebuild I cooked up myself, I use nomirror to tell emerge not to bother looking in Gentoo's family of mirrors. This doesn't actually imply that I can't use a mirror provided by the upstream authors. In fact, if you look at SRC_URI, you'll see that I've listed a mirror close to me where I know I should be able to get the .tar.gz I need.

Then, we proceed to overloading the various functions that control how the package is built. The src_compile() function is the interesting bit. I've taken the example above and fleshed it out a bit. You can see that some options are controlled by USE variables, while others we specify, such as where we want the configuration files to go. We don't really need the die failure messages, but they illustrate how we have full semantics and the power of a shell script available.

Finally, in the src_install() function, we could have relied on the default, but on my system, files in /etc/init.d don't have .rc appended to them. More important, this is intended to replace OpenSSH on the target systems where this ebuild is deployed. Therefore, I wanted to be clear that the RC script was different from the one that OpenSSH put in place.

Portage provides a rich library of helper functions that simplify the execution of common tasks. We take advantage of one to say where we want the RC script to go and to see that it is marked executable. You now place the ebuild into your local overlay of the Portage tree and tell emerge to do its thing.

This example only scratches the surface. For more details, see, the output of emerge --help and the man pages for ebuild(1) and ebuild(5) on any Gentoo system.


-- Andrew Frederick Cowie Operational Dynamics Consulting Pty Ltd


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

interesting article

Anonymous's picture

An interesting article. I've been thinking of playing with Gentoo for a while. The idea of easily being able to build customized packages appeals to me, as it's seems to be like rocket science on Debian...

no so hard

damaki's picture

Just 2 commands for any standard source (./configure based) :
dpkg-build -rfakeroot

Nothing else...

I have seen debian boxes tota

Anonymous's picture

I have seen debian boxes totally corrupted by this kind of installation

Debian is particullary picky about extern packages, gentoo will build any package acording to your new choice if needed.

What if you do that for kdelibs ? gtk ? glibc ? the system will suffer, not on gentoo !

Another overlooked benefit is

Anonymous's picture

Another overlooked benefit is Security. Gentoo Hardened includes tons of excellent security features including SELinux, and you are not limited like other security-focused distributions. You can install basically any software on Linux, and the binary is automatically hardened; just check the configuration.

I use gentoo on every compute

Anonymous's picture

I use gentoo on every computer i got on my home, If you want an easy to install gentoo based distribution with graphical instalation you should check Vidalinux Desktop. Is based on gentoo but is using Redhats anaconda to install everything. http::// :-D


Anonymous's picture

good golly, did you see the minimum system requirements?
Minimum Supported Configuration:
AMD Athlon XP or Pentium 4 compatible processor, 1.0 Ghz; 10-GB hard disk; 256-MB RAM; 800x600 screen resolution

Recommended Configuration:
AMD Athlon XP or Pentium 4 compatible processor, 2.0 Ghz or faster; at least 20-GB hard disk; at least 512-MB RAM; 1024x768 screen resolution or better

where gentoo's minimum system requirements are:
Hardware Requirements
CPU i486 or later
Memory 64 MB
Diskspace 1.5 GB (excluding swap space)
Swap space At least 256 MB

does anaconda really take this much power?

I've been using Linux for ove

Anonymous's picture

I've been using Linux for over 10 years and Gentoo was the distro to pull me away from Win32 for daily use. It's takes a little work for the initial install and the larger compiles like kde. Once installed its great. Easy to use, maintain and update. Seems you have what you need in the version your looking for, including its dependances.

Great Distro. Next Debian & Slackware (Slack being my 1st Linux distro) then Mandrake and Suse. All Great.

The main thing is to Enjoy Linux no matter the distro!

hallo this sucks your link go

Anonymous's picture

hallo this sucks your link goes straight to M$

Nah he accidently added two c

Anonymous's picture

Nah he accidently added two colon's, which for some reason is redirecting to you know where.

Stephane's picture