diff options
Diffstat (limited to 'eclass/doc/eclass-howto.lyx')
| -rw-r--r-- | eclass/doc/eclass-howto.lyx | 597 |
1 files changed, 597 insertions, 0 deletions
diff --git a/eclass/doc/eclass-howto.lyx b/eclass/doc/eclass-howto.lyx new file mode 100644 index 000000000000..ff3f753533c6 --- /dev/null +++ b/eclass/doc/eclass-howto.lyx @@ -0,0 +1,597 @@ +#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 eclasses v3 +\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 + +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. +\layout Standard + +Please read news.txt for an astract of changes between versions of the eclasses. +\layout Standard + +Section two explains how eclasses work.Section three shows a sample inheriting + ebuild. +\layout Subsection + +Notes on this document +\layout Itemize + + +\emph on +ebuild variables/functions +\emph default + refers to those used in std. + ebuilds e.g. + $S, $P, src_unpack()... +\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 + +Defines inherit() function which handles sourcing of eclasses. +\layout Standard + +Syntax of inheriting: we define a simple function inherit(): +\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 + or to introduce more +\begin_inset Quotes eld +\end_inset + +formats +\begin_inset Quotes erd +\end_inset + + (like drobbins' projected +\emph on +xbuilds +\emph default +), any name-to-file resolution code will go in here. +\layout Standard + +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: +\layout Standard + +. + /usr/portage/eclass/inherit.eclass || die +\layout Standard + +inherit kde-base || die +\layout Standard + +Once the inherit() function goes into ebuild.sh, we can drop the first line; + there will be no further change necessary. +\layout Standard + +Eclasses do not need this first line, since they are always sourced from + an ebuild which has it. +\layout Subsection + +virtual.eclass +\layout Standard + +Defines empty variables and functions; defines EXPORT_FUNCTIONS(). +\layout Standard + +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. +\layout Standard + +It defines all ebuild vars and funcs to be empty. +\layout Standard + +It also defines the EXPORT_FUNCTIONS() function which looks like this: +\layout Code + +EXPORT_FUNCTIONS() { +\layout Code + + while [ "$1" ]; do +\layout Code + + eval "$1() { ${ECLASS}_$1 ; }" > /dev/null +\layout Code + + shift +\layout Code + + done +\layout Code + +} +\layout Standard + +This means that after foo.eclass has defined e.g. + src_unpack() and src_install(), it says: +\layout Standard + +ECLASS=foo +\layout Standard + +EXPORT_FUNCTIONS src_unpack src_install +\layout Standard + +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. +\layout Standard + +EXPORT_FUNCTIONS() creates stub functions called ${ECLASS}_blah for every + parameter blah passed to it. + The stub function does nothing but call blah. +\layout Standard + +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. +\layout Standard + +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. +\layout Standard + +I looked at adding ${EBUILD}_ instead of literal strings to the actual function + definitions, but the bash syntax for that is too ugly. +\layout Subsubsection + +ebuild 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 + +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-standrd and must be called explicitly. + Current examples inculde base_src_unpack +\emph on + patch +\emph default +and the upcoming kde_src_unpack +\emph on +objprelink-patch +\emph default + (whose name may change when I actually write it). +\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. +\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 + +Once, long ago, I remember hearing that emerge would execute this code automatic +ally between src_unpack() and src_compile() if the file ${FILESDIR}/${P}-gentoo.d +iff was present. + Was this a plan, a rumour, or what? Someone please correct me, or at least + correct this document. +\layout Subsection + +kde.eclass +\layout Standard + +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. +\layout Standard + +It inherits autoconf and base. +\layout Standard + +Read it to find out what it defines. + It is quite self-explanatory. +\layout Standard + +Briefly, it handles all standard kde-2.1* and 2.2* apps that need configure/make/m +ake install cycles. + It handles all the std. + configure options e.g. + objprelink. + It also adds kdelibs to DEPEND/RDEPEND. +\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 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. +\layout Subsection + +kde-base.eclass +\layout Standard + +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. +\layout Subsection + +kde-i18n.eclass +\layout Standard + +Meant for the kde-i18n-* packages, possibly also for the koffice-i18n to-be-writ +ten 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. +\layout Standard + +Inherits from kde,kde.org. + Makes a few differences, such as PROVIDE virtual/kde-i18n, correct $S, + HOMEPAGE and DESCRIPTION. +\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 + +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 + +debug.eclass +\layout Standard + +Will be written soon. + Will provide verbose debug output functions to centralise the numerous + +\emph on +echo +\emph default +s I have scattered around the eclasses. +\layout Subsection + +kde-objprelink.eclass +\layout Standard + +Will be written soon. + Will provide the objprelink deps and the +\emph on +objprelink-patch +\emph default + src_unpack section. +\layout Section + +The inheriting ebuilds +\layout Standard + +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: +\layout Itemize + +Always extend variables and functions. + You should almost never need to replace them. + In particular, always remember to use DEPEND= +\begin_inset Quotes erd +\end_inset + +$DEPEND... +\begin_inset Quotes erd +\end_inset + + and the same for RDEPEND. +\layout Itemize + +The eclasses have DESCRIPTION= +\begin_inset Quotes erd +\end_inset + +Derived from $ECLASS +\begin_inset Quotes erd +\end_inset + + 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. +\the_end |