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

Contents of /eclass/eclass-howto.txt

Parent Directory Parent Directory | Revision Log Revision Log


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

1
2
3 eclass howto
4
5 Dan Armak
6
7 30/9/01
8
9 1 Introduction
10
11 eclasses are parts of ebuilds; that is, they have the same
12 syntax ebuilds do, but do not define all the required variables
13 and functions. ebuilds can inherit from eclasses, and eclasses
14 can inherit from other eclasses. As in OOP, this is used
15 to ensure maximum code reuse among similar ebuilds.
16
17 The most similar group of ebuilds is the kde apps. These
18 have been selected to be the test case for this first incarnation
19 of eclasses. Currently test ebuilds are available for all
20 of kde-2.2.1 (as kde*-2.2.1-r1), kdevelop-2.0.1 and koffice-1.1.
21 Many others will follow.
22
23 Section two explains how eclasses work.Section three shows
24 a sample inheriting ebuild.
25
26 1.1 Notes on this document
27
28 * ebuild variables/functions refers to those used in std.
29 ebuilds e.g. $S, $P, src_unpack()...
30
31 2 The eclasses
32
33 The best way of becoming familiar with the current eclass
34 structure is an explanation of what each eclass does.
35
36 2.1 inherit.eclass
37
38 Defines inherit() function which handles sourcing of eclasses.
39
40 Syntax of inheriting: we define a simple function inherit():
41
42 ECLASSDIR=/usr/portage/eclass
43
44 inherit() {
45
46 while [ "$1" ]; do
47
48 source ${ECLASSDIR}/${1}.eclass
49
50 shift
51
52 done
53
54 }
55
56 This function simply sources files from a hard-coded location.
57 If, in the future, we will decide to move eclasses to a
58 different location or to introduce more "formats"
59 (like drobbins' projected xbuilds), any name-to-file resolution
60 code will go in here.
61
62 This function is the entire contents of inherit.eclass. In
63 the future, once eclasses are considered to be stable, this
64 function will live in ebuild.sh, and every ebuild will be
65 able to use it. For now, we don't want to make a new version
66 of portage just for this, so we put this function in a separate
67 eclass. Every inheriting ebuild begins with these two lines:
68
69 . /usr/portage/eclass/inherit.eclass || die
70
71 inherit kde-base || die
72
73 Once the inherit() function goes into ebuild.sh, we can drop
74 the first line; there will be no further change necessary.
75
76 Eclasses do not need this first line, since they are always
77 sourced from an ebuild which has it.
78
79 2.2 virtual.eclass
80
81 Defines empty variables and functions; defines EXPORT_FUNCTIONS().
82
83 This eclass is inherited by most other eclasses e.g. base,
84 kde*. As a rule, any eclass that defines some of the base
85 functions needs it. Therefore the only ebuilds which don't
86 get it are the ones that only inherit one of the smaller
87 eclasses e.g. c, autoconf.
88
89 It defines all ebuild vars and funcs to be empty.
90
91 It also defines the EXPORT_FUNCTIONS() function which looks
92 like this:
93
94 EXPORT_FUNCTIONS() {
95
96 while [ "$1" ]; do
97
98 eval "$1() { ${ECLASS}_$1 ; }" > /dev/null
99
100 shift
101
102 done
103
104 }
105
106 This means that after foo.eclass has defined e.g. src_unpack()
107 and src_install(), it says:
108
109 ECLASS=foo
110
111 EXPORT_FUNCTIONS src_unpack src_install
112
113 Actually, the ECLASS setting is put at the beginning of the
114 eclass, directly after the inherit statements. It will in
115 the future be used by other functions as well. Someday we
116 will (I hope) adapt the portage ebuild filename->name algorithm
117 and get the ECLASS setting the same way we do $P and $PN.
118
119 EXPORT_FUNCTIONS() creates stub functions called ${ECLASS}_blah
120 for every parameter blah passed to it. The stub function
121 does nothing but call blah.
122
123 When you inherit more than one eclass (almost always), your
124 ebuild functions are those defined by the 1st eclass inherited.
125 Since eclasses usually inherit other eclasses, you do not
126 want to keep track of that. Instead, you prefix all your
127 functions from foo.eclass with foo_, or ${ECLASS}_. This
128 way, people can call a specific function from a specific
129 eclass and know what they are going to get.
130
131 Because you still want default functions to be defined with
132 the original ebuild names, you call EXPORT_FUNCTIONS() at
133 the end of every eclass. This makes sure that the default
134 functions you passed as parameters are stubs calling the
135 ones you just defined.
136
137 I looked at adding ${EBUILD}_ instead of literal strings
138 to the actual function definitions, but the bash syntax
139 for that is too ugly.
140
141 2.2.1 ebuild function sections
142
143 Although this is not an integral part of eclasses, this is
144 a good place to introduce function sections.
145
146 One rarely uses predefined functions as-is; you usually want
147 to extend them. Once they have unique names (foo_src_unpack)
148 it's easy to add code that executes before or after them.
149 Function sections break them down and allow code to execute
150 between any two sections.
151
152 The implementation is simple. Let's take as an example the
153 src_compile() function from base.eclass. It looks like this:
154
155 base_src_compile() {
156
157 ./configure || die
158
159 make || die
160
161 }
162
163 Here is the same function, divided into sections:
164
165 base_src_compile() {
166
167
168
169 [ -z "$1" ] && base_src_compile all
170
171
172
173 while [ "$1" ]; do
174
175 case $1 in
176
177
178 configure)
179
180 ./configure
181 || die;;
182
183
184 make)
185
186 make
187 || die;;
188
189
190 all)
191
192 base_src_compile
193 configure make;;
194
195 esac
196
197 shift
198
199 done
200
201
202
203 }
204
205 The code has been divided into two "sections":
206 configure and make. In our simple example, they correspond
207 to the two commands in the original function.
208
209 In the center of the new function is a while;case...esac;shift;done
210 block. This block matches the parameters to the functions
211 with the defined section names and executes the corresponding
212 lines of code.
213
214 The special case all calls the same function recursively
215 with a list of sections in order. It's up to the eclass's
216 author to maintain this list, which is very important.
217
218 The line before the block says that a call without parameters
219 should be treated the same as a call with the single parameter
220 all. As you see, this function recurses a lot. Note, however,
221 that the call base_src_compile configure all make is also
222 legal; it will execute base_src_compile configure configure
223 make make.
224
225 Now, in your ebuild (or eclass) that inherits from base.eclass,
226 you get the stub function src_compile which calls base_src_compile
227 without parameters. This makes base_src_compile execute
228 all, that is, all its sections. You can leave it as-is.
229 If you wish to extend it, you define a new src_compile and
230 call base_src_compile a section at a time:
231
232 src_compile() {
233
234 myfunc1
235
236 base_src_compile configure
237
238 myfunc2
239
240 base_src_compile make
241
242 }
243
244 The only way to know what functions contain what sections
245 is to read the eclasses.
246
247 2.3 base.eclass
248
249 This eclass defines some default variables and functions,
250 similar to those you'd get by default in a non-inheriting
251 ebuild. For example, it defines:
252
253 base_src_unpack() { unpack ${A}; }
254
255 Only with sections, of course.
256
257 It is inherited by higher-level eclasses like the kde ones.
258
259 2.4 kde.eclass
260
261 Used by all kde apps, whether directly or indirectly. This
262 is a higher-level eclass, which is intended to provide not
263 only sensible defaults but functions which can be used as-is
264 more often then not.
265
266 It inherits c, autoconf and base.
267
268 Read it to find out what it defines. It is quite self-explanatory.
269
270 Briefly, it handles all standard kde-2.1* and 2.2* apps that
271 need configure/make/make install cycles. It handles all
272 the std. configure options e.g. objprelink. It also adds
273 kdelibs and qt to DEPEND.
274
275 2.5 kde-base.eclass
276
277 Meant for kde apps part of the core kde distribution.
278
279 Differences from kde.eclass:
280
281 * Sets appropriate DESCRIPTION and HOMEPAGE=www.kde.org.
282
283 * Sets default download path to the correct location on ftp.kde.org
284 and several of its mirrors.
285
286 2.6 kde-i18n.eclass
287
288 Meant for the kde-i18n-* packages. Niche use.
289
290 In fact, all kde-i18n ebuilds are completely identical and
291 so all they have to do is inherit from this eclass.
292
293 Differences from kde.eclass:
294
295 Many. Doesn't inherit c. Doesn't depend on qt. Provides virtual/kde-i18n-${PV}.
296 Doesn't have myconf section in src_compile(). Doesn't have
297 any sections in src_install(). Probably something else I
298 forgot as well.
299
300 2.7 c.eclass
301
302 Adds gcc and glibc to DEPEND and RDEPEND. Not meant to be
303 used alone, inherited by kde*.
304
305 2.8 autoconf.eclass
306
307 Adds make/automake/autoconf to DEPEND. Not meant to be used
308 alone, inherited by kde*.
309
310 2.9 debug.eclass
311
312 Will be written soon. Will provide verbose debug output functions
313 to centralise the numerous echos I have scattered around
314 the eclasses.
315
316 3 The inheriting ebuilds
317
318 Not much here as yet. Look at the kde*-2.2.1-r1 ebuilds for
319 examples. As a rule, read the eclass you are inheriting
320 from and put any necessary changes in your ebuild.
321
322 Remember: always extend variables and fnctions. You should
323 almost never need to replace them.

  ViewVC Help
Powered by ViewVC 1.1.20