eclass howto

1. Introduction

Overview  

eclasses are parts of ebuilds. They are sourced ("inherited";) by ebuilds and other eclasses, to provide default settings and functions across many similar ebuilds. As in OOP, this is used to ensure maximum code reuse among similar ebuilds.

This first section shows briefly how to write an eclass. The second is a detailed overview of all the existing eclasses. The third explains how to write a KDE ebuild using the kde group of eclasses.

Example  

Here is a fictive sourceforge.eclass, designed to provide homepage and download locations to sourceforge.net-hosted projects:

# Copyright 2001-2002 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License, v2 or later
# Author Dan Armak <danarmak@gentoo.org>
# $Header: /home/cvsroot/gentoo-x86/eclass/sourceforge.eclass,v 1.12 2002/03/27 22:33:53 danarmak Exp $
# This eclass sets $HOMEPAGE and $SRC_URI to the standard vaules for
# sourceforge.net - hosted projects.
ECLASS=base
HOMEPAGE="http://${PN}.sourceforge.net/"
SRC_URI="http://download.sourceforge.net/${PN}/${P}.tar.gz"
   

The first four lines are headers, just like those in any ebuild. The next two lines are a short description of the eclass. The seventh line set $ECLASS to the eclass's name, which is useful for some applications not seen in this example. The rest of the code does the actual work - setting SRC_URI and HOMEPAGE.

There you go  

This is all you need to know to actually write eclasses. Put your new eclass in /usr/portage/eclass/, and put these two lines at the beginning of your ebuild:

. /usr/portage/eclass/inherit.eclass || die
inherit sourceforge
   

The first line is only needed for backward compatibility with <=portage-1.8.8, i.e. the rc6 profile. The new 1.8.9 portage tree contains an inherit() function, but the old one doesn't and so we have to manually source inherit.eclass which provides it. This backward support will be discontinued on April the 25th, one month after the release of portage-1.8.9_pre32 for the 1.0 profile (the first portage to include inherit() and some other eclass-supporting elements).

Oh, and you can inherit several eclasses at the same time by saying:

inherit eclass1 eclass2 ...
   

...but watch their order!

2. The current eclasses

inherit.eclass  

This is the basic eclass. It should always be present (i.e. inherited). No other eclass inherits from it, however: an inheriting ebuild needs to inherit it explicitly before it does anything else, by saying:

. /usr/portage/eclass/inherit.eclass || die
   

Eclasses do not need this first line, since they are always sourced from an ebuild which already has it.

The second line would typically be:

inherit <list of eclasses>
   

inherit()

This eclass defines the inherit() function which handles sourcing of eclasses:

ECLASSDIR=/usr/portage/eclass
inherit() {
    while [ "$1" ]; do
        source ${ECLASSDIR}/${1}.eclass
    shift
    done
}
    

This function simply sources files from a hard-coded location. If, in the future, we will decide to move eclasses to a different location, any name-to-file resolution code will go in here.

EXPORT_FUNCTIONS()

Explanation: suppose A.eclass and B.eclass both define src_compile. If you inherit both A and B you'll get a different src_compile depending on the order in which you inherit them. That's ok, you're supposed to keep track of your inheritance order. But you may want to call either of the two src_compile's explicitly.

So, every eclass adds to the functions that it defines a prefix. For example, A.eclass will define A_src_compile(), and B.eclass will define a B_src_compile(). That way, the ebuild can call either function and know what it'll get.

This raises a new problem: we need a function called src_compile so that the ebuild doesn't need to explicitly call something_src_compile. This is where EXPORT_FUNCTIONS() comes into play:

EXPORT_FUNCTIONS() {
 
        while [ "$1" ]; do
            eval "$1() { ${ECLASS}_$1 ; }" > /dev/null
        shift
        done
 
}
    

Every eclass at its beginning sets $ECLASS to its name (e.g. "A"; or "B";). Then it calls EXPORT_FUNCTIONS with the list of functions it provides. For example, if you call

ECLASS=foo
EXPORT_FUNCTIONS src_unpack
    

The EXPORT_FUNCTIONS will call eval on the following string:

src_unpack() { foo_src_unpack() ; }
    

Function sections  

One rarely uses predefined functions as-is; you usually want to extend them. Once they have unique names (foo_src_unpack) it's easy to add code that executes before or after them. Function sections break them down and allow code to execute between any two sections.

The implementation is simple. Let's take as an example the src_compile() function from base.eclass. It looks like this:

base_src_compile() {
    ./configure || die
    make || die
}
   

Here is the same function, divided into sections:

base_src_compile() {
 
    [ -z "$1" ] && base_src_compile all
 
    while [ "$1" ]; do
        case $1 in
            configure)
                ./configure || die;;
            make)
                make || die;;
            all)
                base_src_compile configure make;;
        esac
    shift
    done
 
}
   

