HOWTO Create an Updated Ebuild

From Gentoo Linux Wiki

[edit] Introduction

So you've found a really cool program, and check to see if it is in portage - It is, but it's not the latest version! HOW do you make a new version?

The answer can be somewhat complex for beginners, but once you do it, it's never forgotten. It will be explained in this HOWTO.

[edit] Using a Portage Overlay

Portage provides an extremely useful feature for these kind of situations - overlays. An "overlay" is a directory where you can put your own ebuilds, and they will be treated as if they were in the actual portage tree - as if you got them from emerge --sync. One important point, however, is that emerge --sync does not overwrite this directory like it does if you add something to the real portage directory.

So how do you set up an "overlay" anyhow? That's what this section is for.

[edit] Creating an Overlay

To create a portage overlay, you need to add the following to your /etc/make.conf:

PORTDIR_OVERLAY="/usr/local/portage"

To make things simple, as root execute this command:

mkdir -p /usr/local/portage && echo 'PORTDIR_OVERLAY="/usr/local/portage"' >> /etc/make.conf

This will make the directory and add the overlay to make.conf in one shot.

[edit] Making the Updated Ebuild

I will use xchat-2.0.8 as the old one, and 2.0.9 as the needed ebuild in this example, even though 2.0.9 has already hit portage outside of this HOWTO.

[edit] Locating the existing ebuild in Portage

Moving on, let's find the location of the already-in-portage ebuild, xchat in this example:

# emerge --search xchat
  *  net-irc/xchat
       Latest version available: 2.0.8
       Latest version installed: 2.0.8
       Size of downloaded files: 1,067 kB
       Homepage:    http://www.xchat.org/
       Description: Graphical IRC client
       License:     GPL-2
  *  net-irc/xchat-systray
       Latest version available: 2.4.0
       Latest version installed: [ Not Installed ]
       Size of downloaded files: 41 kB
       Homepage:    http://blight.altervista.org/
       Description: System tray plugin for X-Chat.
       License:     GPL-2

Now that we know the full name of xchat, net-irc/xchat, we can continue with our ebuild making.

[edit] Copying the ebuild to the Overlay

We can now copy the ebuild to the overlay with a new version number, but first, we need to make the right directory for it:

mkdir -p /usr/local/portage/net-irc/xchat

Now we can copy over the old ebuild to the new location:

cp /usr/portage/net-irc/xchat/xchat-2.0.8.ebuild /usr/local/portage/net-irc/xchat/xchat-2.0.9.ebuild

You can keep the same name, if you want. In this case, the overlayed ebuild will take precedence over the main one (note that a newer version always takes precedence, so when 2.0.10 hits mainline it'll be prefered over 2.0.9 in the overlay). This is useful if you want to change the way portage compiles some package, but without incrementing the version number.

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

cp -R /usr/portage/net-irc/xchat/files /usr/local/portage/net-irc/xchat/files

This is because the FILESDIR variable points to the directory containing the ebuild, with /files appended. If you are not going to be adding files you can get away with a symlink. If the two directories is on the same partition you may also want to pass -l which will hardlink the files instead of making separate copies.

Then, we need to make a digest for this new ebuild and its patches. Portage will fail (Security Violation) if there are some patches not listed in digest. You need to make a digest even if you won't use patches.

[edit] Unmasking the ebuild

Ebuilds found in overlays are considered to be "testing", so in order to get emerge to use the modified ebuild, you need to unmask it by adding a line like the following to /etc/portage/package.keywords:

[Of course use the appropriate architecture identifier in place of x86 if needed.]

[edit] Making a Digest

All you need to do to make a digest is, for example:

ebuild /usr/local/portage/net-irc/xchat/xchat-2.0.9.ebuild digest

And it will download some possibly needed files to distfiles dir and make an md5 sum of all related files (patches and files downloaded to distfiles). Usually, that's all it takes. In this particular version (2.0.8) of xchat however, there was a security hole that the ebuild patched, and in 2.0.9 it was fixed by the developers. This is where problems can pop up.

Another option can be to modify /etc/make.conf and add FEATURES="-strict"

[edit] Fixing a Patched Ebuild

We need to open up the new ebuild:

nano -w /usr/local/portage/net-irc/xchat/xchat-2.0.9.ebuild

We now find the location of our problem:

# Fix for sock5 vulnerability - see #46856
epatch ${FILESDIR}/xc208-fixsocks5.diff

But to get epatch to work we have to write into the first line of the ebuild

inherit eutils

The sock5 vuln. was fixed in 2.0.9, so we can remove its epatch, and now the ebuild should compile peacefully!

Apply this to other ebuilds, and you will have the most positively up-to-date system possible.

[edit] Adding a Patch

Sometimes you will want to add a patch to an ebuild: to enable a cool feature, to fix a bug, etc. The first thing to do is to copy the patch to /usr/local/portage/net-irc/xchat/files/, so the ebuild can access it. 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).

Now you need to get the ebuild to apply the patch. If the ebuild contains a section

src_unpack() {

then you will add the patch line to the end of this section, just before the closing } brace. Otherwise, you need to add a src_unpack section:

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

Emerge looks at the Manifest for integrity. If the ebuild size has changed it will not build. Update the Manifest with new ebuild info:

ebuild /usr/local/portage/<category>/<program>/<program-version>.ebuild digest

Note:

• unpack ${A} may be incorrect. If the ebuild inherits an eclass, you will need to use src_unpack from the corresponding eclass: e.g. if it inherits cvs, use: cvs_src_unpack in place of unpack ${A}.
• The stanza above applies the patch in ${S}, the top directory of the source tree. You may need to apply it in a subdirectory e.g. ${S}/src. If you have trouble getting the patch to work, try unpacking the sources and applying the patch by hand.
• ${S} and ${FILESDIR} are wrapped in quotes, to cater for the unlikely scenario of spaces or other troublesome characters in the file/directory names. ${A}, however, is not wrapped in quotes because it is a parameter list.
• if you get a message like "QA Notice: ECLASS 'eutils' inherited illegally"; don't panic, chances are that the dependency tracking of portage is confused because the ebuild didn't depend on eutils before and now it does. you can fix it by running:

 ebuild /usr/portage/<category>/<program>/<program-version>.ebuild depend

[edit] See Also

• Gentoo Linux Documentation - Ebuild HOWTO
• Gentoo Development Manual - Quickstart Ebuild Guide
• Installing 3rd Party Ebuilds HOWTO