diff options
author | Dan Armak <danarmak@gentoo.org> | 2001-10-01 11:04:22 +0000 |
---|---|---|
committer | Dan Armak <danarmak@gentoo.org> | 2001-10-01 11:04:22 +0000 |
commit | eeaa105921a7f1d53ba72d958656f91e1d7ce61d (patch) | |
tree | a9b324d616e8659af477ae426d5ce90745a49e80 /eclass/doc/eclass-howto.txt | |
parent | updated to 0.10.3 (diff) | |
download | historical-eeaa105921a7f1d53ba72d958656f91e1d7ce61d.tar.gz historical-eeaa105921a7f1d53ba72d958656f91e1d7ce61d.tar.bz2 historical-eeaa105921a7f1d53ba72d958656f91e1d7ce61d.zip |
eclasses v3. read the gentoo-dev announcement, and news.txt and howto.*
in doc/.
Diffstat (limited to 'eclass/doc/eclass-howto.txt')
-rw-r--r-- | eclass/doc/eclass-howto.txt | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/eclass/doc/eclass-howto.txt b/eclass/doc/eclass-howto.txt new file mode 100644 index 000000000000..360218ee0e74 --- /dev/null +++ b/eclass/doc/eclass-howto.txt @@ -0,0 +1,357 @@ + + +eclass howto + +Dan Armak + +Updated for eclasses v3 + +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 this first incarnation +of eclasses. Currently test ebuilds are available for all +of kde-2.2.1 (as kde*-2.2.1-r1), kdevelop-2.0.1 and koffice-1.1. +Many others will follow. + +Please read news.txt for an astract of changes between versions +of the eclasses. + +Section two explains how eclasses work.Section three shows +a sample inheriting ebuild. + +1.1 Notes on this document + +* ebuild variables/functions refers to those used in std. + ebuilds e.g. $S, $P, src_unpack()... + +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. + +This function is the entire contents of inherit.eclass. In +the future, once eclasses are considered to be stable, this +function will live in ebuild.sh, and every ebuild will be +able to use it. For now, we don't want to make a new version +of portage just for this, so we put this function in a separate +eclass. Every inheriting ebuild begins with these two lines: + +. /usr/portage/eclass/inherit.eclass || die + +inherit kde-base || die + +Once the inherit() function goes into ebuild.sh, we can drop +the first line; there will be no further change necessary. + +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(). + +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-standrd and must be called explicitly. Current +examples inculde base_src_unpack patch and the upcoming +kde_src_unpack objprelink-patch (whose name may change when +I actually write it). + +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. objprelink. 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 ompile c code and link against qt, should inhreit +from kde-base.eclass. + +2.5 kde-base.eclass + +Meant for standard kde apps, of both 2.1 and 2.2 architectures. +Inherits c,kde and adds objprelink and 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. 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 + +Will be written soon. Will provide verbose debug output functions +to centralise the numerous echos I have scattered around +the eclasses. + +2.11 kde-objprelink.eclass + +Will be written soon. Will provide the objprelink deps and +the objprelink-patch src_unpack section. + +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. |