path: root/eclass/doc/eclass-howto.txt

eclass howto

Dan Armak

Updated for 20020206

1 Warning

The eclasses have been modified and the documentation isn't
up to date, to be fixed shortly.

2 Introduction

eclasses are parts of ebuilds; that is, they have the same
syntax ebuilds do, but do not define all the required variables
and functions. ebuilds can inherit from eclasses, and eclasses
can inherit from other eclasses. As in OOP, this is used
to ensure maximum code reuse among similar ebuilds.

This inheritance is implemented via simple bash sourcing.
So, when you 'inherit" something its
functions and variables override your own. For this reason,
variables and functions are usually extended and not just
set (more on this later).

The most uniform group of ebuilds is the kde apps. These
were accordingly selected to be the test case for eclasses,
and I believe I can now say the test has been successful.
Eclasses for non-kde ebuilds may follow, but there are no
concrete plans as of this time.

Because of the current customisable KDEDIR (KDE?DIR, KDE?LIBSDIR)
scheme, all kde ebuilds (including ebuilds for apps with
optional kde support) must use the eclasses. As a minimum,
inherit kde-dirs to get the set-qtdir(), set-kdedir() functions.

Section two explains how eclasses work; section three gives
an example of a typical inheriting ebuild, and another of
an ebuild for an app with optional kde functionality.

3 The eclasses

The best way of becoming familiar with the current eclass
structure is an explanation of what each eclass does.

3.1 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>

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.

3.2 virtual.eclass

This is sourced from inherit.eclass, and thus should always
be present before all other eclasses. It defines 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() ; }

virtual.eclass defines all the ebuild functions (src_unpack,
src_compile, src_install, src_preinst, src_postinst, src_prerm,
src_postrm) as empty functions that do nothing (except call
debug_print_function, see debug.eclass).

3.3 Function sections

Although this is not an integral part of eclasses, this is
a good place to introduce 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.

3.4 debug.eclass

Adds verbose output debugging functions. Is inherited by
virtual.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 (if you know of one, tell me!).

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

}

3.5 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

There is also a helper function provided by base.eclass,
called newdepend(). It simply adds all parameters to both
DEPEND and RDEPEND, saving you the trouble of writing and
maintaining two lists of dependencies.

3.6 c.eclass

Adds gcc and glibc to DEPEND and RDEPEND.

3.7 autoconf.eclass

Adds make/automake/autoconf to DEPEND.

3.8 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 feel in here).

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

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

3.11 kde-base.eclass

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

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

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

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

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

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

4 The inheriting ebuilds

When in doubt, look at other inheriting ebuilds, or ask.

4.1 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

}

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

Have fun! :-) - danarmak