Basic guide to write Gentoo Ebuilds

Portage, the heart of Gentoo, uses ebuild scripts!
In order to be able to do package management you have to define what packages are and how they download, unpack, patch, compile, install and merge (copy it from a temporary directory to your live file system) sources and/or binaries, to make it more nice we also add some useful metadata as well as USE flags, patches and more to allow one to manipulate the process the way; this definition is mostly done in an ebuild.

Ebuilds, where do they live? How do I create one?
When you had set up Gentoo, you probably remember that you had to download and unpack a Portage tree snapshot. This snapshot (which you later update when you run emerge --sync) is full of ebuilds, it is the Portage tree and once unpacked is usually located at /usr/portage.

Now, you can't just create a file /usr/portage/hello-world.ebuild and be done with it; there are several reasons:


 * 1) It is your local copy of a remote Portage Tree: If you place an ebuild in there or update an ebuild, then you run emerge --sync, your changes will be gone. Therefore, you will want to work in /usr/local/portage, in a sub directory of your home directory or in an overlay instead.
 * 2) The ebuild file is not in the right directory: An ebuild has to be located in the "package name" subdirectory of "category" directory; so, for an ebuild to work you have to place it in a directory like /usr/local/portage/app-misc/hello-world/.
 * 3) The ebuild file name has no version listed: Packages have versions, they need to specified in the file name; therefore we would like to create a file like /usr/local/portage/app-misc/hello-world/hello-world-1.0.ebuild.

So, let's create us a minimal ebuild; to keep it simple I will assume you run under root privileges, you can always use sudo if you feel like.

We recursively create the directories and cd into it ($_ recalls the last argument), then we create an ebuild out of the ebuild header which is a necessity if you want it added to the Portage tree.

This won't run yet, it requires us to define a minimal amount of variables, so let's add the following code:

Just one variable? Exactly, it is required that we explicitly state that we won't use SLOTs, which is what "0" means.

We can now install the package to our system by running:

This will manifest (create hashes, to avoid corruption), clean any present temporary work directories and (e)merge the ebuild.

Good, you have just made and tested your first ebuild, it doesn't really do much but it's a good start!

Let's make it install a file that echoes "hello world!" when being run, a classic example.
To be continued...

Useful resources

 * Gentoo Development Guide


 * man 5 ebuild


 * repoman metadata && repoman full to check for QA errors, QA keywords are explained in the last part of man repoman.


 * Ebuild Policy