Writing Ebuilds

In this page, how to write ebuild files is explained. For ebuild commands, document currently lacks on Gentoo wiki.

(For contributers: several thorough documents for developers are already available. This page should give practical informations for users, including introductory materials.)

Ebuild is a text file
Ebuilds are Gentoo's packages. Unlike debian .debs and redhat .rpms, ebuilds are simply scripts instead of archives. Hence, if you want to create an ebuild for a package, you simply write an ebuild script.

Easiest: Updating an existing ebuild
The common and (luckily) the easiest way to prepare an ebuild is to update the ebuild in official portage tree, where the latest version of the software is released, but the ebuild is not up-to-date.

Overlays
You have to put your ebuilds not under ; it's for official portage tree, and not for private use. (You can put one, but it will be erased by .)

Instead, create an overlay directory somewhere - that's where your ebuilds are hosted. To create a portage overlay, you need to add the following to your :

Old location was. Pls see : 

Now commands like, etc will take your overlay into account.

Making the Updated Ebuild
In this example, imaginary package foo-zilla-2.0.8 is the old one, and 2.0.9 is the ebuild you want.

Know the Category
First, know its category, by or

And you know it's www-client. Ok.

Copy to overlay
Next, create the directory for ebuild, like this

Be sure to follow the structure. It has to be.

Now, copy the ebuild:

You can keep the version unchanged, if you want. In this case, the overlayed ebuild will take precedence over the main one. This is useful if you want to change the way portage compiles some package, but without incrementing the version number.

Note also that a newer version is always chosen, so when 2.0.10 hits mainline it'll be prefered over 2.0.9 in the overlay. You can always specify the exact version to emerge with prefix =:

Patches from portage tree
If you plan to keep some patches from the old ebuild, you need to copy them:

Symlink is okay, too.

Generate manifest
Finally, create 'manifest, or security authorization file.

If you edit the ebuild, each time you have to make the manifest. At this point, the source is downloaded.

An alternate is to put the prefix to the emerge command. (It's possible to add this in, but it's not recommended, because it allows corrupt official portage tree.)

Now will build. Enjoy!

Example
Good example with heavy comments is found at.

How to Fix
Sometimes, some fixes are necessary. Don't forget to produce the manifest after you edit ebuild or added patches.

Adding a patch
What if you have a patch at, and want to apply it? Easy. Put the file under Add to ebuild:

If  is there, then put epatch after.

Also, add inherit eutils near the beginning of the ebuild so that the ebuild can use epatch (if there's already an inherit line, make sure it contains eutils).

Don't forget to update manifest:

Note: if the ebuild inherits cvs, for example, you have to use: cvs_src_unpack in place of unpack ${A}. Another example of this kind is git.

Directory structure is wrong
Emerge assumes that the unpacked tarball puts the source in, in the above example. If this is not the case, add the line S=dirname-tarball-makes at earlier parts of ebuild.

Old ebuilds
Old ebuilds, i.e., ebuilds once in official portage tree but deleted now, can be obtained at Gentoo source repository -&gt; gentoo-x86. (All architectures' ebuilds, not only x86, are stored there.)

Using your source
By default, ebuilds assumes that source tarball is somewhere online. If you want to use your source, say my-zilla-1.0, then put it at, and make manifest.

A real world ebuild example
With a currently unsigned ebuild found at, can be found in Talk:Writing_Ebuilds

You should be able to easily do all the tricks explained above and get that real package emerged in a matter of minutes.