Writing Ebuilds

From Gentoo Linux Wiki

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.)

[edit] 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.

[edit] 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.

[edit] Overlays

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

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 /etc/make.conf:

PORTDIR_OVERLAY="/usr/local/portage"

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

[edit] 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.

[edit] Know the Category

First, know its category, by

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

[edit] Copy to overlay

Next, create the directory for ebuild, like this

Be sure to follow the structure. It has to be /overlay/category/package.

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 =:

[edit] Patches from portage tree

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

Symlink is okay, too.

[edit] 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 FEATURES="-strict" to the emerge command. (It's possible to add this in /etc/make.conf, but it's not recommended, because it allows corrupt official portage tree.)

[edit] Example

Good example with heavy comments is found at /usr/portage/skel.ebuild.

[edit] How to Fix

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

[edit] Adding a patch

What if you have a patch at my-new-patch.patch, and want to apply it? Easy. Put the file under .../category/package/files/ Add to ebuild:

src_unpack() {
    unpack ${A}
    cd "${S}"
    epatch "${FILESDIR}"/my-new-patch.patch
}

If src_unpack is there, then put epatch after cd "${S}".

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.

[edit] Directory structure is wrong

Emerge assumes that the unpacked tarball puts the source in

S=dirname-tarball-makes

[edit] Tips

[edit] Old ebuilds

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

[edit] 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 /usr/portage/distfiles/, and make manifest.

[edit] See Also

Man page:

• man 5 ebuild

Thorough references for developers can be found:

• Official Gentoo Developer Handbook: Chapter 2
• Gentoo Development Guide

To submit you ebuilds to Gentoo, see:

• Contributing Ebuilds
• Common ebuild Mistakes in part 3, chapter 2 of Gentoo Developer Handbook should also be read.

The next articles to read after this page.

• Gentoo Sunrise Coding Standard
• Quickstart Ebuild Guide is, contrary to its name, not so easy for beginners.

If it suffices for you to use third party ebuilds, then look at Overlay

For further help, try #gentoo-dev-help on Freenode (low traffic but high quality)

Because ebuilds form parts of portage, writing ebuilds sometimes require knowledges of portage, emerge and so on.

• Portage, man portage
• man emerge
• man 1 ebuild, for ebuild command.