Re: [gentoo-dev] The future of eclasses

[Dan Armak <danarmak@gentoo.org>]

On Thursday 07 February 2002 21:27, you wrote:
> I like the idea. If its documentation becomes part of the ebuild howto,
> it will get adopted fairly quickly.
>
> The main concern Hallski and me (and possibly others, such as John
> Stalker, if memory serves) was that the current ebuild system mirrors
> the manual build process so closely that external contributors have
> little or no difficulty sending us ebuilds.
>
> I think this can be solved somewhat if it is clearly documented _what_
> is assumed by the various eclasses and perhaps a motivation when the
> assumptions are less than crystal clear.
When parts of the eclasses are merged into portage proper, what's left will 
(I hope) be a more unified and harmonious whole. Most of what's left will be 
in kde.eclass, which is written just like a standard ebuild, so anyone can 
read it (except for the many debug output statements).

As for documentation, there's my eclass-howto (in /usr/portage/eclass/doc) 
which explains almost everything abuot eclasses and can in fact serve as a 
guide to writing new eclasses, not just inheriting ebuilds. It also has 
specific detailed instructions for writing inheriting kde ebuilds. I haven't 
updated it yet for yesterday's changes, but I shortly will.

>
> What plagues many non-kde ebuilds is that their build systems are fairly
> non-standard. And even packages with seemingly standard build systems
> quickly turn out to have both minor and major flaws (Mailman is a good
> example of a horrible build system that on the surface looks nice, but
> in practice turns out to be a real bitch).
>
> The minor nuisances of the various build systems mean that we might find
> it easier to patch the generated Makefiles instead of the Makefile.in or
> Makefile.am files, thus requiring an intermediate step between
> configure and make (ie, patching in src_unpack is too troublesome).
>
> Consequently a simple wrapper for src_compile will only work a certain
> percentage (possibly relatively low; <= 50%) of the time, and a
> full-blown manual src_compile() function must be written for the rest of
> the ebuilds.
>
> The situation for src_install() is even more dire, as it would appear
> that close to all packages have trouble conforming to any kind of FHS,
> and installing in a temporary directory is completely foreign.
I know; kde ebuilds are surprisingly uniform and standard/fhs-compliant -a 
maintainer's dream really. That's what made kde eclasses possible in the 
first place.

> Now, for our regular ebuild writers, the 50% saving is a big deal. For a
> new submitter, it means he has to figure out which eclasses are
> available (+ what they are), which criteria his package must meet to be
> able to avail himself of the various eclasses, and finally test that
> this is really so.

The following is an illustrative explanations for people who aren't very 
familiar with eclasses:
The lesson learned from eclasses is, that writing standard functions and 
overriding them in the ebuilds when they don't work still isn't efficient 
enough to justify the whole thing. Instead we must provide means to easily 
extend these functions. 

In the existing eclasses (mostly base and kde) I do it in two ways. The first 
one is function sections; quoting fom the eclass-howto (I've erased some 
parts to make this shorter):

<quote>
One rarely uses predefined functions as-is; you usually want to extend them. 
Once they have unique names (foo_src_unpack) [another eclass feature, see 
eclass-howto] 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.

The special case all calls the same function recursively with a list of 
sections in order. The line before the block says that a call without 
parameters should be treated the same as a call with the single parameter all.

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() {

    # do what i want
    base_src_compile configure
    # do something in between
    base_src_compile make
    # do something else

}

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.
</quote>

The second way is by setting variables that the functions act on. The best 
example is that of $myconf. Many ebuilds say, in their general section:
myconf="$myconf my-parameter" # you can place a use flag? here too
Then, kde_src_compile passes $myconf to configure (after adding all the std 
parameters it knows about).

In my view, the eclass interface isn't very different from the ordinary 
ebuild one, it just encapsulates very many things, especially in the case of 
KDE where apps are stantardized. the great majority of inheriting ebuilds 
looks like this:
<headers>
. /usr/portage/eclass/inherit.eclass || die
inherit kde-base
newdepend "foo? ( bar )"
use foo && myconf="$myconf --with-foo" || myconf="$myconf --without-foo"
---

At the end of the eclass-howto I explain in detail how to write inheriting 
kde ebuilds, as well as ebuilds for apps with optional kde functionality. 
Please take a look at that; I think that (possibly with some improvements) it 
can be added to the ebuild writing howto (or a reference added).

A problem with kde ebuilds is that they *have* to use eclasses, in order for 
the kde "scheme" to work ($KDE?DIR and all that). Otherwise every kde ebuild 
would have to include some standard code that figures out where to install 
and against which kdelibs to link (it's currently in functions.eclass), so 
the obvious solution is to make a sourceable file out of it.

However, other ebuilds needn't be forced into this situation (which isn't 
strictly beneficial): I think we should avoid, at least at first, making smoe 
features only available via the eclasses. An ebuild writer should be able to 
recreate everything with minimal effort, even if it means rewriting a 
standard src_compile(). This way new ebuild authors can start out writing 
ordinary ebuilds, and later (or never if they so choose) move to inheriting 
ones. As long as there's no obligation or pressure on ebuild 
authors/developers to use eclasses, there needn't be any pressure not to.

-- 
Dan Armak
Gentoo Linux Developer, Desktop Team (KDE)
Matan, Israel