# Contents of /eclass/eclass-howto.lyx

eclasses v3. read the gentoo-dev announcement, and news.txt and howto.*

 1 #LyX 1.1 created this file. For more info see http://www.lyx.org/ 2 \lyxformat 218 3 \textclass docbook-chapter 4 \language english 5 \inputencoding auto 6 \fontscheme default 7 \graphics default 8 \paperfontsize default 9 \spacing single 10 \papersize Default 11 \paperpackage a4 12 \use_geometry 0 13 \use_amsmath 0 14 \paperorientation portrait 15 \secnumdepth 3 16 \tocdepth 3 17 \paragraph_separation indent 18 \defskip medskip 19 \quotes_language english 20 \quotes_times 2 21 \papercolumns 1 22 \papersides 1 23 \paperpagestyle default 24 25 \layout Title 26 27 eclass howto 28 \layout Author 29 30 Dan Armak 31 \layout Date 32 33 30/9/01 34 \layout Section 35 36 Introduction 37 \layout Standard 38 39 eclasses are parts of ebuilds; that is, they have the same syntax ebuilds 40 do, but do not define all the required variables and functions. 41 ebuilds can inherit from eclasses, and eclasses can inherit from other 42 eclasses. 43 As in OOP, this is used to ensure maximum code reuse among similar ebuilds. 44 \layout Standard 45 46 The most similar group of ebuilds is the kde apps. 47 These have been selected to be the test case for this first incarnation 48 of eclasses. 49 Currently test ebuilds are available for all of kde-2.2.1 (as kde*-2.2.1-r1), 50 kdevelop-2.0.1 and koffice-1.1. 51 Many others will follow. 52 \layout Standard 53 54 Section two explains how eclasses work.Section three shows a sample inheriting 55 ebuild. 56 \layout Subsection 57 58 Notes on this document 59 \layout Itemize 60 61 62 \emph on 63 ebuild variables/functions 64 \emph default 65 refers to those used in std. 66 ebuilds e.g. 67 $S,$P, src_unpack()... 68 \layout Section 69 70 The eclasses 71 \layout Standard 72 73 The best way of becoming familiar with the current eclass structure is an 74 explanation of what each eclass does. 75 \layout Subsection 76 77 inherit.eclass 78 \layout Standard 79 80 Defines inherit() function which handles sourcing of eclasses. 81 \layout Standard 82 83 Syntax of inheriting: we define a simple function inherit(): 84 \layout Code 85 86 ECLASSDIR=/usr/portage/eclass 87 \layout Code 88 89 inherit() { 90 \layout Code 91 92 while [ "$1" ]; do 93 \layout Code 94 95 source${ECLASSDIR}/${1}.eclass 96 \layout Code 97 98 shift 99 \layout Code 100 101 done 102 \layout Code 103 104 } 105 \layout Standard 106 107 This function simply sources files from a hard-coded location. 108 If, in the future, we will decide to move eclasses to a different location 109 or to introduce more 110 \begin_inset Quotes eld 111 \end_inset 112 113 formats 114 \begin_inset Quotes erd 115 \end_inset 116 117 (like drobbins' projected 118 \emph on 119 xbuilds 120 \emph default 121 ), any name-to-file resolution code will go in here. 122 \layout Standard 123 124 This function is the entire contents of inherit.eclass. 125 In the future, once eclasses are considered to be stable, this function 126 will live in ebuild.sh, and every ebuild will be able to use it. 127 For now, we don't want to make a new version of portage just for this, 128 so we put this function in a separate eclass. 129 Every inheriting ebuild begins with these two lines: 130 \layout Standard 131 132 . 133 /usr/portage/eclass/inherit.eclass || die 134 \layout Standard 135 136 inherit kde-base || die 137 \layout Standard 138 139 Once the inherit() function goes into ebuild.sh, we can drop the first line; 140 there will be no further change necessary. 141 \layout Standard 142 143 Eclasses do not need this first line, since they are always sourced from 144 an ebuild which has it. 145 \layout Subsection 146 147 virtual.eclass 148 \layout Standard 149 150 Defines empty variables and functions; defines EXPORT_FUNCTIONS(). 151 \layout Standard 152 153 This eclass is inherited by most other eclasses e.g. 154 base, kde*. 155 As a rule, any eclass that defines some of the base functions needs it. 156 Therefore the only ebuilds which don't get it are the ones that only inherit 157 one of the smaller eclasses e.g. 158 c, autoconf. 159 \layout Standard 160 161 It defines all ebuild vars and funcs to be empty. 162 \layout Standard 163 164 It also defines the EXPORT_FUNCTIONS() function which looks like this: 165 \layout Code 166 167 EXPORT_FUNCTIONS() { 168 \layout Code 169 170 while [ "$1" ]; do 171 \layout Code 172 173 eval "$1() {${ECLASS}_$1 ; }" > /dev/null 174 \layout Code 175 176 shift 177 \layout Code 178 179 done 180 \layout Code 181 182 } 183 \layout Standard 184 185 This means that after foo.eclass has defined e.g. 186 src_unpack() and src_install(), it says: 187 \layout Standard 188 189 ECLASS=foo 190 \layout Standard 191 192 EXPORT_FUNCTIONS src_unpack src_install 193 \layout Standard 194 195 Actually, the ECLASS setting is put at the beginning of the eclass, directly 196 after the inherit statements. 197 It will in the future be used by other functions as well. 198 Someday we will (I hope) adapt the portage ebuild filename->name algorithm 199 and get the ECLASS setting the same way we do$P and $PN. 200 \layout Standard 201 202 EXPORT_FUNCTIONS() creates stub functions called${ECLASS}_blah for every 203 parameter blah passed to it. 204 The stub function does nothing but call blah. 205 \layout Standard 206 207 When you inherit more than one eclass (almost always), your ebuild functions 208 are those defined by the 1st eclass inherited. 209 Since eclasses usually inherit other eclasses, you do not want to keep 210 track of that. 211 Instead, you prefix all your functions from foo.eclass with foo_, or ${ECLASS}_. 212 This way, people can call a specific function from a specific eclass and 213 know what they are going to get. 214 \layout Standard 215 216 Because you still want default functions to be defined with the original 217 ebuild names, you call EXPORT_FUNCTIONS() at the end of every eclass. 218 This makes sure that the default functions you passed as parameters are 219 stubs calling the ones you just defined. 220 \layout Standard 221 222 I looked at adding${EBUILD}_ instead of literal strings to the actual function 223 definitions, but the bash syntax for that is too ugly. 224 \layout Subsubsection 225 226 ebuild function sections 227 \layout Standard 228 229 Although this is not an integral part of eclasses, this is a good place 230 to introduce function sections. 231 232 \layout Standard 233 234 One rarely uses predefined functions as-is; you usually want to extend them. 235 Once they have unique names (foo_src_unpack) it's easy to add code that 236 executes before or after them. 237 Function sections break them down and allow code to execute between any 238 two sections. 239 \layout Standard 240 241 The implementation is simple. 242 Let's take as an example the src_compile() function from base.eclass. 243 It looks like this: 244 \layout Code 245 246 base_src_compile() { 247 \layout Code 248 249 ./configure || die 250 \layout Code 251 252 make || die 253 \layout Code 254 255 } 256 \layout Standard 257 258 Here is the same function, divided into sections: 259 \layout Code 260 261 base_src_compile() { 262 \layout Code 263 264 \SpecialChar ~ 265 266 \layout Code 267 268 \SpecialChar ~ 269 \SpecialChar ~ 270 \SpecialChar ~ 271 [ -z "$1" ] && base_src_compile all 272 \layout Code 273 274 \SpecialChar ~ 275 276 \layout Code 277 278 \SpecialChar ~ 279 \SpecialChar ~ 280 \SpecialChar ~ 281 while [ "$1" ]; do 282 \layout Code 283 284 \layout Code 285 286 \SpecialChar ~ 287 \SpecialChar ~ 288 \SpecialChar ~ 289 \SpecialChar ~ 290 \SpecialChar ~ 291 \SpecialChar ~ 292 \SpecialChar ~ 293 \SpecialChar ~ 294 case $1 in 295 \layout Code 296 297 \SpecialChar ~ 298 \SpecialChar ~ 299 \SpecialChar ~ 300 \SpecialChar ~ 301 \SpecialChar ~ 302 \SpecialChar ~ 303 \SpecialChar ~ 304 \SpecialChar ~ 305 \SpecialChar ~ 306 \SpecialChar ~ 307 \SpecialChar ~ 308 configure) 309 \layout Code 310 311 \SpecialChar ~ 312 \SpecialChar ~ 313 \SpecialChar ~ 314 \SpecialChar ~ 315 \SpecialChar ~ 316 \SpecialChar ~ 317 \SpecialChar ~ 318 \SpecialChar ~ 319 \SpecialChar ~ 320 \SpecialChar ~ 321 \SpecialChar ~ 322 \SpecialChar ~ 323 \SpecialChar ~ 324 \SpecialChar ~ 325 \SpecialChar ~ 326 \SpecialChar ~ 327 ./configure || die;; 328 \layout Code 329 330 \SpecialChar ~ 331 \SpecialChar ~ 332 \SpecialChar ~ 333 \SpecialChar ~ 334 \SpecialChar ~ 335 \SpecialChar ~ 336 \SpecialChar ~ 337 \SpecialChar ~ 338 \SpecialChar ~ 339 \SpecialChar ~ 340 \SpecialChar ~ 341 make) 342 \layout Code 343 344 \SpecialChar ~ 345 \SpecialChar ~ 346 \SpecialChar ~ 347 \SpecialChar ~ 348 \SpecialChar ~ 349 \SpecialChar ~ 350 \SpecialChar ~ 351 \SpecialChar ~ 352 \SpecialChar ~ 353 \SpecialChar ~ 354 \SpecialChar ~ 355 \SpecialChar ~ 356 \SpecialChar ~ 357 \SpecialChar ~ 358 \SpecialChar ~ 359 \SpecialChar ~ 360 make || die;; 361 \layout Code 362 363 \SpecialChar ~ 364 \SpecialChar ~ 365 \SpecialChar ~ 366 \SpecialChar ~ 367 \SpecialChar ~ 368 \SpecialChar ~ 369 \SpecialChar ~ 370 \SpecialChar ~ 371 \SpecialChar ~ 372 \SpecialChar ~ 373 \SpecialChar ~ 374 all) 375 \layout Code 376 377 \SpecialChar ~ 378 \SpecialChar ~ 379 \SpecialChar ~ 380 \SpecialChar ~ 381 \SpecialChar ~ 382 \SpecialChar ~ 383 \SpecialChar ~ 384 \SpecialChar ~ 385 \SpecialChar ~ 386 \SpecialChar ~ 387 \SpecialChar ~ 388 \SpecialChar ~ 389 \SpecialChar ~ 390 \SpecialChar ~ 391 \SpecialChar ~ 392 \SpecialChar ~ 393 base_src_compile configure make;; 394 \layout Code 395 396 \SpecialChar ~ 397 \SpecialChar ~ 398 \SpecialChar ~ 399 \SpecialChar ~ 400 \SpecialChar ~ 401 \SpecialChar ~ 402 \SpecialChar ~ 403 \SpecialChar ~ 404 esac 405 \layout Code 406 407 \layout Code 408 409 \SpecialChar ~ 410 \SpecialChar ~ 411 \SpecialChar ~ 412 shift 413 \layout Code 414 415 \SpecialChar ~ 416 \SpecialChar ~ 417 \SpecialChar ~ 418 done 419 \layout Code 420 421 \SpecialChar ~ 422 423 \layout Code 424 425 } 426 \layout Standard 427 428 The code has been divided into two 429 \begin_inset Quotes eld 430 \end_inset 431 432 sections 433 \begin_inset Quotes erd 434 \end_inset 435 436 : 437 \emph on 438 configure 439 \emph default 440 and 441 \emph on 442 make 443 \emph default 444 . 445 In our simple example, they correspond to the two commands in the original 446 function. 447 \layout Standard 448 449 In the center of the new function is a while;case...esac;shift;done block. 450 This block matches the parameters to the functions with the defined section 451 names and executes the corresponding lines of code. 452 \layout Standard 453 454 The special case 455 \emph on 456 all 457 \emph default 458 calls the same function recursively with a list of sections in order. 459 It's up to the eclass's author to maintain this list, which is very important. 460 \layout Standard 461 462 The line before the block says that a call without parameters should be 463 treated the same as a call with the single parameter 464 \emph on 465 all. 466 467 \emph default 468 As you see, this function recurses a lot. 469 Note, however, that the call 470 \emph on 471 base_src_compile configure all make 472 \emph default 473 is also legal; it will execute 474 \emph on 475 base_src_compile configure configure make make 476 \emph default 477 . 478 \layout Standard 479 480 Now, in your ebuild (or eclass) that inherits from base.eclass, you get the 481 stub function src_compile which calls base_src_compile without parameters. 482 This makes base_src_compile execute 483 \emph on 484 all 485 \emph default 486 , that is, all its sections. 487 You can leave it as-is. 488 If you wish to extend it, you define a new src_compile and call base_src_compil 489 e a section at a time: 490 \layout Code 491 492 src_compile() { 493 \layout Code 494 495 myfunc1 496 \layout Code 497 498 base_src_compile configure 499 \layout Code 500 501 myfunc2 502 \layout Code 503 504 base_src_compile make 505 \layout Code 506 507 } 508 \layout Standard 509 510 The only way to know what functions contain what sections is to read the 511 eclasses. 512 \layout Subsection 513 514 base.eclass 515 \layout Standard 516 517 This eclass defines some default variables and functions, similar to those 518 you'd get by default in a non-inheriting ebuild. 519 For example, it defines: 520 \layout Code 521 522 base_src_unpack() { unpack${A}; } 523 \layout Standard 524 525 Only with sections, of course. 526 \layout Standard 527 528 It is inherited by higher-level eclasses like the kde ones. 529 \layout Subsection 530 531 kde.eclass 532 \layout Standard 533 534 Used by all kde apps, whether directly or indirectly. 535 This is a higher-level eclass, which is intended to provide not only sensible 536 defaults but functions which can be used as-is more often then not. 537 538 \layout Standard 539 540 It inherits c, autoconf and base. 541 \layout Standard 542 543 Read it to find out what it defines. 544 It is quite self-explanatory. 545 \layout Standard 546 547 Briefly, it handles all standard kde-2.1* and 2.2* apps that need configure/make/m 548 ake install cycles. 549 It handles all the std. 550 configure options e.g. 551 objprelink. 552 It also adds kdelibs and qt to DEPEND. 553 \layout Subsection 554 555 kde-base.eclass 556 \layout Standard 557 558 Meant for kde apps part of the core kde distribution. 559 \layout Standard 560 561 Differences from kde.eclass: 562 \layout Itemize 563 564 Sets appropriate DESCRIPTION and HOMEPAGE=www.kde.org. 565 \layout Itemize 566 567 Sets default download path to the correct location on ftp.kde.org and several 568 of its mirrors. 569 \layout Subsection 570 571 kde-i18n.eclass 572 \layout Standard 573 574 Meant for the kde-i18n-* packages. 575 Niche use. 576 \layout Standard 577 578 In fact, all kde-i18n ebuilds are completely identical and so all they have 579 to do is inherit from this eclass. 580 \layout Standard 581 582 Differences from kde.eclass: 583 \layout Standard 584 585 Many. 586 Doesn't inherit c. 587 Doesn't depend on qt. 588 Provides virtual/kde-i18n-\${PV}. 589 Doesn't have 590 \emph on 591 myconf 592 \emph default 593 section in src_compile(). 594 Doesn't have any sections in src_install(). 595 Probably something else I forgot as well. 596 \layout Subsection 597 598 c.eclass 599 \layout Standard 600 601 Adds gcc and glibc to DEPEND and RDEPEND. 602 Not meant to be used alone, inherited by kde*. 603 \layout Subsection 604 605 autoconf.eclass 606 \layout Standard 607 608 Adds make/automake/autoconf to DEPEND. 609 Not meant to be used alone, inherited by kde*. 610 \layout Subsection 611 612 debug.eclass 613 \layout Standard 614 615 Will be written soon. 616 Will provide verbose debug output functions to centralise the numerous 617 618 \emph on 619 echo 620 \emph default 621 s I have scattered around the eclasses. 622 \layout Section 623 624 The inheriting ebuilds 625 \layout Standard 626 627 Not much here as yet. 628 Look at the kde*-2.2.1-r1 ebuilds for examples. 629 As a rule, read the eclass you are inheriting from and put any necessary 630 changes in your ebuild. 631 \layout Standard 632 633 Remember: always extend variables and fnctions. 634 You should almost never need to replace them. 635 \the_end