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

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass docbook-chapter
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

eclass howto
\layout Author

Dan Armak
\layout Date

Updated for 20020206
\layout Section

Warning
\layout Standard

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

Introduction
\layout Standard

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.
\layout Standard

This inheritance is implemented via simple bash sourcing.
 So, when you 'inherit
\begin_inset Quotes erd
\end_inset 

 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).
\layout Standard

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.
\layout Standard

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

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.
\layout Section

The eclasses
\layout Standard

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

inherit.eclass
\layout Standard

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:
\layout Code

.
 /usr/portage/eclass/inherit.eclass || die
\layout Standard

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

The second line would typically be:
\layout Code

inherit <list of eclasses>
\layout Standard

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

ECLASSDIR=/usr/portage/eclass
\layout Code

inherit() {
\layout Code

    while [ "$1" ]; do
\layout Code

        source ${ECLASSDIR}/${1}.eclass
\layout Code

    shift
\layout Code

    done
\layout Code

}
\layout Standard

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.
\layout Subsection

virtual.eclass
\layout Standard

This is sourced from inherit.eclass, and thus should always be present before
 all other eclasses.
 It defines EXPORT_FUNCTIONS().
\layout Standard

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.
\layout Standard

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.
\layout Standard

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:
\layout Code

EXPORT_FUNCTIONS() {
\layout Code

 
\layout Code

        while [ "$1" ]; do
\layout Code

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

        shift
\layout Code

        done
\layout Code

 
\layout Code

}
\layout Standard

Every eclass at its beginning sets $ECLASS to its name (e.g.
 
\begin_inset Quotes eld
\end_inset 

A
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

B
\begin_inset Quotes erd
\end_inset 

).
 Then it calls EXPORT_FUNCTIONS with the list of functions it provides.
 For example, if you call
\layout Code

ECLASS=foo
\layout Code

EXPORT_FUNCTIONS src_unpack
\layout Standard

The EXPORT_FUNCTIONS will call eval on the following string:
\layout Code

src_unpack() { foo_src_unpack() ; }
\layout Standard

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).
\layout Subsection

Function sections
\layout Standard

Although this is not an integral part of eclasses, this is a good place
 to introduce function sections.
 
\layout Standard

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.
\layout Standard

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

base_src_compile() {
\layout Code

    ./configure || die
\layout Code

    make || die
\layout Code

}
\layout Standard

Here is the same function, divided into sections:
\layout Code

base_src_compile() {
\layout Code

 
\layout Code

    [ -z "$1" ] && base_src_compile all
\layout Code

 
\layout Code

    while [ "$1" ]; do
\layout Code

\layout Code

        case $1 in
\layout Code

            configure)
\layout Code

                ./configure || die;;
\layout Code

            make)
\layout Code

                make || die;;
\layout Code

            all)
\layout Code

                base_src_compile configure make;;
\layout Code

        esac
\layout Code

\layout Code

    shift
\layout Code

    done
\layout Code

 
\layout Code

}
\layout Standard

The code has been divided into two 
\begin_inset Quotes eld
\end_inset 

sections
\begin_inset Quotes erd
\end_inset 

: 
\emph on 
configure
\emph default 
 and 
\emph on 
make
\emph default 
.
 In our simple example, they correspond to the two commands in the original
 function.
\layout Standard

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.
\layout Standard

The special case 
\emph on 
all
\emph default 
 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.
\layout Standard

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

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 
\emph on 
all
\emph default 
, 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_compil
e a section at a time:
\layout Code

src_compile() {
\layout Code

    myfunc1
\layout Code

    base_src_compile configure
\layout Code

    myfunc2
\layout Code

    base_src_compile make
\layout Code

}
\layout Standard

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

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

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

debug.eclass
\layout Standard

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!).
\layout Standard

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

You can export ECLASS_DEBUG_OUTPUT=
\begin_inset Quotes erd
\end_inset 

/dev/stdout
\begin_inset Quotes erd
\end_inset 

 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!).
\layout Standard

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

base_src_compile() {
\layout Code

 
\layout Code

    debug-print function $FUNCNAME $*
\layout Code

    [ -z "$1" ] && base_src_compile all
\layout Code

 
\layout Code

    while [ "$1" ]; do
\layout Code

\layout Code

        case $1 in
\layout Code

            configure)
\layout Code

                debug-print-section configure
\layout Code

                ./configure || die;;
\layout Code

            make)
\layout Code

                debug-print-section make
\layout Code

                make || die;;
\layout Code

            all)
\layout Code

                debug-print-section all
\layout Code

                base_src_compile configure make;;
\layout Code

        esac
