diff options
Diffstat (limited to 'eclass/doc/eclass-howto.txt')
| -rw-r--r-- | eclass/doc/eclass-howto.txt | 556 |
1 files changed, 0 insertions, 556 deletions
diff --git a/eclass/doc/eclass-howto.txt b/eclass/doc/eclass-howto.txt deleted file mode 100644 index fc2baa4ad5d7..000000000000 --- a/eclass/doc/eclass-howto.txt +++ /dev/null @@ -1,556 +0,0 @@ - - -eclass howto - -Dan Armak - -Updated for 20020206 - -1 Warning - -The eclasses have been modified and the documentation isn't -up to date, to be fixed shortly. - -2 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. - -This inheritance is implemented via simple bash sourcing. -So, when you 'inherit" 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). - -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. - -Because of the current customisable KDEDIR (KDE?DIR, KDE?LIBSDIR) -scheme, all kde ebuilds (including ebuilds for apps with -optional kde support) must use the eclasses. As a minimum, -inherit kde-dirs to get the set-qtdir(), set-kdedir() functions. - -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. - -3 The eclasses - -The best way of becoming familiar with the current eclass -structure is an explanation of what each eclass does. - -3.1 inherit.eclass - -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: - -. /usr/portage/eclass/inherit.eclass || die - -Eclasses do not need this first line, since they are always -sourced from an ebuild which already has it. - -The second line would typically be: - -inherit <list of eclasses> - -3.1.1 inherit() - -This eclass defines the inherit() function which handles -sourcing of eclasses: - -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, any name-to-file resolution code will -go in here. - -3.1.2 EXPORT_FUNCTIONS() - -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. - -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. - -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: - -EXPORT_FUNCTIONS() { - - - - while [ "$1" ]; do - - eval "$1() { ${ECLASS}_$1 ; }" > /dev/null - - shift - - done - - - -} - -Every eclass at its beginning sets $ECLASS to its name (e.g. -"A" or "B"). Then it calls EXPORT_FUNCTIONS -with the list of functions it provides. For example, if -you call - -ECLASS=foo - -EXPORT_FUNCTIONS src_unpack - -The EXPORT_FUNCTIONS will call eval on the following string: - -src_unpack() { foo_src_unpack() ; } - -3.2 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 - -} - -Where myfunc{1,2} is any code you want to execute between -the sections. - -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. The only -such section right now is base_src_compile patch. - -3.3 debug.eclass - -Adds verbose output debugging functions. Is inherited by -inherit.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 (except for bash -x). - -Look at it to see the functions it provides, they are simplistic. - -You can export ECLASS_DEBUG_OUTPUT="/dev/stdout" -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!). - -Let's add typical debug output statements to our sample function -from the function sections explanation: - -base_src_compile() { - - - - debug-print function $FUNCNAME $* - - [ -z "$1" ] && base_src_compile all - - - - while [ "$1" ]; do - - case $1 in - - configure) - - debug-print-section configure - - ./configure || die;; - - make) - - debug-print-section make - - make || die;; - - all) - - debug-print-section all - - base_src_compile configure make;; - - esac - - shift - - done - - - - debug-print "$FUNCNAME: result is $RESULT" #yes I know -there is no $RESULT in this sample function - -} - -3.4 base.eclass - -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}; }. - -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 - -3.5 autotools.eclass - -This is made and maintained by Azarah. To quote his comments: - -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. - -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 fill in here). - -3.6 kde.eclass - -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. - -It inherits autoconf, base and depend. - -Read it to find out what it defines. It is quite self-explanatory. - -Briefly, it handles all standard kde apps that use GNU standard -configure/make/make install cycles. It handles all the std. -configure options e.g. qtmt. - -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.eclass. - -3.7 functions.eclass - -3.7.1 kde-related (used to be kde-dirs.eclass) - -A short explanation about the current multi-kdedir scheme: - -$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}. - -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. - -As for qt, the latest 2.x, 3.x version lives in /usr/qt/2,3 -respectively. - -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. - -This eclass provides two pairs of functions: need-kde(), -need-qt() and set-kdedir(), set-qtdir(). These functions -handle the details of the multi-qt and multi-kdelibs schemes. - -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. - -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. - -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. - -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. - -kde-dirs.eclass also contains several helper functions you -shouldn't need to use directly. - -3.7.2 newdepend() - -This function simply adds all parameters to both DEPEND and -RDEPEND, saving you the trouble of writing and maintaining -two lists of dependencies. - -If called with a special parameter, it adds predefined dependencies. -These special parmeters exst as of now: - -"/autotools": add "sys-devel/autoconf - sys-devel/automake sys-devel/make" - to DEPEND (but not RDEPEND). - -"/c": add "virtual/glibc sys-devel/ld.so" - to both DEPEND and RDEPEND. Also, add "sys-devel/gcc" - to DEPEND. - -This function encourages developers to maintain comprehensive -DPEND strings. Especially, many ebuilds have no RDEPEND -strings, which will be a problem once we have unmerge functionality -that knows about dependencies. - -3.8 kde-base.eclass - -Meant for standard kde apps; nearly all ebuilds use it. Inherits -kde. Calls newdepend /c. Sets HOMEPAGE=apps.kde.com. - -3.9 kde-i18n.eclass - -Meant for the kde-i18n-* packages. Niche use. - -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. - -Inherits kde, kde.org. Makes a few differences, such as PROVIDE -virtual/kde-i18n, correct $S, HOMEPAGE and DESCRIPTION. - -3.10 koffice-i18n.eclass - -Meant for the koffice-i18n-* packages. Niche use. Very similar -to kde-i18n.eclass. - -All kde-i18n ebuilds are completely identical and so all -they have to do is inherit from this eclass. - -3.11 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. - -3.12 kde-cvs - -This is only included with the kde3-pre ebuilds, and doesn't -live in portage. See [http://www.gentoo.org/~danarmak/kde3-pre.html||http://www.gentoo.org/~danarmak/kde3-pre.html]. - -It provides a new src_unpack which sets SRC_URI="" -and copies the sources from a location hardcoded in the -eclass. Useful if you have a local copy of the kde cvs modules. - -It does not run cvs.cvsup itself beacuse that would violate -the sanbox. I plan to add a sanbox_allow command and implement -that functionality. - -3.13 kde-pre - -This is only included with the kde3-pre ebuilds, and doesn't -live in portage. See [http://www.gentoo.org/~danarmak/kde3-pre.html||http://www.gentoo.org/~danarmak/kde3-pre.html]. - -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. - -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). - -4 The inheriting ebuilds - -When in doubt, look at other inheriting ebuilds, or ask. - -4.1 A typical kde app ebuild - -<header lines> - -. /usr/portage/eclass/inherit.eclass || die - -inherit kde-base - -# Some ebuilds end right here. Others need some customization. - - -# Add any extra deps. Remember: *always* extend variables, -never override! - -DEPEND="$DEPEND foo/bar" - -RDEPEND="$RDEPEND bar/foo" - -# This will add a dep to both DEPEND and RDEPEND - -newdepend "foo? ( bar )" - -# This adds extra arguments to $myconf, which is passed to -configure - -myconf="$myconf --with-foobar" - -# extend src_unpack - -src_unpack() { - - base_src_unpack all patch # Patch from ${FILESDIR}/${P}-gentoo.diff - - # some more changes - - dosed -e 's:1:2:' ${S}/foobar - -} - -4.2 A typical optional-kde-functionality app ebuild - -To your normal ebuild, add the following lines. Prefix each -line with "use kde &&", or -create whole "if [ "`use -kde`" ]; then; fi" blocks. To the general -section, add: - -. /usr/prtage/eclass/inherit.eclass - -inherit kde-dirs - -need-kde $version # minimal version of kde your app needs - -If you only need (optional) qt support, do the same, but -call need-qt. You can also disregard eclasses entirely, -but make sure to add the correct QT dep; the correct format -as of now is e.g. =x11-libs/qt-2* for qt2.x. - -Have fun! :-) - danarmak |