The code has been divided into two "sections";: configure and make. In our simple example, they correspond to the two commands in the original function.

In the center of the new function is a while;case...esac;shift;done block. This block matches the parameters to the functions with the defined section names and executes the corresponding lines of code.

The special case all calls the same function recursively with a list of sections in order. It's up to the eclass's author to maintain this list, which is very important.

The line before the block says that a call without parameters should be treated the same as a call with the single parameter all. As you see, this function recurses a lot. Note, however, that the call base_src_compile configure all make is also legal; it will execute base_src_compile configure configure make make.

Now, in your ebuild (or eclass) that inherits from base.eclass, you get the stub function src_compile which calls base_src_compile without parameters. This makes base_src_compile execute all, that is, all its sections. You can leave it as-is. If you wish to extend it, you define a new src_compile and call base_src_compile a section at a time:

src_compile() {
    myfunc1
    base_src_compile configure
    myfunc2
    base_src_compile make
}
   

Where myfunc{1,2}" is any code you want to execute between the sections.

The only way to know what functions contain what sections is to read the eclasses.

A final note: not all functions execute all their sections when called with all or without parameters. Some sections may be non-standard and must be called explicitly. The only such section right now is base_src_compile patch.

debug.eclass  

Adds verbose output debugging functions. Is inherited by inherit.eclass. All eclasses call these functions a lot, which makes them look ugly but helps a great deal in tracing stuff, since there is no bash script debugger/ide/step-by-step interpreter AFAIK (except for bash -x).

Look at it to see the functions it provides, they are simplistic.

You can export ECLASS_DEBUG_OUTPUT=";/dev/stdout"; to get the output with your other msgs while merging. Unfortunately opening /dev/stdout for writing violates the sandbox. I'm not sure how to bypass this (FIXME!).

Let's add typical debug output statements to our sample function from the function sections explanation:

base_src_compile() {
 
    debug-print function $FUNCNAME $*
    [ -z "$1" ] && base_src_compile all
 
    while [ "$1" ]; do
        case $1 in
            configure)
                debug-print-section configure
                ./configure || die;;
            make)
                debug-print-section make
                make || die;;
            all)
                debug-print-section all
                base_src_compile configure make;;
        esac
    shift
    done
 
    debug-print "$FUNCNAME: result is $RESULT" #yes I know there is no $RESULT in this sample function
}
   

base.eclass  

This eclass defines some default variables and functions, similar to those you'd get by default in a non-inheriting ebuild (starting with a recent portage), e.g. src_unpack() { unpack ${A}"; }".

It is inherited by higher-level eclasses like the kde ones.

