/[gentoo-x86]/eclass/eclass-howto.sgml
Gentoo

Contents of /eclass/eclass-howto.sgml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download) (as text)
Mon Oct 1 11:04:22 2001 UTC (13 years, 2 months ago) by danarmak
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +0 -0 lines
File MIME type: text/sgml
FILE REMOVED
eclasses v3. read the gentoo-dev announcement, and news.txt and howto.*
in doc/.

1 <!doctype chapter public "-//OASIS//DTD DocBook V3.1//EN">
2
3 <chapter lang="en">
4 <!-- DocBook file was created by LyX 1.1
5 See http://www.lyx.org/ for more information -->
6 <title>
7 eclass howto
8 </title>
9 <author>
10 Dan Armak
11 </author>
12 <date>
13 30/9/01
14 </date>
15 <sect1>
16 <title>
17 Introduction
18 </title>
19 <para>
20 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.
21 </para>
22 <para>
23 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.
24 </para>
25 <para>
26 Section two explains how eclasses work.Section three shows a sample inheriting ebuild.
27 </para>
28 <sect2>
29 <title>
30 Notes on this document
31 </title>
32 <itemizedlist>
33 <listitem>
34 <para>
35 ebuild variables/functions</emphasis> refers to those used in std. ebuilds e.g. &dollar;S, &dollar;P, src_unpack()...
36 </para>
37 </listitem>
38 </itemizedlist>
39 </sect2>
40 </sect1>
41 <sect1>
42 <title>
43 The eclasses
44 </title>
45 <para>
46 The best way of becoming familiar with the current eclass structure is an explanation of what each eclass does.
47 </para>
48 <sect2>
49 <title>
50 inherit.eclass
51 </title>
52 <para>
53 Defines inherit() function which handles sourcing of eclasses.
54 </para>
55 <para>
56 Syntax of inheriting: we define a simple function inherit():
57 </para>
58 <programlisting>
59 <![ CDATA [ECLASSDIR=/usr/portage/eclass
60 ]]><![ CDATA [inherit() {
61 ]]><![ CDATA [ while [ "$1" ]; do
62 ]]><![ CDATA [ source ${ECLASSDIR}/${1}.eclass
63 ]]><![ CDATA [ shift
64 ]]><![ CDATA [ done
65 ]]><![ CDATA [}
66 ]]> </programlisting>
67 <para>
68 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 &ldquo;formats&rdquo; (like drobbins' projected <emphasis>xbuilds</emphasis>), any name-to-file resolution code will go in here.
69 </para>
70 <para>
71 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:
72 </para>
73 <para>
74 . /usr/portage/eclass/inherit.eclass || die
75 </para>
76 <para>
77 inherit kde-base || die
78 </para>
79 <para>
80 Once the inherit() function goes into ebuild.sh, we can drop the first line; there will be no further change necessary.
81 </para>
82 <para>
83 Eclasses do not need this first line, since they are always sourced from an ebuild which has it.
84 </para>
85 </sect2>
86 <sect2>
87 <title>
88 virtual.eclass
89 </title>
90 <para>
91 Defines empty variables and functions; defines EXPORT_FUNCTIONS().
92 </para>
93 <para>
94 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.
95 </para>
96 <para>
97 It defines all ebuild vars and funcs to be empty.
98 </para>
99 <para>
100 It also defines the EXPORT_FUNCTIONS() function which looks like this:
101 </para>
102 <programlisting>
103 <![ CDATA [EXPORT_FUNCTIONS() {
104 ]]><![ CDATA [ while [ "$1" ]; do
105 ]]><![ CDATA [ eval "$1() { ${ECLASS}_$1 ; }" > /dev/null
106 ]]><![ CDATA [ shift
107 ]]><![ CDATA [ done
108 ]]><![ CDATA [}
109 ]]> </programlisting>
110 <para>
111 This means that after foo.eclass has defined e.g. src_unpack() and src_install(), it says:
112 </para>
113 <para>
114 ECLASS=foo
115 </para>
116 <para>
117 EXPORT_FUNCTIONS src_unpack src_install
118 </para>
119 <para>
120 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-&gt;name algorithm and get the ECLASS setting the same way we do &dollar;P and &dollar;PN.
121 </para>
122 <para>
123 EXPORT_FUNCTIONS() creates stub functions called &dollar;&lcub;ECLASS&rcub;_blah for every parameter blah passed to it. The stub function does nothing but call blah.
124 </para>
125 <para>
126 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 &dollar;&lcub;ECLASS&rcub;_. This way, people can call a specific function from a specific eclass and know what they are going to get.
127 </para>
128 <para>
129 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.
130 </para>
131 <para>
132 I looked at adding &dollar;&lcub;EBUILD&rcub;_ instead of literal strings to the actual function definitions, but the bash syntax for that is too ugly.
133 </para>
134 <sect3>
135 <title>
136 ebuild function sections
137 </title>
138 <para>
139 Although this is not an integral part of eclasses, this is a good place to introduce function sections.
140 </para>
141 <para>
142 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.
143 </para>
144 <para>
145 The implementation is simple. Let's take as an example the src_compile() function from base.eclass. It looks like this:
146 </para>
147 <programlisting>
148 <![ CDATA [base_src_compile() {
149 ]]><![ CDATA [./configure || die
150 ]]><![ CDATA [make || die
151 ]]><![ CDATA [}
152 ]]> </programlisting>
153 <para>
154 Here is the same function, divided into sections:
155 </para>
156 <programlisting>
157 <![ CDATA [base_src_compile() {
158 ]]><![ CDATA [
159 ]]><![ CDATA [ [ -z "$1" ] && base_src_compile all
160 ]]><![ CDATA [
161 ]]><![ CDATA [ while [ "$1" ]; do
162 ]]><![ CDATA [
163 ]]><![ CDATA [ case $1 in
164 ]]><![ CDATA [ configure)
165 ]]><![ CDATA [ ./configure || die;;
166 ]]><![ CDATA [ make)
167 ]]><![ CDATA [ make || die;;
168 ]]><![ CDATA [ all)
169 ]]><![ CDATA [ base_src_compile configure make;;
170 ]]><![ CDATA [ esac
171 ]]><![ CDATA [
172 ]]><![ CDATA [ shift
173 ]]><![ CDATA [ done
174 ]]><![ CDATA [
175 ]]><![ CDATA [}
176 ]]> </programlisting>
177 <para>
178 The code has been divided into two &ldquo;sections&rdquo;: <emphasis>configure</emphasis> and <emphasis>make</emphasis>. In our simple example, they correspond to the two commands in the original function.
179 </para>
180 <para>
181 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.
182 </para>
183 <para>
184 The special case <emphasis>all</emphasis> 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.
185 </para>
186 <para>
187 The line before the block says that a call without parameters should be treated the same as a call with the single parameter <emphasis>all. </emphasis>As you see, this function recurses a lot. Note, however, that the call <emphasis>base_src_compile configure all make </emphasis>is also legal; it will execute <emphasis>base_src_compile configure configure make make</emphasis>.
188 </para>
189 <para>
190 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 <emphasis>all</emphasis>, 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:
191 </para>
192 <programlisting>
193 <![ CDATA [src_compile() {
194 ]]><![ CDATA [ myfunc1
195 ]]><![ CDATA [ base_src_compile configure
196 ]]><![ CDATA [ myfunc2
197 ]]><![ CDATA [ base_src_compile make
198 ]]><![ CDATA [}
199 ]]> </programlisting>
200 <para>
201 The only way to know what functions contain what sections is to read the eclasses.
202 </para>
203 </sect3>
204 </sect2>
205 <sect2>
206 <title>
207 base.eclass
208 </title>
209 <para>
210 This eclass defines some default variables and functions, similar to those you'd get by default in a non-inheriting ebuild. For example, it defines:
211 </para>
212 <programlisting>
213 <![ CDATA [base_src_unpack() { unpack ${A}; }
214 ]]> </programlisting>
215 <para>
216 Only with sections, of course.
217 </para>
218 <para>
219 It is inherited by higher-level eclasses like the kde ones.
220 </para>
221 </sect2>
222 <sect2>
223 <title>
224 kde.eclass
225 </title>
226 <para>
227 Used by all kde apps, whether directly or indirectly. 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.
228 </para>
229 <para>
230 It inherits c, autoconf and base.
231 </para>
232 <para>
233 Read it to find out what it defines. It is quite self-explanatory.
234 </para>
235 <para>
236 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 and qt to DEPEND.
237 </para>
238 </sect2>
239 <sect2>
240 <title>
241 kde-base.eclass
242 </title>
243 <para>
244 Meant for kde apps part of the core kde distribution.
245 </para>
246 <para>
247 Differences from kde.eclass:
248 </para>
249 <itemizedlist>
250 <listitem>
251 <para>
252 Sets appropriate DESCRIPTION and HOMEPAGE=www.kde.org.
253 </para>
254 </listitem>
255 <listitem>
256 <para>
257 Sets default download path to the correct location on ftp.kde.org and several of its mirrors.
258 </para>
259 </listitem>
260 </itemizedlist>
261 </sect2>
262 <sect2>
263 <title>
264 kde-i18n.eclass
265 </title>
266 <para>
267 Meant for the kde-i18n-* packages. Niche use.
268 </para>
269 <para>
270 In fact, all kde-i18n ebuilds are completely identical and so all they have to do is inherit from this eclass.
271 </para>
272 <para>
273 Differences from kde.eclass:
274 </para>
275 <para>
276 Many. Doesn't inherit c. Doesn't depend on qt. Provides virtual/kde-i18n-&dollar;&lcub;PV&rcub;. Doesn't have <emphasis>myconf </emphasis>section in src_compile(). Doesn't have any sections in src_install(). Probably something else I forgot as well.
277 </para>
278 </sect2>
279 <sect2>
280 <title>
281 c.eclass
282 </title>
283 <para>
284 Adds gcc and glibc to DEPEND and RDEPEND. Not meant to be used alone, inherited by kde*.
285 </para>
286 </sect2>
287 <sect2>
288 <title>
289 autoconf.eclass
290 </title>
291 <para>
292 Adds make/automake/autoconf to DEPEND. Not meant to be used alone, inherited by kde*.
293 </para>
294 </sect2>
295 <sect2>
296 <title>
297 debug.eclass
298 </title>
299 <para>
300 Will be written soon. Will provide verbose debug output functions to centralise the numerous <emphasis>echo</emphasis>s I have scattered around the eclasses.
301 </para>
302 </sect2>
303 </sect1>
304 <sect1>
305 <title>
306 The inheriting ebuilds
307 </title>
308 <para>
309 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.
310 </para>
311 <para>
312 Remember: always extend variables and fnctions. You should almost never need to replace them.
313 </para>
314 </sect1>
315
316
317 </chapter>

  ViewVC Help
Powered by ViewVC 1.1.20