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

eclass howto

Dan Armak

Updated for eclasses v3.3

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

The most similar group of ebuilds is the kde apps. These
have been selected to be the test case for the first incarnation
of eclasses. Inheriting ebuilds are available for all of
kde-2.2.1 (as kde*-2.2.1-r1), kdevelop-2.0.1 and koffice-1.1.
Others will follow.

Please read news.txt for an abstract of changes between versions
of the eclasses.

Section two explains how eclasses work; section three explains
how to write inheriting ebuilds.

1.1 Notes on this document

* ebuild variables/functions refers to those used in std.
  ebuilds e.g. $S, $P, src_unpack()...

* Versioning: I suppose I could have made, instead of versions
  1, 2, 3, 3.1, 3.1 versions 0.1, ... 0.3.1, or maybe 0.0.3-1.
  Usually I would. Not sure why I didn't. Too late to change
  it now.

2 The eclasses

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

2.1 inherit.eclass

Defines inherit() function which handles sourcing of eclasses.

Syntax of inheriting: we define a simple function inherit():

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 or to introduce more "formats"
(like drobbins' projected xbuilds), any name-to-file resolution
code will go in here.

Every inheriting ebuild begins with these two lines:

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

inherit <list of eclasses> || die

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

2.2 virtual.eclass

Defines empty variables and functions; defines EXPORT_FUNCTIONS().
Also inherits debug.eclass so that everyone gets that.

This eclass is inherited by most other eclasses e.g. base,
kde*. As a rule, any eclass that defines some of the base
functions needs it. Therefore the only ebuilds which don't
get it are the ones that only inherit one of the smaller
eclasses e.g. c, autoconf.

It defines all ebuild vars and funcs to be empty.

It also defines the EXPORT_FUNCTIONS() function which looks
like this:

EXPORT_FUNCTIONS() {

    while [ "$1" ]; do

        eval "$1() { ${ECLASS}_$1 ; }" > /dev/null

    shift

    done

}

This means that after foo.eclass has defined e.g. src_unpack()
and src_install(), it says:

ECLASS=foo

EXPORT_FUNCTIONS src_unpack src_install

Actually, the ECLASS setting is put at the beginning of the
eclass, directly after the inherit statements. It will in
the future be used by other functions as well. Someday we
will (I hope) adapt the portage ebuild filename->name algorithm
and get the ECLASS setting the same way we do $P and $PN.

EXPORT_FUNCTIONS() creates stub functions called ${ECLASS}_blah
for every parameter blah passed to it. The stub function
does nothing but call blah.

When you inherit more than one eclass (almost always), your
ebuild functions are those defined by the 1st eclass inherited.
Since eclasses usually inherit other eclasses, you do not
want to keep track of that. Instead, you prefix all your
functions from foo.eclass with foo_, or ${ECLASS}_. This
way, people can call a specific function from a specific
eclass and know what they are going to get.

Because you still want default functions to be defined with
the original ebuild names, you call EXPORT_FUNCTIONS() at
the end of every eclass. This makes sure that the default
functions you passed as parameters are stubs calling the
ones you just defined.

I looked at adding ${EBUILD}_ instead of literal strings
to the actual function definitions, but the bash syntax
for that is too ugly.

2.2.1 ebuild 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

}

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. Current
examples include base_src_unpack patch.

A more final note: the eclasses also include some debug statements,
which are not part of the function/section structure. More
on this at the debug.eclass section.

2.3 base.eclass

This eclass defines some default variables and functions,
similar to those you'd get by default in a non-inheriting
ebuild.

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

Once, long ago, I remember hearing that emerge would execute
this code automatically between src_unpack() and src_compile()
if the file ${FILESDIR}/${P}-gentoo.diff was present. Was
this a plan, a rumour, or what? Someone please correct me,
or at least correct this document.

2.4 kde.eclass

Used by all kde apps, whether directly or indirectly. This
is a med-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.

It inherits autoconf and base.

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

Briefly, it handles all standard kde-2.1* and 2.2* apps that
need configure/make/make install cycles. It handles all
the std. configure options e.g. qtmt. It also adds kdelibs
to DEPEND/RDEPEND.

Note: some kde apps, like widget styles and i18n packages,
do not need to compile anything. Therefore kde.eclass does
not inherit c and does not depend on qt. These packages
can then inherit straight from here (or from kde-i18n.eclass,
which also inherits from here). All other packages, which
need to compile c code and link against qt, should inherit
from kde-base.eclass.

As of v3.3, kde-objprelink was merged with kde, which now
provides the objprelink deps (>=objprelink-0-r1), the options
passed to configure and a function kde-objprelink-patch()
that applies the kde-admin-acinclude patch. Call it at the
end of your src_unpack if you need it.

2.5 kde-base.eclass

Meant for standard kde apps, of both 2.1 and 2.2 architectures.
Inherits c,kde and adds qt deps. Sets HOMEPAGE=apps.kde.com.

2.6 kde-i18n.eclass

Meant for the kde-i18n-* packages, possibly also for the
koffice-i18n to-be-written packages. Niche use.

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

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

2.7 kde-dist.eclass

Meant for the base kde distribution packages in kde-base/*.
Inherits kde-base, kde.org and kde-objprelink. 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.

2.8 c.eclass

Adds gcc and glibc to DEPEND and RDEPEND.

2.9 autoconf.eclass

Adds make/automake/autoconf to DEPEND.

2.10 debug.eclass

Adds verbose output debugging functions. Is inherited by
virtual.eclass.

A function with debugging looks like this:

base_src_install() {

 

        debug-print-function base_src_install $*

        [ -z "$1" ] && base_src_install all

 

        while [ "$1" ]; do

 

        case $1 in

                make)

                        debug-print-section make

                        make DESTDIR=${D} install || die

                        ;;

            all)

                        debug-prnit-section all

                        base_src_install make

                        ;;

        esac

 

        shift

        done

 

}

debug-print-function() prints "now
in function $1", "parameters
are $2..." (all following parameters to the function).

debug-print-section() prints "now
in section $1".

debug-print() prints raw "$1".

Inside debug.eclass are several settings, which can later
be moved to some external config file. They include turning
debug on or off and redirecting its output.

The functions are used in all ebuild functions/sections of
all eclasses, and in the helper functions inherit() and
EXPORT_FUNCTIONS().

Note that all debugging output is off by default. You can
change this setting in debug.eclass (for now), but be careful
not to commit the new setting to cvs. In addition, debug
output is further disabled in inherit() in inherit.eclass
to avoid extra-inheriting. You can enable it there by uncommenting
the appropriate lines.

2.11 kde-objprelink.eclass

This eclass has been removed in v3.3 Its contents were merged
into kde.eclass.

3 The inheriting ebuilds

Not much here as yet. Look at the kde*-2.2.1-r1 ebuilds for
examples. As a rule, read the eclass you are inheriting
from and put any necessary changes in your ebuild. For now,
a collection of tips:

* Always extend variables and functions. You should almost
  never need to replace them. In particular, always remember
  to use DEPEND="$DEPEND..."
  and the same for RDEPEND.

* The eclasses have DESCRIPTION="Derived
  from $ECLASS" set. This is to remind you
  to write a description of your own for your ebuilds. Otherwise
  the inherited one will show through as a reminder.