HOWTO_Installing_3rd_Party_Ebuilds

Introduction

This tutorial shows how to install ebuilds found on third-party sites or in the Gentoo Bugzilla that are currently not in the Portage tree.

As an example, x11-drivers/nvidia-drivers-100.14.11 will be installed.

General Concepts

All ebuilds have the following attributes:

• A category, e.g. app-accessibility
• A package name, e.g. gcc or nvidia-drivers
• A version number, e.g. 1.05_beta3 or 100.14.11

It is very important to specify these attributes correctly.

Local Portage Overlay

The first thing to do is set up a local overlay directory. Add the following line to /etc/make.conf

PORTDIR_OVERLAY="/usr/local/portage"

This directive will allow you to safely store your custom ebuilds, because emerge --sync removes any non-official files from the Portage tree (usually /usr/portage).

You can also install multiple overlays, e.g.:

PORTDIR_OVERLAY="/usr/local/portage"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-bmg-main"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-bmg-gnome"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-gentoo-de"
PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage-fluidportage"

Where each PORTDIR_OVERLAY entry points to the root of the rsync tree acquired by gensync (app-portage/gentoolkit-dev).

The reason for putting each entry on one line is to make it easy to comment-out any particular source of overlays. Alternatively, put all entries in one line, separating each entry with a space:

PORTDIR_OVERLAY="/usr/local/portage-bmg-main /usr/local/portage-bmg-gnome"

See Local Portage Overlay for further information.

Finding the Ebuild

You can consult the articles TIP Overlays and Search_Bar_Plugin to get ebuilds from overlays. You can also get ebuild files directly from the gentoo bugzilla or just search the web for "<my program> ebuild".

Download the Ebuild

When placing the ebuild in /usr/local/portage, you must keep a similar structure to that of /usr/portage - category/program/program-version.ebuild

The category must match one of the lines in /usr/portage/profiles/categories

To download the ebuild, first look at the list of attachments and note that the second attachment file has a URL of http://bugs.gentoo.org/attachment.cgi?id=122958

Create the initial directory structure for the ebuild, and download it:

# mkdir -p /usr/local/portage/x11-drivers/nvidia-drivers
# cd /usr/local/portage/x11-drivers/nvidia-drivers
# wget -O nvidia-drivers-100.14.11.ebuild http://bugs.gentoo.org/attachment.cgi?id=122958

Unstable Packages

The new ebuild will likely be masked by keyword, so unmask it as is described in man portage, done by first opening /etc/portage/package.keywords in your favorite text editor.

If the directory (or the file) doesn't exist, you can safely create it:

# mkdir /etc/portage

Add the following line to /etc/portage/package.keywords, replacing <category> with the category the new ebuild is in (e.g. app-portage), and replacing <package> with the name of the package (e.g. gentoolkit).

<category>/<package>

For nvidia-drivers:

x11-drivers/nvidia-drivers

Or, to mark only this specific version of the package as unstable: (note the equals sign at the start of the line)

=<category>/<package>-<version>

For nvidia-drivers:

=x11-drivers/nvidia-drivers-100.14.11

Script Safety

An ebuild is a bash script run with root permissions, and can trash your system. A wise precaution, which will help to avoid overwriting existing files, is to have collision-protect enabled in /etc/make.conf, e.g.:

FEATURES="collision-protect ccache parallel-fetch"

The sandbox, which provides a bit more protection, is enabled by default, which can be confirmed by:

# emerge --info | grep FEATURES

However, it is most important to read the ebuild, using your favourite text editor, to see what it does. If it tries to delete files in e.g. pkg_postinst, then there is no protection - the bash code will be executed with root permissions.

Once the script has been judged safe to execute on the PC with root permissions, digest it to fetch all the files specified in its SRC_URI.

# ebuild nvidia-drivers-100.14.11.ebuild digest

Files Subdirectory

Ebuilds often make use of their own ebuild-specific files, usually for patches to the source code. Such files are contained in its FILESDIR. To perform a quick check:

# grep FILESDIR *.ebuild

To copy the files from the Portage tree to the local overlay:

# cp -rf /usr/portage/x11-drivers/nvidia-drivers/files/* /usr/local/portage/x11-drivers/nvidia-drivers/files/

It is unlikely, but not impossible, that there are further subdirectories under files, hence the -r in the above command.

Other files which are intended to be placed in the files subdirectory might exist in the Attachments section of the bugzilla entry, so do not blindly assume that the ebuild author has made a mistake if the emerge fails (especially with an error message indicating a missing file) - look inside the ebuild at what it is doing, and what files it is using, and copy the needed files into the local ebuild's files subdirectory if that is where the ebuild is trying to find them. As with the ebuild file, look inside the files at their contents, using your favourite text editor, to check that they are not malicious.

After making any changes to the ebuild's directory tree, digest the ebuild again to update its Manifest file, which Portage checks to guard against unauthorized tampering with the ebuild's files.

# ebuild nvidia-drivers-100.14.11.ebuild digest

Note that if the ebuild uses a source URI other than the normal Gentoo mirror(s) specified in make.conf (the ebuild will contain a SRC_URI=<site> line) you will see the ebuild attempt (and fail) to download the source from all the Gentoo mirror(s) listed BEFORE attempting to get the source from the 3rd party URI listed in the ebuild. This is normal behaviour, simply allow the attempts to run, and eventually the correct site will be tried.

Install the Ebuild

To install the ebuild:

# emerge nvidia-drivers

To ensure that a specific version is emerged:

# emerge =nvidia-drivers-100.14.11

If the package name exists in more than one category, specify the category also:

# emerge x11-drivers/nvidia-drivers
# emerge =x11-drivers/nvidia-drivers-100.14.11

Temporary Space

If an emerge fails and the emerge is retried, Portage tries to be "helpful" by deciding whether to reuse its temporary storage area (which will default to /var/tmp/portage/x11-drivers/nvidia-drivers-100.14.11), which can potentially cause a perfectly good ebuild to fail, so clear it out before re-running emerge, with:

# rm -rf /var/tmp/portage/*

Do not run this command while emerging a package.

Useful Commands

To use the extremely useful commands shown below, first emerge the packages containing them:

# emerge -n genlop gentoolkit

List the versions available and installed:

# equery list -p -o -e nvidia-drivers

Show the files installed by a package:

# equery files nvidia-drivers

Show the history of emerges:

# genlop -l

See Also

From Gentoo-Wiki:

• TIP Sync your private overlay - keep your overlay on several PCs
• TIP Overlays - list of various sources to get more ebuilds
• HOWTO Create an Updated Ebuild - how to make a new version

From Gentoo Forums:

• searchportage script - to find actual examples of ebuild commands in the Portage tree. Alternatively, to install a version of qgrep which supports overlays:

# emerge =app-portage/portage-utils-0.1.28

From Gentoo Linux Documentation:

• Ebuild HOWTO
• Gentoo Development Guide
• Contributing Ebuilds

Others:

• Gentoo Bugzilla