\layout Code

\layout Code

    shift
\layout Code

    done
\layout Code

 
\layout Code

    debug-print "$FUNCNAME: result is $RESULT" #yes I know there is no $RESULT
 in this sample function
\layout Code

\layout Code

}
\layout Subsection

base.eclass
\layout Standard

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}; }.
\layout Standard

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

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

cd ${S}
\layout Code

patch -p0 < ${FILESDIR}/${P}-gentoo.diff
\layout Standard

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.
\layout Subsection

c.eclass
\layout Standard

Adds gcc and glibc to DEPEND and RDEPEND.
\layout Subsection

autoconf.eclass
\layout Standard

Adds make/automake/autoconf to DEPEND.
\layout Subsection

autotools.eclass
\layout Standard

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

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.
\layout Standard

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).
\layout Subsection

kde.eclass
\layout Standard

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.
\layout Standard

It inherits autoconf, base and depend.
\layout Standard

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

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

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.e
class.
\layout Subsection

kde-dirs.eclass
\layout Standard

A short explanation about the current multi-kdedir scheme:
\layout Standard

$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}.
\layout Standard

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.
\layout Standard

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

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.
\layout Standard

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

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.
\layout Standard

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.
\layout Standard

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.
\layout Standard

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.
\layout Standard

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

kde-base.eclass
\layout Standard

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

kde-i18n.eclass
\layout Standard

Meant for the kde-i18n-* packages.
 Niche use.
\layout Standard

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.
\layout Standard

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

koffice-i18n.eclass
\layout Standard

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

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

kde-dist.eclass
\layout Standard

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.
\layout Subsection

kde-cvs
\layout Standard

This is only included with the kde3-pre ebuilds, and doesn't live in portage.
 See 
\begin_inset LatexCommand \url[http://www.gentoo.org/~danarmak/kde3-pre.html]{http://www.gentoo.org/~danarmak/kde3-pre.html}

\end_inset 

.
\layout Standard

It provides a new src_unpack which sets SRC_URI=
\begin_inset Quotes erd
\end_inset 


\begin_inset Quotes erd
\end_inset 

 and copies the sources from a location hardcoded in the eclass.
 Useful if you have a local copy of the kde cvs modules.
\layout Subsection

kde-pre
\layout Standard

This is only included with the kde3-pre ebuilds, and doesn't live in portage.
 See 
\begin_inset LatexCommand \url[http://www.gentoo.org/~danarmak/kde3-pre.html]{http://www.gentoo.org/~danarmak/kde3-pre.html}

\end_inset 

.
\layout Standard

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.
\layout Standard

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).
\layout Section

The inheriting ebuilds
\layout Standard

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

A typical kde app ebuild
\layout Code

<header lines>
\layout Code

.
 /usr/portage/eclass/inherit.eclass || die
\layout Code

inherit kde-base
\layout Code

# Some ebuilds end right here.
 Others need some customization.
\newline 

\layout Code

# Add any extra deps.
 Remember: *always* extend variables, never override!
\layout Code

DEPEND="$DEPEND foo/bar"
\layout Code

RDEPEND="$RDEPEND bar/foo"
\layout Code

# This will add a dep to both DEPEND and RDEPEND
\layout Code

newdepend "foo? ( bar )"
\layout Code

\layout Code

# This adds extra arguments to $myconf, which is passed to configure
\layout Code

myconf="$myconf --with-foobar"
\layout Code

\layout Code

# extend src_unpack
\layout Code

src_unpack() {
\layout Code

    base_src_unpack all patch   # Patch from ${FILESDIR}/${P}-gentoo.diff
\layout Code

    # some more changes
\layout Code

    dosed -e 's:1:2:' ${S}/foobar
\layout Code

}
\layout Code

\layout Subsection

A typical optional-kde-functionality app ebuild
\layout Standard

To your normal ebuild, add the following lines.
 Prefix each line with 
\begin_inset Quotes eld
\end_inset 

use kde &&
\begin_inset Quotes erd
\end_inset 

, or create whole 
\begin_inset Quotes eld
\end_inset 

if [ 
\begin_inset Quotes eld
\end_inset 

`use kde`
\begin_inset Quotes erd
\end_inset 

 ]; then; fi
\begin_inset Quotes erd
\end_inset 

 blocks.
 To the general section, add:
\layout Code

.
 /usr/prtage/eclass/inherit.eclass
\layout Code

inherit kde-dirs
\layout Code

need-kde $version # minimal version of kde your app needs
\layout Standard

If you only need (optional) qt support, do the same, but call need-qt.
\layout Standard

Have fun! :-) - danarmak
\the_end