Note that in base_src_unpack there is one non-default section (i.e. it doesn't execute for section all). It is called patch and it looks like this:

cd ${S}
patch -p0 < ${FILESDIR}/${P}-gentoo.diff
   

autotools.eclass  

This is made and maintained by Azarah. To quote his comments:

This eclass was made to bridge the incompatibility problem of autoconf-2.13, autoconf-2.5x and automake-1.4x, automake-1.5x. Most packages needs autoconf-2.13 and automake-1.4x, but cannot work with the latest versions of these packages due to incompatibility, thus when we have a package that needs the latest versions of automake and autoconf, it begins to get a problem.

Read the eclass for more info. AFAIK it has no relationship whatsoever to an of the other eclasses. Contact Azarah for any further info. (Azarah, you're welcome to fill in here).

kde.eclass  

Used by all kde apps, whether directly or indirectly. (Not by apps with optional kde functionality though.) This is a higher-level eclass, which is intended to provide not only sensible defaults but functions which can be used as-is more often then not. In fact, none of the high-level kde-* eclasses which inherit from here change the functions in any way, and the ebuilds rarely do so. This eclass contains the meat of the kde eclass system, while virtual and base can be said to provide the skeleton.

It inherits autoconf, base and depend.

Read it to find out what it defines. It is quite self-explanatory.

Briefly, it handles all standard kde apps that use GNU standard configure/make/make install cycles. It handles all the std. configure options e.g. qtmt.

Note: some kde apps, like widget styles and i18n packages, do not need to compile anything. Therefore kde.eclass does not inherit c. These packages can then inherit straight from here. All other packages, which need to compile c code, should inherit from kde-base.eclass.

functions.eclass  

kde-related (used to be kde-dirs.eclass)

A short explanation about the current multi-kdedir scheme:

$KDE{2,3}"DIR and $KDELIBS{2,3}"DIR are set in make.globals (and can be overridden in make.conf). Their default values are /usr/kde/{2,3}".

A package that identifies itself as a kde2 package (see below) will use the kdelibs installed in $KDELIBS2DIR and install itself into $KDE2DIR. Same goes for kde3. NOTE: separating kdelibs from kde apps and any other non-default KDEDIR stuff is untested and unsupported.

As for qt, the latest 2.x, 3.x version lives in /usr/qt/2,3 respectively.

The inner works of the system needn't be described here. A few weeks ago all this scheme was changed out of recognition, but no ebuilds needed to be changed, only eclasses. That speaks for their success.

This eclass provides two pairs of functions: need-kde(), need-qt() and set-kdedir(), set-qtdir(). These functions handle the details of the multi-qt and multi-kdelibs schemes.

The need-* functions are called with a parameter which is the version number required. They then add the corresponding dependencies to DEPEND and RDEPEND, and set the variables kde_version and qt_version which are used by the set-*dir functions. If no parameter is passed, a version number of 0 (zero) is used, meaning that any version will satisfy the dependency.

It is important to call these functions from the main part of the ebuild (i.e. not from a function), so that any changes to DEPEND and RDEPEND affect emerge.

The set-* dir functions are both called from the beginning of the configure section of the kde_src_compile() function. They set KDEDIR and QTDIR appropriately. That's all your ebuild should need.

In a ebuild with optional kde support, you inherit kde-dirs directly (and no other eclass). You should then call both need-* and set-* yourself.

kde-dirs.eclass also contains several helper functions you shouldn't need to use directly.

newdepend()

This function simply adds all parameters to both DEPEND and RDEPEND, saving you the trouble of writing and maintaining two lists of dependencies.

If called with a special parameter, it adds predefined dependencies. These special parmeters exst as of now:

This function encourages developers to maintain comprehensive DPEND strings. Especially, many ebuilds have no RDEPEND strings, which will be a problem once we have unmerge functionality that knows about dependencies.

kde-base.eclass  

Meant for standard kde apps; nearly all ebuilds use it. Inherits kde. Calls newdepend /c. Sets HOMEPAGE=apps.kde.com.

kde-i18n.eclass  

Meant for the kde-i18n-* packages. Niche use.

In fact, all kde-i18n ebuilds are completely identical and so all they have to do is inherit from this eclass. Their ${P}" does the rest.

Inherits kde, kde.org. Makes a few differences, such as PROVIDE virtual/kde-i18n, correct $S, HOMEPAGE and DESCRIPTION.

koffice-i18n.eclass  

Meant for the koffice-i18n-* packages. Niche use. Very similar to kde-i18n.eclass.

All kde-i18n ebuilds are completely identical and so all they have to do is inherit from this eclass.

kde-dist.eclass  

Meant for the base kde distribution packages in kde-base/*. Inherits kde-base, kde.org. Adds the correct DESCRIPTION and HOMEPAGE and kdelibs-${PV}" deps. The simpler/smaller kde-base/ packages (e.g. kdetoys) make no changes at all; most of those that do only add deps.

kde-cvs  

This is only included with the kde3-pre ebuilds, and doesn't live in portage. See http://www.gentoo.org/~danarmak/kde3-pre.html.

It provides a new src_unpack which sets SRC_URI=";"; and copies the sources from a location hardcoded in the eclass. Useful if you have a local copy of the kde cvs modules.

It does not run cvs.cvsup itself beacuse that would violate the sanbox. I plan to add a sanbox_allow command and implement that functionality.

kde-pre  

This is only included with the kde3-pre ebuilds, and doesn't live in portage. See http://www.gentoo.org/~danarmak/kde3-pre.html.

For pre-release ebuilds, which have underscores in their portage names (3.0_beta1) but not in their source archives' names (3.0beta1.tar.gz). Removes any underscores from $SRC_URI and $S.

I'll probably add this to portage if there'll be a reason to do it (i.e. a pre-release kde ebuild in portage).

3. The inheriting ebuilds

A typical kde app ebuild  

<header lines>
. /usr/portage/eclass/inherit.eclass || die
inherit kde-base
# Some ebuilds end right here. Others need some customization.	
# Add any extra deps. Remember: *always* extend variables, never override!
DEPEND="$DEPEND foo/bar"
RDEPEND="$RDEPEND bar/foo"
# This will add a dep to both DEPEND and RDEPEND
newdepend "foo? ( bar )"
# This adds extra arguments to $myconf, which is passed to configure
myconf="$myconf --with-foobar"
# extend src_unpack
src_unpack() {
    base_src_unpack all patch   # Patch from ${FILESDIR}/${P}-gentoo.diff
    # some more changes
    dosed -e 's:1:2:' ${S}/foobar
}
   

A typical optional-kde-functionality app ebuild  

To your normal ebuild, add the following lines. Prefix each line with "use kde &"&"";, or create whole "if [ "`use kde`"; ]"; then; fi"; blocks. To the general section, add:

. /usr/prtage/eclass/inherit.eclass
inherit kde-dirs
need-kde $version # minimal version of kde your app needs
   

If you only need (optional) qt support, do the same, but call need-qt. You can also disregard eclasses entirely, but make sure to add the correct QT dep; the correct format as of now is e.g. =x11-libs/qt-2* for qt2.x.

Have fun! :-) - danarmak