Merge branch 'org.openembedded.dev' of git://git.openembedded.org/openembedded into...
[openembedded.git] / docs / usermanual / chapters / recipes.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="chapter_recipes" xreflabel="Recipes chapter">
3   <title>Recipes</title>
4
5   <section id="recipes_introduction" xreflabel="introduction">
6     <title>Introduction</title>
7
8     <para>A bitbake recipe is a set of instructions that describe what needs
9     to be done to retrieve the source code for some application, apply any
10     necessary patches, provide any additional files (such as init scripts),
11     compile it, install it and generated binary packages. The end result is a
12     binary package that you can install on your target device, and maybe some
13     intermediate files, such as libraries and headers, which can be used when
14     building other application.</para>
15
16     <para>In many ways the process is similar to creating .deb or .rpm
17     packages for your standard desktop distributions with one major difference
18     - in OpenEmbedded everything is being cross-compiled. This often makes the
19     task far more difficult (depending on how well suited the application is
20     to cross compiling), then it is for other packaging systems and sometime
21     impossible.</para>
22
23     <para>This chapter assumes that you are familiar with working with
24     bitbake, including the work flow, required directory structures, bitbake
25     configuration and the use of monotone. If you are not familiar with these
26     then first take a look at the chapter on bitbake usage.</para>
27   </section>
28
29   <section id="recipes_syntax" xreflabel="syntax">
30     <title>Syntax of recipes</title>
31
32     <para>The basic items that make up a bitbake recipe file are:</para>
33
34     <variablelist>
35       <varlistentry>
36         <term>functions</term>
37
38         <listitem>
39           <para>Functions provide a series of actions to be performed.
40           Functions are usually used to override the default implementation of
41           a task function, or to compliment (append or prepend to an existing
42           function) a default function. Standard functions use sh shell
43           syntax, although access to OpenEmbedded variables and internal
44           methods is also available.</para>
45
46           <para>The following is an example function from the sed
47           recipe:</para>
48
49           <para><screen>do_install () {
50     autotools_do_install
51     install -d ${D}${base_bindir}
52     mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN}
53 }</screen>It is also possible to implement new functions, that are not
54           replacing or complimenting the default functions, which are called
55           between existing tasks. It is also possible to implement functions
56           in python instead of sh. Both of these options are not seen in the
57           majority of recipes.</para>
58         </listitem>
59       </varlistentry>
60
61       <varlistentry>
62         <term>variable assignments and manipulations</term>
63
64         <listitem>
65           <para>Variable assignments allow a value to be assigned to a
66           variable. The assignment may be static text or might include the
67           contents of other variables. In addition to assignment, appending
68           and prepending operations are also supported.</para>
69
70           <para>The follow example shows the some of the ways variables can be
71           used in recipes:<screen>S = "${WORKDIR}/postfix-${PV}"
72 PR = "r4"
73 CFLAGS += "-DNO_ASM"
74 SRC_URI_append = "file://fixup.patch;patch=1"</screen></para>
75         </listitem>
76       </varlistentry>
77
78       <varlistentry>
79         <term>keywords</term>
80
81         <listitem>
82           <para>Only a few keywords are used in bitbake recipes. They are used
83           for things such as including common functions
84           (<emphasis>inherit</emphasis>), loading parts of a recipe from other
85           files (<emphasis>include</emphasis> and
86           <emphasis>require</emphasis>) and exporting variables to the
87           environment (export).</para>
88
89           <para>The following example shows the use of some of these
90           keywords:<screen>export POSTCONF = "${STAGING_BINDIR}/postconf"
91 inherit autoconf
92 require otherfile.inc</screen></para>
93         </listitem>
94       </varlistentry>
95
96       <varlistentry>
97         <term>comments</term>
98
99         <listitem>
100           <para>Any lines that begin with a # are treated as comment lines and
101           are ignored.<screen># This is a comment</screen></para>
102         </listitem>
103       </varlistentry>
104     </variablelist>
105
106     <para>The following is a summary of the most important (and most commonly
107     used) parts of the recipe syntax:</para>
108
109     <variablelist>
110       <varlistentry>
111         <term>Line continuation: \</term>
112
113         <listitem>
114           <para>To split a line over multiple lines you should place a \ at
115           the end of the line that is to be continued on the next line.</para>
116
117           <screen>VAR = "A really long \
118        line"</screen>
119
120           <para>Note that there must not be anything (no spaces or tabs) after
121           the \.</para>
122         </listitem>
123       </varlistentry>
124
125       <varlistentry>
126         <term>Comments: #</term>
127
128         <listitem>
129           <para>Any lines beginning with a # are comments and will be
130           ignored.<screen># This is a comment</screen></para>
131         </listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term>Using variables: ${...}</term>
136
137         <listitem>
138           <para>To access the contents of a variable you need to access it via
139           <emphasis>${&lt;varname&gt;}</emphasis>:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"</screen></para>
140         </listitem>
141       </varlistentry>
142
143       <varlistentry>
144         <term>Quote all assignments</term>
145
146         <listitem>
147           <para>All variable assignments should be quoted with double quotes.
148           (It may work without them at present, but it will not work in the
149           future).<screen>VAR1 = "${OTHERVAR}"
150 VAR2 = "The version is ${PV}"</screen></para>
151         </listitem>
152       </varlistentry>
153
154       <varlistentry>
155         <term>Conditional assignment</term>
156
157         <listitem>
158           <para>Conditional assignement is used to assign a value to a
159           variable, but only when the variable is currently unset. This is
160           commonly used to provide a default value for use when no specific
161           definition is provided by the machine or distro configuration of the
162           users local.conf configuration.</para>
163
164           <para>The following example:<screen>VAR1 ?= "New value"</screen>will
165           set <emphasis role="bold">VAR1</emphasis> to <emphasis>"New
166           value"</emphasis> if its currently empty. However if it was already
167           set it would be unchanged. In the following <emphasis
168           role="bold">VAR1</emphasis> is left with the value
169           <emphasis>"Original value"</emphasis>:<screen>VAR1 = "Original value"
170 VAR1 ?= "New value"</screen></para>
171         </listitem>
172       </varlistentry>
173
174       <varlistentry>
175         <term>Appending: +=</term>
176
177         <listitem>
178           <para>You can append values to existing variables using the
179           <emphasis>+=</emphasis> operator. Note that this operator will add a
180           space between the existing content of the variable and the new
181           content.<screen>SRC_URI += "file://fix-makefile.patch;patch=1"</screen></para>
182         </listitem>
183       </varlistentry>
184
185       <varlistentry>
186         <term>Prepending: =+</term>
187
188         <listitem>
189           <para>You can prepend values to existing variables using the
190           <emphasis>=+</emphasis> operator. Note that this operator will add a
191           space between the new content and the existing content of the
192           variable.<screen>VAR =+ "Starts"</screen></para>
193         </listitem>
194       </varlistentry>
195
196       <varlistentry>
197         <term>Appending: _append</term>
198
199         <listitem>
200           <para>You can append values to existing variables using the
201           <emphasis>_append</emphasis> method. Note that this operator does
202           not add any additional space, and it is applied after all the
203           <emphasis>+=</emphasis>, and <emphasis>=+</emphasis> operators have
204           been applied.</para>
205
206           <para>The following example show the space being explicitly added to
207           the start to ensure the appended value is not merged with the
208           existing value:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"</screen>The
209           <emphasis>_append</emphasis> method can also be used with overrides,
210           which result in the actions only being performed for the specified
211           target or machine: [TODO: Link to section on overrides]<screen>SRC_URI_append_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
212           that the appended information is a variable itself, and therefore
213           it's possible to used <emphasis>+=</emphasis> or
214           <emphasis>=+</emphasis> to assign variables to the
215           <emphasis>_append</emphasis> information:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"
216 SRC_URI_append += "file://fix-install.patch;patch=1"</screen></para>
217         </listitem>
218       </varlistentry>
219
220       <varlistentry>
221         <term>Prepending: _prepend</term>
222
223         <listitem>
224           <para>You can prepend values to existing variables using the
225           _prepend method. Note that this operator does not add any additional
226           space, and it is applied after all the <emphasis>+=</emphasis>, and
227           <emphasis>=+</emphasis> operators have been applied.</para>
228
229           <para>The following example show the space being explicitly added to
230           the end to ensure the prepended value is not merged with the
231           existing value:<screen>CFLAGS_prepend = "-I${S}/myincludes "</screen>The
232           <emphasis>_prepend</emphasis> method can also be used with
233           overrides, which result in the actions only being performed for the
234           specified target or machine: [TODO: Link to section on
235           overrides]<screen>CFLAGS_prepend_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
236           that the appended information is a variable itself, and therefore
237           it's possible to used <emphasis>+=</emphasis> or
238           <emphasis>=+</emphasis> to assign variables to the
239           <emphasis>_prepend</emphasis> information:<screen>CFLAGS_prepend = "-I${S}/myincludes "
240 CFLAGS_prepend += "-I${S}/myincludes2 "</screen>Note also the lack of a space
241           when using += to append to a prepend value - remember that the +=
242           operator is adding space itself.</para>
243         </listitem>
244       </varlistentry>
245
246       <varlistentry>
247         <term>Spaces vs tabs</term>
248
249         <listitem>
250           <para>Spaces should be used for indentation, not hard tabs. Both
251           currently work, however it is a policy decision of OE that spaces
252           always be used.</para>
253         </listitem>
254       </varlistentry>
255
256       <varlistentry>
257         <term>Style: oe-stylize.py</term>
258
259         <listitem>
260           <para>To help with using the correct style in your recipes there is
261           a python script in the contrib directory called
262           <emphasis>oe-stylize.py</emphasis> which can be used to reformat
263           your recipes to the correct style. The output will contain a list of
264           warning (to let you know what you did wrong) which should be edited
265           out before using the new file.<screen>contrib/oe-stylize.py myrecipe.bb &gt; fixed-recipe.bb
266 vi fixed-recipe.bb
267 mv fixed.recipe.bb myrecipe.bb</screen></para>
268         </listitem>
269       </varlistentry>
270
271       <varlistentry>
272         <term>Using python for complex operations: ${@...}</term>
273
274         <listitem>
275           <para>For more advanced processing it is possible to use python code
276           during variable assignments, for doing search and replace on a
277           variable for example.</para>
278
279           <para>Python code is indicated by a proceeding @ sign in the
280           variable assignment.<screen>CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"</screen>More
281           information about using python is available in the <xref
282           linkend="recipes_advanced_python" /> section.</para>
283         </listitem>
284       </varlistentry>
285
286       <varlistentry>
287         <term>Shell syntax</term>
288
289         <listitem>
290           <para>When describing a list of actions to take shell syntax is used
291           (as if you were writing a shell script). You should ensure that you
292           script would work with a generic sh and not require any bash (or
293           other shell) specific functionality. The same applies to various
294           system utilities (sed, grep, awk etc) that you may wish to use. If
295           in doubt you should check with multiple implementations - including
296           those from busybox.</para>
297         </listitem>
298       </varlistentry>
299     </variablelist>
300
301     <para>For a detailed description of the syntax for the bitbake recipe
302     files you should refer to the bitbake use manual.</para>
303   </section>
304
305   <section id="recipes_versioning" xreflabel="versioning">
306     <title>Recipe naming: Names, versions and releases</title>
307
308     <para>Recipes in OpenEmbedded use a standard naming convention that
309     includes the package name and version number in the filename. In addition
310     to the name and version there is also a release number, which is indicates
311     changes to the way the package is built and/or packaged. The release
312     number is contained within the recipe itself.</para>
313
314     <para>The expected format of recipe name is:<screen>&lt;package-name&gt;_&lt;version&gt;.bb</screen></para>
315
316     <para>where <emphasis>&lt;package-name&gt;</emphasis> is the name of the
317     package (application, library, module, or whatever it is that is being
318     packaged) and <emphasis>version</emphasis> is the version number.</para>
319
320     <para>So a typical recipe name would be:<screen>strace_4.5.14.bb</screen>which
321     would be for version <emphasis>4.5.14</emphasis> of the
322     <emphasis>strace</emphasis> application.</para>
323
324     <para>The release version is defined via the package release variable, PR,
325     contained in the recipe. The expected format is:<screen>r&lt;n&gt;</screen>where
326     <emphasis>&lt;n&gt;</emphasis> is an integer number starting from 0
327     initially and then incremented each time the recipe, or something that
328     effects the recipe, is modified. So a typical definition of the release
329     would be:<screen>PR = "r1"</screen>to specify release number
330     <emphasis>1</emphasis> (the second release, the first would have been
331     <emphasis>0</emphasis>). If there is no definition of PR in the recipe
332     then the default value of "r0" is used.</para>
333
334     <para><note>
335         <para>It is good practice to always define PR in your recipes, even
336         for the <emphasis>"r0"</emphasis> release, so that when editing the
337         recipe it is clear that the PR number needs to be updated.</para>
338
339         <para>You should always increment PR when modifying a recipe.
340         Sometimes this can be avoided if the change will have no effect on the
341         actual packages generated by the recipe, such as updating the SRC_URI
342         to point to a new host. If in any doubt then you should increase the
343         PR regardless of what has been changed.</para>
344
345         <para>The PR value should never be decremented. If you accidentally
346         submit a large PR value for example then it should be left at the
347         value and just increased for new releases, not reset back to a lower
348         version.</para>
349       </note></para>
350
351     <para>When a recipe is being processed some variables are automatically
352     set based on the recipe file name and can be used for other purposes from
353     within the recipe itself. These include:</para>
354
355     <variablelist>
356       <varlistentry>
357         <term>PN</term>
358
359         <listitem>
360           <para>The package name. Determined from the recipe filename -
361           everything up until the first underscore is considered to be the
362           package name. For the <command>strace_4.5.14.bb</command> recipe the
363           PN variable would be set to <emphasis>"strace"</emphasis>.</para>
364         </listitem>
365       </varlistentry>
366
367       <varlistentry>
368         <term>PV</term>
369
370         <listitem>
371           <para>The package version. Determined from the recipe filename -
372           everything between the first underscore and the final .bb is
373           considered to be the package version. For the
374           <command>strace_4.5.14.bb</command> recipe the PV variable would be
375           set to <emphasis>"4.5.14"</emphasis>.</para>
376         </listitem>
377       </varlistentry>
378
379       <varlistentry>
380         <term>PR</term>
381
382         <listitem>
383           <para>The package release. This is explicitly set in the recipe, or
384           if not set it defaults to "<emphasis>r0"</emphasis> if not
385           set.</para>
386         </listitem>
387       </varlistentry>
388
389       <varlistentry>
390         <term>P</term>
391
392         <listitem>
393           <para>The package name and versions separated by a hyphen.<screen>P = "${PN}-${PV}"</screen></para>
394
395           <para>For the <command>strace_4.5.14.bb</command> recipe the P
396           variable would be set to
397           <emphasis>"strace-4.5.14"</emphasis>.</para>
398         </listitem>
399       </varlistentry>
400
401       <varlistentry>
402         <term>PF</term>
403
404         <listitem>
405           <para>The package name, version and release separated by
406           hyphens.<screen>PF = "${PN}-${PV}-${PR}"</screen></para>
407
408           <para>For the s<command>trace_4.5.14.bb recipe</command>, with PR
409           set to <emphasis>"r1"</emphasis> in the recipe, the PF variable
410           would be set to <emphasis>"strace-4.5.14-r1"</emphasis>.</para>
411         </listitem>
412       </varlistentry>
413     </variablelist>
414
415     <para>While some of these variables are not commonly used in recipes (they
416     are used internally though) both PN and PV are used a lot.</para>
417
418     <para>In the following example we are instructing the packaging system to
419     include an additional directory in the package. We use PN to refer to the
420     name of the package rather than spelling out the package name:<screen>FILES_${PN} += "${sysconfdir}/myconf"</screen></para>
421
422     <para>In the next example we are specifying the URL for the package
423     source, by using PV in place of the actual version number it is possible
424     to duplicate, or rename, the recipe for a new version without having to
425     edit the URL:<screen>SRC_URI = "ftp://ftp.vim.org/pub/vim/unix/vim-${PV}.tar.bz2"</screen></para>
426   </section>
427
428   <section id="recipes_variables" xreflabel="variables">
429     <title>Variables</title>
430
431     <para>One of the most confusing part of bitbake recipes for new users is
432     the large amount of variables that appear to be available to change and/or
433     control the behaviour of some aspect of the recipe. Some variables, such
434     as those derived from the file name are reasonably obvious, others are not
435     at all obvious.</para>
436
437     <para>There are several places where these variables are derived from
438     and/or used:</para>
439
440     <orderedlist>
441       <listitem>
442         <para>A large number of variables are defined in the bitbake
443         configuration file conf/bitbake.conf - it's often a good idea to look
444         through that file when trying to determine what a particular variable
445         means.</para>
446       </listitem>
447
448       <listitem>
449         <para>Machine and distribution configuration files in conf/machine and
450         conf/distro will sometimes define some variables specific to the
451         machine and/or distribution. You should look at the appropriate files
452         for your targets to see if anything is being defined that effects the
453         recipes you are building.</para>
454       </listitem>
455
456       <listitem>
457         <para>Bitbake itself will define some variables. The FILE variables
458         that defines the name of the bitbake recipe being processed is set by
459         bitbake itself for example. Refer to the bitbake manual for more
460         information on the variables that bitbake sets.</para>
461       </listitem>
462
463       <listitem>
464         <para>The classes, that are used via the inherit keyword, define
465         and/or use the majority of the remaining variables. A class is a like
466         a library that contain parts of a bitbake recipe that are used by
467         multiple recipes. To make them usable in more situations they often
468         include a large number of variables to control how the class
469         operates.</para>
470       </listitem>
471     </orderedlist>
472
473     <para>Another important aspect is that there are three different types of
474     things that binaries and libraries are used for and they often have
475     different variables for each. These include:</para>
476
477     <variablelist>
478       <varlistentry>
479         <term>target</term>
480
481         <listitem>
482           <para>Refers to things built for the target are expected to be run
483           on the target device itself.</para>
484         </listitem>
485       </varlistentry>
486
487       <varlistentry>
488         <term>native</term>
489
490         <listitem>
491           <para>Refers to things built to run natively on the build host
492           itself.</para>
493         </listitem>
494       </varlistentry>
495
496       <varlistentry>
497         <term>cross</term>
498
499         <listitem>
500           <para>Refers to things built to run natively on the build host
501           itself, but produce output which is suitable for the target device.
502           Cross versions of packages usually only exist for things like
503           compilers and assemblers - i.e. things which are used to produce
504           binary applications themselves.</para>
505         </listitem>
506       </varlistentry>
507     </variablelist>
508   </section>
509
510   <section id="recipes_header" xreflabel="header">
511     <title>Header</title>
512
513     <para>Practically all recipes start was the header section which describes
514     various aspects of the package that is being built. This information is
515     typically used directly by the package format (such as ipkg or deb) as
516     it's meta data used to describe the package.</para>
517
518     <para>Variables used in the header include:</para>
519
520     <variablelist>
521       <varlistentry>
522         <term>DESCRIPTION</term>
523
524         <listitem>
525           <para>Describes what the software does. Hopefully this gives enough
526           information to a use to know if it's the right application for
527           them.</para>
528
529           <para>The default description is: <emphasis>"Version ${PV}-${PR} of
530           package ${PN}"</emphasis>.</para>
531         </listitem>
532       </varlistentry>
533
534       <varlistentry>
535         <term>HOMEPAGE</term>
536
537         <listitem>
538           <para>The URL of the home page of the application where new releases
539           and more information can be found.</para>
540
541           <para>The default homepage is <emphasis>"unknown"</emphasis>.</para>
542         </listitem>
543       </varlistentry>
544
545       <varlistentry>
546         <term>SECTION</term>
547
548         <listitem>
549           <para>The section is used to categorise the application into a
550           specific group. Often used by GUI based installers to help users
551           when searching for software.</para>
552
553           <para>See <xref linkend="section_variable" /> for a list of the
554           available sections.</para>
555
556           <para>The default section is <emphasis>"base"</emphasis>.</para>
557         </listitem>
558       </varlistentry>
559
560       <varlistentry>
561         <term>PRIORITY</term>
562
563         <listitem>
564           <para>The default priority is
565           <emphasis>"optional"</emphasis>.</para>
566         </listitem>
567       </varlistentry>
568
569       <varlistentry>
570         <term>LICENSE</term>
571
572         <listitem>
573           <para>The license for the application. If it is not one of the
574           standard licenses then the license itself must be included
575           (where?).</para>
576
577           <para>As well as being used in the package meta-data the license is
578           also used by the src_distribute class.</para>
579
580           <para>The default license is <emphasis>"unknown"</emphasis>.</para>
581         </listitem>
582       </varlistentry>
583     </variablelist>
584   </section>
585
586   <section id="recipes_sources" xreflabel="sources">
587     <title>Sources: Downloading, patching and additional files</title>
588
589     <para>A recipes purpose is to describe how to take a software package and
590     build it for your target device. The location of the source file (or
591     files) is specified via the <xref linkend="src_uri_variable" /> in the
592     recipe. This can describe several types of URI's, the most common
593     are:</para>
594
595     <variablelist>
596       <varlistentry>
597         <term>http and https</term>
598
599         <listitem>
600           <para>Specifies files to be downloaded. A copy is stored locally so
601           that future builds will not download the source again.</para>
602         </listitem>
603       </varlistentry>
604
605       <varlistentry>
606         <term>cvs, svn and git</term>
607
608         <listitem>
609           <para>Specifies that the files are to be retrieved using the
610           specified version control system.</para>
611         </listitem>
612       </varlistentry>
613
614       <varlistentry>
615         <term>files</term>
616
617         <listitem>
618           <para>Plain files which are included locally. These can be used for
619           adding documentation, init scripts or any other files that need to
620           be added to build the package under openembedded.</para>
621         </listitem>
622       </varlistentry>
623
624       <varlistentry>
625         <term>patches</term>
626
627         <listitem>
628           <para>Patches are plain files which are treated as patched and
629           automatically applied.</para>
630         </listitem>
631       </varlistentry>
632     </variablelist>
633
634     <para>If a http, https or file URI refers to a compressed file, an archive
635     file or a compressed archive file, such as .tar.gz or .zip, then the files
636     will be uncompressed and extracted from the archive automatically.</para>
637
638     <para>Archive files will be extracted from with the working directory,
639     <emphasis role="bold">${WORKDIR}</emphasis> and plain files will be copied
640     into the same directory. Patches will be applied from within the unpacked
641     source directory, <emphasis role="bold">${S}</emphasis>. (Details on these
642     directories is provided in the next section.)</para>
643
644     <para>The following example from the havp recipe shows a typical <emphasis
645     role="bold">SRC_URI</emphasis> definition:<screen>SRC_URI = "http://www.server-side.de/download/havp-${PV}.tar.gz \
646            file://sysconfdir-is-etc.patch;patch=1 \
647            file://havp.init \
648            file://doc.configure.txt \
649            file://volatiles.05_havp"</screen></para>
650
651     <para>This describes several files</para>
652
653     <variablelist>
654       <varlistentry>
655         <term>http://www.server-side.de/download/havp-${PV}.tar.gz</term>
656
657         <listitem>
658           <para>This is the URI of the havp source code. Note the use of the
659           <emphasis role="bold">${PV}</emphasis> variable to specify the
660           version. This is done to enable the recipe to be renamed for a new
661           version without the need the edit the recipe itself. Because this is
662           a .tar.gz compressed archive the file will be decompressed and
663           extracted in the working dir <emphasis
664           role="bold">${WORKDIR}</emphasis>.</para>
665         </listitem>
666       </varlistentry>
667
668       <varlistentry>
669         <term>file://sysconfdir-is-etc.patch;patch=1</term>
670
671         <listitem>
672           <para>This is a local file that is used to patch the extracted
673           source code. The patch=1 is what specifies that this is a patch. The
674           patch will be applied from the unpacked source directory, <emphasis
675           role="bold">${S}</emphasis>. In this case <emphasis
676           role="bold">${S}</emphasis> will be <emphasis
677           role="bold">${WORKDIR}/havp-0.82</emphasis>, and luckily the
678           <emphasis role="bold">havp-0.82.tar.gz</emphasis> file extracts
679           itself into that directory (so no need to explicitly change
680           <emphasis role="bold">${S}</emphasis>).</para>
681         </listitem>
682       </varlistentry>
683
684       <varlistentry>
685         <term>file://havp.init file://doc.configure.txt
686         file://volatiles.05_havp"</term>
687
688         <listitem>
689           <para>These are plain files which are just copied into the working
690           directory <emphasis role="bold">${WORKDIR}</emphasis>. These are
691           then used during the install task in the recipe to provide init
692           scripts, documentation and volatiles configuration information for
693           the package.</para>
694         </listitem>
695       </varlistentry>
696     </variablelist>
697
698     <para>Full details on the <emphasis role="bold">SRC_URI</emphasis>
699     variable and all the support URI's is available in the <xref
700     linkend="src_uri_variable" /> section of the reference chapter.</para>
701   </section>
702
703   <section id="recipes_directories" xreflabel="directories">
704     <title>Directories: What goes where</title>
705
706     <para>A large part of the work or a recipe is involved with specifying
707     where files and found and where they have to go. It's important for
708     example that programs do not try and use files from <emphasis
709     role="bold">/usr/include</emphasis> or <emphasis
710     role="bold">/usr/lib</emphasis> since they are for the host system, not
711     the target. Similarly you don't want programs installed into <emphasis
712     role="bold">/usr/bin</emphasis> since that may overwrite your host system
713     programs with versions that don't work on the host!</para>
714
715     <para>The following are some of the directories commonly referred to in
716     recipes and will be described in more detail in the rest of this
717     section:</para>
718
719     <variablelist>
720       <varlistentry>
721         <term>Working directory: WORKDIR</term>
722
723         <listitem>
724           <para>This working directory for a recipe is where archive files
725           will be extracted, plain files will be placed, subdirectories for
726           logs, installed files etc will be created.</para>
727         </listitem>
728       </varlistentry>
729
730       <varlistentry>
731         <term>Unpacked source code directory: S</term>
732
733         <listitem>
734           <para>This is where patches are applied and where the program is
735           expected to be compiled in.</para>
736         </listitem>
737       </varlistentry>
738
739       <varlistentry>
740         <term>Destination directory: D</term>
741
742         <listitem>
743           <para>The destination directory. This is where your package should
744           be installed into. The packaging system will then take the files
745           from directories under here and package them up for installation on
746           the target.</para>
747         </listitem>
748       </varlistentry>
749
750       <varlistentry>
751         <term>Installation directories: bindir, docdir, ...</term>
752
753         <listitem>
754           <para>There are a set of variables available to describe all of the
755           paths on the target that you may want to use. Recipes should use
756           these variables rather than hard coding any specific paths.</para>
757         </listitem>
758       </varlistentry>
759
760       <varlistentry>
761         <term>Staging directories: STAGING_LIBDIR, STAGING_INCDIR, ...</term>
762
763         <listitem>
764           <para>Staging directories are a special area for headers, libraries
765           and other files that are generated by one recipe that may be needed
766           by another recipe. A library package for example needs to make the
767           library and headers available to other recipes so that they can link
768           against them.</para>
769         </listitem>
770       </varlistentry>
771
772       <varlistentry>
773         <term>File path directories: FILE, FILE_DIRNAME, FILESDIR,
774         FILESPATH</term>
775
776         <listitem>
777           <para>These directories are used to control where files are found.
778           Understanding these can help you separate patches for different
779           versions or releases of your recipes and/or use the same patch over
780           multiple versions etc.</para>
781         </listitem>
782       </varlistentry>
783     </variablelist>
784
785     <section>
786       <title>WORKDIR: The working directory</title>
787
788       <para>The working directory is where the source code is extracted, to
789       which plain files (not patches) are copied and where the logs and
790       installation files are created. A typical reason for needing to
791       reference the work directory is for the handling of non patch
792       files.</para>
793
794       <para>If we take a look at the recipe for quagga we can see an example
795       non patch files for configuration and init scripts:<screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
796            file://fix-for-lib-inpath.patch;patch=1 \
797            file://quagga.init \
798            file://quagga.default \
799            file://watchquagga.init \
800            file://watchquagga.default"</screen>The recipe has two init files
801       and two configuration files, which are not patches, but are actually
802       files that it wants to include in the generated packages. Bitbake will
803       copy these files into the work directory. So to access them during the
804       install task we refer to them via the <emphasis
805       role="bold">WORKDIR</emphasis> variable:<screen>do_install () {
806     # Install init script and default settings
807     install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
808     install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga
809     install -m 0644 ${WORKDIR}/watchquagga.default ${D}${sysconfdir}/default/watchquagga
810     install -m 0755 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga
811     install -m 0755 ${WORKDIR}/watchquagga.init ${D}${sysconfdir}/init.d/watchquagga
812     ...</screen></para>
813     </section>
814
815     <section>
816       <title>S: The unpacked source code directory</title>
817
818       <para>Bitbake expects to find the extracted source for a package in a
819       directory called <emphasis
820       role="bold">&lt;packagename&gt;-&lt;version&gt;</emphasis> in the
821       <emphasis role="bold">WORKDIR</emphasis> directory. This is the
822       directory in which it will change into before patching, compiling and
823       installating the package.</para>
824
825       <para>For example, we have a package called <emphasis
826       role="bold">widgets_1.2.bb</emphasis> which we are extracting from the
827       <emphasis role="bold">widgets-1.2.tar.gz</emphasis> file. Bitbake
828       expects the source to end up in a directory called <emphasis
829       role="bold">widgets-1.2</emphasis> within the work directory. If the
830       source does not end up in this directory then bitbake needs to be told
831       this by explicitly setting <emphasis role="bold">S</emphasis>.</para>
832
833       <para>If <emphasis role="bold">widgets-1.2.tar.gz</emphasis> actually
834       extracts into a directory called <emphasis
835       role="bold">widgets</emphasis>, without the version number, instead of
836       <emphasis role="bold">widgets-1.2</emphasis> then the <emphasis
837       role="bold">S</emphasis> variable will be wrong and patching and/or
838       compiling will fail. Therefore we need to override the default value of
839       <emphasis role="bold">S</emphasis> to specify the directory the source
840       was actually extracted into:<screen>SRC_URI = "http://www.example.com/software/widgets-${PN}.tar.gz"
841 S = "${WORKDIR}/widgets"</screen></para>
842     </section>
843
844     <section>
845       <title>D: The destination directory</title>
846
847       <para>The destination directory is where the completed application and
848       all of it's files are installed into in preparation for packaging.
849       Typically an installation would places files in directories such as
850       <emphasis role="bold">/etc</emphasis> and <emphasis
851       role="bold">/usr/bin</emphasis> by default. Since those directories are
852       used by the host system we do not want the packages to install into
853       those locations. Instead they need to install into the directories below
854       the destination directory.</para>
855
856       <para>So instead of installing into <emphasis
857       role="bold">/usr/bin</emphasis> the package needs to install into
858       <emphasis role="bold">${D}/usr/bin</emphasis>.</para>
859
860       <para>The following example from arpwatch shows the make install command
861       being passed a <emphasis role="bold">${D}</emphasis> as the <emphasis
862       role="bold">DESTDIR</emphasis> variable to control where the makefile
863       installs everything:<screen>do_install() {
864         ...
865         oe_runmake install DESTDIR=${D}</screen></para>
866
867       <para>The following example from quagga shows the use of the destination
868       directory to install the configuration files and init scripts for the
869       package:<screen>do_install () {
870         # Install init script and default settings
871         install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
872         install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga
873         install -m 0755 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga</screen><note>
874           <para>You should not use directories such as <emphasis
875           role="bold">/etc</emphasis> and <emphasis
876           role="bold">/usr/bin</emphasis> directly in your recipes. You should
877           use the variables that define these locations. The full list of
878           these variables can be found in the <xref
879           linkend="directories_installation" /> section of the reference
880           chapter.</para>
881         </note></para>
882     </section>
883
884     <section>
885       <title>Staging directories</title>
886
887       <para>Staging is used to make libraries, headers and binaries available
888       for the build of one recipe for use by another recipe. Building a
889       library for example requires that packages be created containing the
890       libraries and headers for development on the target as well as making
891       them available on the host for building other packages that need the
892       libraries and headers.</para>
893
894       <para>Making the libraries, headers and binaries available for use by
895       other recipes on the host is called staging and is performed by the
896       <emphasis>stage</emphasis> task in the recipe. Any recipes that contain
897       items that are required to build other packages should have a
898       <emphasis>stage</emphasis> task to make sure the items are all correctly
899       placed into the staging area. The following example from clamav show the
900       clamav library and header being placed into the staging area:<screen>do_stage () {
901         oe_libinstall -a -so libclamav ${STAGING_LIBDIR}
902         install -m 0644 libclamav/clamav.h ${STAGING_INCDIR}
903 }</screen></para>
904
905       <para>The following from the p3scan recipe show the path to the clamav
906       library and header being passed to the configure script. Without this
907       the configure script would either fail to find the library, or worse
908       still search the host systems directories for the library. Passing in
909       the location results in it searching the correct location and finding
910       the clamav library and headers:<screen>EXTRA_OECONF = "--with-clamav=${STAGING_LIBDIR}/.. \
911                 --with-openssl=${STAGING_LIBDIR}/.. \
912                 --disable-ripmime"</screen>While the staging directories are
913       automatically added by OpenEmbedded to the compiler and linking commands
914       it is sometimes necessary, as in the p3scan example above, to explicitly
915       specify the location of the staging directories. Typically this is
916       needed for autoconf scripts that search in multiple places for the
917       libraries and headers.</para>
918
919       <note>
920         <para>Many of the helper classes, such as pkgconfig and autotools add
921         appropriate commands to the stage task for you. Check with the
922         individual class descriptions in the reference section to determine
923         what each class is staging automatically for you.</para>
924       </note>
925
926       <para>A full list of staging directories can be found in the <xref
927       linkend="directories_staging" /> section in the reference
928       chapter.</para>
929     </section>
930
931     <section id="recipes_filespath_dir" xreflabel="FILESPATH/FILESDIR">
932       <title>FILESPATH/FILESDIR: Finding local files</title>
933
934       <para>The file related variables are used by bitbake to determine where
935       to look for patches and local files.</para>
936
937       <para>Typically you will not need to modify these, but it is useful to
938       be aware of the default values. In particular when searching for patches
939       and/or files (file:// URI's), the default search path is:</para>
940
941       <variablelist>
942         <varlistentry>
943           <term>${FILE_DIRNAME}/${PF}</term>
944
945           <listitem>
946             <para>This is the package name, version and release, such as
947             "<emphasis role="bold">strace-4.5.14-r1</emphasis>". This is very
948             rarely used since the patches would only be found for the one
949             exact release of the recipe.</para>
950           </listitem>
951         </varlistentry>
952
953         <varlistentry>
954           <term>${FILE_DIRNAME}/${P}</term>
955
956           <listitem>
957             <para>This is the package name and version, such as "<emphasis
958             role="bold">strace-4.5.14</emphasis>". This is by far the most
959             common place to place version specified patches.</para>
960           </listitem>
961         </varlistentry>
962
963         <varlistentry>
964           <term>${FILE_DIRNAME}/${PN}</term>
965
966           <listitem>
967             <para>This is the package name only, such as "<emphasis
968             role="bold">strace</emphasis>". This is not commonly used.</para>
969           </listitem>
970         </varlistentry>
971
972         <varlistentry>
973           <term>${FILE_DIRNAME}/files</term>
974
975           <listitem>
976             <para>This is just the directory called "<emphasis
977             role="bold">files</emphasis>". This is commonly used for patches
978             and files that apply to all version of the package.</para>
979           </listitem>
980         </varlistentry>
981
982         <varlistentry>
983           <term>${FILE_DIRNAME}/</term>
984
985           <listitem>
986             <para>This is just the base directory of the recipe. This is very
987             rarely used since it would just clutter the main directory.</para>
988           </listitem>
989         </varlistentry>
990       </variablelist>
991
992       <para>Each of the paths is relative to <emphasis
993       role="bold">${FILE_DIRNAME}</emphasis> which is the directory in which
994       the recipe that is being processed is located.</para>
995
996       <para>The full set of variables that control the file locations and
997       patch are:</para>
998
999       <variablelist>
1000         <varlistentry>
1001           <term>FILE</term>
1002
1003           <listitem>
1004             <para>The path to the .bb file which is currently being
1005             processed.</para>
1006           </listitem>
1007         </varlistentry>
1008
1009         <varlistentry>
1010           <term>FILE_DIRNAME</term>
1011
1012           <listitem>
1013             <para>The path to the directory which contains the FILE which is
1014             currently being processed.<screen>FILE_DIRNAME = "${@os.path.dirname(bb.data.getVar('FILE', d))}"</screen></para>
1015           </listitem>
1016         </varlistentry>
1017
1018         <varlistentry>
1019           <term>FILESPATH</term>
1020
1021           <listitem>
1022             <para>The default set of directories which are available to use
1023             for the file:// URI's. Each directory is searched, in the
1024             specified order, in an attempt to find the file specified by each
1025             file:// URI: <screen>FILESPATH = "${FILE_DIRNAME}/${PF}:${FILE_DIRNAME}/${P}:\
1026 ${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}"</screen></para>
1027           </listitem>
1028         </varlistentry>
1029
1030         <varlistentry>
1031           <term>FILESDIR</term>
1032
1033           <listitem>
1034             <para>The default directory to search for file:// URI's. Only used
1035             if the file is not found in FILESPATH. This can be used to easily
1036             add one additional directory to the search path without having to
1037             modify the default FILESPATH setting. By default this is just the
1038             first directory from FILESPATH. <screen>FILESDIR = "${@bb.which(bb.data.getVar('FILESPATH', d, 1), '.')}" </screen></para>
1039           </listitem>
1040         </varlistentry>
1041       </variablelist>
1042
1043       <para>Sometimes recipes will modify the <emphasis
1044       role="bold">FILESPATH</emphasis> or <emphasis
1045       role="bold">FILESDIR</emphasis> variables to change the default search
1046       path for patches and files. The most common situation in which this is
1047       done is when one recipe includes another one in which the default values
1048       will be based on the name of the package doing the including, not the
1049       included package. Typically the included package will expect the files
1050       to be located in a directories based on it's own name.</para>
1051
1052       <para>As an example the m4-native recipe includes the m4 recipe. This is
1053       fine, except that the m4 recipes expects its files and patches to be
1054       located in a directory called <emphasis role="bold">m4</emphasis>
1055       directory while the native file name results in them being searched for
1056       in <emphasis role="bold">m4-native</emphasis>. So the m4-native recipe
1057       sets the <emphasis role="bold">FILESDIR</emphasis> variable to the value
1058       that of m4 to add the actual m4 directory (where m4 itself has its files
1059       stored) to the list of directories search for:<screen>        include m4_${PV}.bb
1060         inherit native
1061         FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/m4"</screen></para>
1062     </section>
1063   </section>
1064
1065   <section id="recipes_examples" xreflabel="examples">
1066     <title>Basic examples</title>
1067
1068     <para>By now you should know enough about the bitbake recipes to be able
1069     to create a basic recipe. We'll cover a simple single file recipe and then
1070     a more advanced example that uses the autotools helper class (to be
1071     described later) to build an autoconf based package.</para>
1072
1073     <section id="recipes_helloworld_example" xreflabel="hello world example">
1074       <title>Hello world</title>
1075
1076       <para>Now it's time for our first recipe. This is going to be one of the
1077       simplest possible recipes: all code is included and there's only one
1078       file to compile and one readme file. While this isn't all that common
1079       it's a useful example because it doesn't depend on any of the helper
1080       classes which can sometime hide a lot of what is going on.</para>
1081
1082       <para>First we'll create the myhelloworld.c file and a readme file.
1083       We'll place this in the files subdirectory, which is one of the places
1084       that is searched for file:// URI's:<screen>mkdir recipes/myhelloworld
1085 mkdir recipes/myhelloworld/files
1086 cat &gt; recipes/myhelloworld/files/myhelloworld.c
1087 #include &lt;stdio.h&gt;
1088
1089 int main(int argc, char** argv)
1090 {
1091         printf("Hello world!\n");
1092         return 0;
1093 }
1094 ^D
1095 cat &gt; recipes/myhelloworld/files/README.txt
1096 Readme file for myhelloworld.
1097 ^D</screen></para>
1098
1099       <para>Now we have a directory for our recipe, recipes/myhelloworld, and
1100       we've created a files subdirectory in there to store our local files.
1101       We've created two local files, the C source code for our helloworld
1102       program and a readme file. Now we need to create the bitbake
1103       recipe.</para>
1104
1105       <para>First we need the header section, which will contain a description
1106       of the package and the release number. We'll leave the other header
1107       variables out for now:<screen>DESCRIPTION = "My hello world program"
1108 PR = "r0"</screen></para>
1109
1110       <para>Next we need to tell it which files we want to be included in the
1111       recipe, which we do via file:// URI's and the SRC_URI variable:<screen>SRC_URI = "file://myhelloworld.c \
1112            file://README.txt"</screen></para>
1113
1114       <para>Note the use of the \ to continue a file and the file of file://
1115       local URI's, rather than other types such as http://.</para>
1116
1117       <para>Now we need provide a compile task which tells bitbake how to
1118       compile this program. We do this by defining a do_compile function in
1119       the recipe and providing the appropriate commands:</para>
1120
1121       <para><screen>do_compile() {
1122         ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
1123 }</screen></para>
1124
1125       <para>Note the:</para>
1126
1127       <itemizedlist>
1128         <listitem>
1129           <para>use of the pre-defined compiler variables, <emphasis
1130           role="bold">${CC}</emphasis>, <emphasis
1131           role="bold">${CFLAGS}</emphasis> and <emphasis
1132           role="bold">${LDFLAGS}</emphasis>. These are setup automatically to
1133           contain the settings required to cross-compile the program for the
1134           target.</para>
1135         </listitem>
1136
1137         <listitem>
1138           <para>use of <emphasis role="bold">${WORKDIR}</emphasis> to find the
1139           source file. As mentioned previously all files are copied into the
1140           working directory and can be referenced via the <emphasis
1141           role="bold">${WORKDIR}</emphasis> variable.</para>
1142         </listitem>
1143       </itemizedlist>
1144
1145       <para>And finally we want to install the program and readme file into
1146       the destination directory so that it'll be packaged up correctly. This
1147       is done via the install task, so we need to define a do_install function
1148       in the recipe to describe how to install the package:<screen>do_install() {
1149         install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
1150         install -m 0644 ${S}/myhelloworld ${D}${bindir}
1151         install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
1152 }</screen></para>
1153
1154       <para>Note the:</para>
1155
1156       <itemizedlist>
1157         <listitem>
1158           <para>use the <emphasis role="bold">install</emphasis> command to
1159           create directories and install the files, not cp.</para>
1160         </listitem>
1161
1162         <listitem>
1163           <para>way directories are created before we attempt to install any
1164           files into them. The install command takes care of any
1165           subdirectories that are missing, so we only need to create the full
1166           path to the directory - no need to create the subdirectories.</para>
1167         </listitem>
1168
1169         <listitem>
1170           <para>way we install everything into the destination directory via
1171           the use of the <emphasis role="bold">${D}
1172           </emphasis>variable.</para>
1173         </listitem>
1174
1175         <listitem>
1176           <para>way we use variables to refer to the target directories, such
1177           as <emphasis role="bold">${bindir}</emphasis> and <emphasis
1178           role="bold">${docdir}</emphasis>.</para>
1179         </listitem>
1180
1181         <listitem>
1182           <para>use of <emphasis role="bold">${WORKDIR}</emphasis> to get
1183           access to the <emphasis role="bold">README.txt</emphasis> file,
1184           which was provided via file:// URI.</para>
1185         </listitem>
1186       </itemizedlist>
1187
1188       <para>We'll consider this release 0 and version 0.1 of a program called
1189       helloworld. So we'll name the recipe myhelloworld_0.1.bb:<screen>cat &gt; recipes/myhelloworld/myhelloworld_0.1.bb
1190 DESCRIPTION = "Hello world program"
1191 PR = "r0"
1192
1193 SRC_URI = "file://myhelloworld.c \
1194            file://README.txt"
1195
1196 do_compile() {
1197         ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
1198 }
1199
1200 do_install() {
1201         install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
1202         install -m 0644 ${S}/myhelloworld ${D}${bindir}
1203         install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
1204 }
1205 ^D</screen>Now we are ready to build our package, hopefully it'll all work
1206       since it's such a simple example:<screen>~/oe%&gt; bitbake -b recipes/myhelloworld/myhelloworld_0.1.bb
1207 NOTE: package myhelloworld-0.1: started
1208 NOTE: package myhelloworld-0.1-r0: task do_fetch: started
1209 NOTE: package myhelloworld-0.1-r0: task do_fetch: completed
1210 NOTE: package myhelloworld-0.1-r0: task do_unpack: started
1211 NOTE: Unpacking /home/lenehan/devel/oe/local-recipes/myhelloworld/files/helloworld.c to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/
1212 NOTE: Unpacking /home/lenehan/devel/oe/local-recipes/myhelloworld/files/README.txt to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/
1213 NOTE: package myhelloworld-0.1-r0: task do_unpack: completed
1214 NOTE: package myhelloworld-0.1-r0: task do_patch: started
1215 NOTE: package myhelloworld-0.1-r0: task do_patch: completed
1216 NOTE: package myhelloworld-0.1-r0: task do_configure: started
1217 NOTE: package myhelloworld-0.1-r0: task do_configure: completed
1218 NOTE: package myhelloworld-0.1-r0: task do_compile: started
1219 NOTE: package myhelloworld-0.1-r0: task do_compile: completed
1220 NOTE: package myhelloworld-0.1-r0: task do_install: started
1221 NOTE: package myhelloworld-0.1-r0: task do_install: completed
1222 NOTE: package myhelloworld-0.1-r0: task do_package: started
1223 NOTE: package myhelloworld-0.1-r0: task do_package: completed
1224 NOTE: package myhelloworld-0.1-r0: task do_package_write: started
1225 NOTE: Not creating empty archive for myhelloworld-dbg-0.1-r0
1226 Packaged contents of myhelloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk
1227 Packaged contents of myhelloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk
1228 NOTE: Not creating empty archive for myhelloworld-dev-0.1-r0
1229 NOTE: Not creating empty archive for myhelloworld-locale-0.1-r0
1230 NOTE: package myhelloworld-0.1-r0: task do_package_write: completed
1231 NOTE: package myhelloworld-0.1-r0: task do_populate_staging: started
1232 NOTE: package myhelloworld-0.1-r0: task do_populate_staging: completed
1233 NOTE: package myhelloworld-0.1-r0: task do_build: started
1234 NOTE: package myhelloworld-0.1-r0: task do_build: completed
1235 NOTE: package myhelloworld-0.1: completed
1236 Build statistics:
1237   Attempted builds: 1
1238 ~/oe%&gt;</screen></para>
1239
1240       <para>The package was successfully built, the output consists of two
1241       .ipkg files, which are ready to be installed on the target. One contains
1242       the binary and the other contains the readme file:<screen>~/oe%&gt; ls -l tmp/deploy/ipk/*/myhelloworld*
1243 -rw-r--r--  1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk
1244 -rw-r--r--  1 lenehan lenehan  768 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk
1245 ~/oe%&gt;</screen></para>
1246
1247       <para>It's worthwhile looking at the working directory to see where
1248       various files ended up:<screen>~/oe%&gt; find tmp/work/myhelloworld-0.1-r0
1249 tmp/work/myhelloworld-0.1-r0
1250 tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1
1251 tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/patches
1252 tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/myhelloworld
1253 tmp/work/myhelloworld-0.1-r0/temp
1254 tmp/work/myhelloworld-0.1-r0/temp/run.do_configure.21840
1255 tmp/work/myhelloworld-0.1-r0/temp/log.do_stage.21840
1256 tmp/work/myhelloworld-0.1-r0/temp/log.do_install.21840
1257 tmp/work/myhelloworld-0.1-r0/temp/log.do_compile.21840
1258 tmp/work/myhelloworld-0.1-r0/temp/run.do_stage.21840
1259 tmp/work/myhelloworld-0.1-r0/temp/log.do_configure.21840
1260 tmp/work/myhelloworld-0.1-r0/temp/run.do_install.21840
1261 tmp/work/myhelloworld-0.1-r0/temp/run.do_compile.21840
1262 tmp/work/myhelloworld-0.1-r0/install
1263 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-locale
1264 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dbg
1265 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dev
1266 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc
1267 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr
1268 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share
1269 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc
1270 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld
1271 tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld/README.txt
1272 tmp/work/myhelloworld-0.1-r0/install/myhelloworld
1273 tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr
1274 tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin
1275 tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld
1276 tmp/work/myhelloworld-0.1-r0/image
1277 tmp/work/myhelloworld-0.1-r0/image/usr
1278 tmp/work/myhelloworld-0.1-r0/image/usr/bin
1279 tmp/work/myhelloworld-0.1-r0/image/usr/share
1280 tmp/work/myhelloworld-0.1-r0/image/usr/share/doc
1281 tmp/work/myhelloworld-0.1-r0/image/usr/share/doc/myhelloworld
1282 tmp/work/myhelloworld-0.1-r0/myhelloworld.c
1283 tmp/work/myhelloworld-0.1-r0/README.txt
1284 ~/oe%&gt;</screen>Things to note here are:</para>
1285
1286       <itemizedlist>
1287         <listitem>
1288           <para>The two source files are in <emphasis
1289           role="bold">tmp/work/myhelloworld-0.1-r0</emphasis>, which is the
1290           working directory as specified via the <emphasis
1291           role="bold">${WORKDIR}</emphasis> variable;</para>
1292         </listitem>
1293
1294         <listitem>
1295           <para>There's logs of the various tasks in <emphasis
1296           role="bold">tmp/work/myhelloworld-0.1-r0/temp</emphasis> which you
1297           can look at for more details on what was done in each task;</para>
1298         </listitem>
1299
1300         <listitem>
1301           <para>There's an image directory at <emphasis
1302           role="bold">tmp/work/myhelloworld-0.1-r0/image</emphasis> which
1303           contains just the directories that were to be packaged up. This is
1304           actually the destination directory, as specified via the <emphasis
1305           role="bold">${D}</emphasis> variable. The two files that we
1306           installed were originally in here, but during packaging they were
1307           moved into the install area into a subdirectory specific to the
1308           package that was being created (remember we have a main package and
1309           a -doc package being created.</para>
1310         </listitem>
1311
1312         <listitem>
1313           <para>The program was actually compiled in the <emphasis
1314           role="bold">tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1</emphasis>
1315           directory, this is the source directory as specified via the
1316           <emphasis role="bold">${S}</emphasis> variable.</para>
1317         </listitem>
1318
1319         <listitem>
1320           <para>There's an install directory at <emphasis
1321           role="bold">tmp/work/myhelloworld-0.1-r0/install</emphasis> which
1322           contains the packages that were being generated and the files that
1323           go in the package. So we can see that the myhelloworld-doc package
1324           contains the single file <emphasis
1325           role="bold">/usr/share/doc/myhelloworld/README.txt</emphasis>, the
1326           myhelloworld package contains the single file <emphasis
1327           role="bold">/usr/bin/myhelloworld</emphasis> and the -dev, -dbg and
1328           -local packages are all empty.</para>
1329         </listitem>
1330       </itemizedlist>
1331
1332       <para>At this stage it's good to verify that we really did produce a
1333       binary for the target and not for our host system. We can check that
1334       with the file command:<screen>~/oe%&gt; file tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld
1335 tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld: ELF 32-bit LSB executable, Hitachi SH, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, not stripped
1336 ~/oe%&gt; file /bin/ls
1337 /bin/ls: ELF 64-bit LSB executable, AMD x86-64, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, stripped
1338 ~/oe%&gt;</screen>This shows us that the helloworld program is for an SH
1339       processor (obviously this will change depending on what your target
1340       system is), while checking the <emphasis role="bold">/bin/ls</emphasis>
1341       program on host shows us that the host system is an AMD X86-64 system.
1342       That's exactly what we wanted.</para>
1343     </section>
1344
1345     <section id="recipes_autoconf_example" xreflabel="autoconf example">
1346       <title>An autotools package</title>
1347
1348       <para>Now for an example of a package that uses autotools. These are
1349       programs that you need to run a configure script for, passing various
1350       parameters, and then make. To make these work when cross-compiling you
1351       need to provides a lot of variables to the configure script. But all the
1352       hard work as already been done for you. There's an <xref
1353       linkend="autotools_class" /> which takes care of most of the complexity
1354       of building an autotools based packages.</para>
1355
1356       <para>Let's take a look at the tuxnes recipe which is an example of a
1357       very simple autotools based recipe:<screen>%~oe&gt; cat recipes/tuxnes/tuxnes_0.75.bb
1358 DESCRIPTION = "Tuxnes Nintendo (8bit) Emulator"
1359 HOMEPAGE = "http://prdownloads.sourceforge.net/tuxnes/tuxnes-0.75.tar.gz"
1360 LICENSE = "GPLv2"
1361 SECTION = "x/games"
1362 PRIORITY = "optional"
1363 PR = "r1"
1364
1365 SRC_URI = "http://heanet.dl.sourceforge.net/sourceforge/tuxnes/tuxnes-0.75.tar.gz"
1366
1367 inherit autotools</screen></para>
1368
1369       <para>This is a really simple recipe. There's the standard header that
1370       describes the package. Then the SRC_URI, which in this case is a http
1371       URL that causes the source code to be downloaded from the specified URI.
1372       And finally there's an "<emphasis role="bold">inherit
1373       autotools</emphasis>" command which loads the autotools class. The
1374       autotools class will take care of generating the require configure,
1375       compile and install tasks. So in this case there's nothing else to do -
1376       that's all there is to it.</para>
1377
1378       <para>It would be nice if it was always this simple. Unfortunately
1379       there's usually a lot more involved for various reasons including the
1380       need to:</para>
1381
1382       <itemizedlist>
1383         <listitem>
1384           <para>Pass parameters to configure to enable and disable
1385           features;</para>
1386         </listitem>
1387
1388         <listitem>
1389           <para>Pass parameters to configure to specify where to find
1390           libraries and headers;</para>
1391         </listitem>
1392
1393         <listitem>
1394           <para>Make modifications to prevent searching for headers and
1395           libraries in the normal locations (since they below to the host
1396           system, not the target);</para>
1397         </listitem>
1398
1399         <listitem>
1400           <para>Make modifications to prevent the configure script from tying
1401           to compile and run programs - any programs it compiles will be for
1402           the target and not the host and so cannot be run.</para>
1403         </listitem>
1404
1405         <listitem>
1406           <para>Manually implement staging scripts;</para>
1407         </listitem>
1408
1409         <listitem>
1410           <para>Deal with lots of other more complex issues;</para>
1411         </listitem>
1412       </itemizedlist>
1413
1414       <para>Some of these items are covered in more detail in the advanced
1415       autoconf section.</para>
1416     </section>
1417   </section>
1418
1419   <section id="recipes_depenencies" xreflabel="dependencies">
1420     <title>Dependencies: What's needed to build and/or run the
1421     package?</title>
1422
1423     <para>Dependencies should be familiar to anyone who has used an .rpm and
1424     .deb based desktop distribution. A dependency is something that a package
1425     requires either to run the package (a run-time dependency) or to build the
1426     package (a build-time or compile-time, dependency).</para>
1427
1428     <para>There are two variables provided to allow the specifications of
1429     dependencies:</para>
1430
1431     <variablelist>
1432       <varlistentry>
1433         <term>DEPENDS</term>
1434
1435         <listitem>
1436           <para>Specifies build-time dependencies, via a list of bitbake
1437           recipes to build prior to build the recipe. These are programs
1438           (flex-native) or libraries (libpcre) that are required in order to
1439           build the package.</para>
1440         </listitem>
1441       </varlistentry>
1442
1443       <varlistentry>
1444         <term>RDEPENDS</term>
1445
1446         <listitem>
1447           <para>Specifies run-time dependencies, via a list of packages to
1448           install prior to installing the current package. These are programs
1449           or libraries that are required in order to run the program. Note
1450           that libraries which are dynamically linked to an application will
1451           be automatically detected and added to <emphasis
1452           role="bold">RDEPENDS</emphasis> and therefore do not need to be
1453           explicitly declared. If a library was dynamically loaded then it
1454           would need to be explicitly listed.</para>
1455         </listitem>
1456       </varlistentry>
1457     </variablelist>
1458
1459     <para>If we take openssh for an example, it requires zlib and openssl in
1460     order to both built and run. In the recipe we have:<screen>DEPENDS = "zlib openssl"</screen>This
1461     tells bitbake that it will need to build and stage zlib and openssl prior
1462     to trying to build openssh, since openssh requires both of them. Note that
1463     there is no <emphasis role="bold">RDEPENDS</emphasis> even though openssh
1464     requires both of them to run. The run time dependencies on libz1 (the name
1465     of the package containing the zlib library) and libssl0 (the name of the
1466     package containing the ssl library) are automatically determined and added
1467     via the auto shared libs dependency code.</para>
1468   </section>
1469
1470   <section id="recipes_methods" xreflabel="methods">
1471     <title>Methods: Inbuilt methods to make your life easier</title>
1472
1473     <para>There are several helper functions defined by the base class, which
1474     is included by default for all recipes. Many of these are used a lot in
1475     both recipes and other classes.</para>
1476
1477     <para>The most commonly seen, and most useful functions, include:</para>
1478
1479     <variablelist>
1480       <varlistentry>
1481         <term>oe_runmake</term>
1482
1483         <listitem>
1484           <para>This function is used to run make. However unlike calling make
1485           yourself this will pass the EXTRA_OEMAKE settings to make, will
1486           display a note about the make command and will check for any errors
1487           generated via the call to make.</para>
1488
1489           <para>You should never have any reason to call make directly and
1490           should also use oe_runmake when you need to run make.</para>
1491         </listitem>
1492       </varlistentry>
1493
1494       <varlistentry>
1495         <term>oe_runconf (autotools only)</term>
1496
1497         <listitem>
1498           <para>This function is used to run the configure script of a package
1499           that is using the autotools class. This takes care of passing all of
1500           the correct parameters for cross-compiling and for installing into
1501           the appropriate target directory.</para>
1502
1503           <para>It also passes the value of the <emphasis
1504           role="bold">EXTRA_OECONF</emphasis> variable to the configure
1505           script. For many situations setting <emphasis
1506           role="bold">EXTRA_OECONF</emphasis> is sufficient and you'll have no
1507           need to define your own configure task in which you call oe_runconf
1508           manually.</para>
1509
1510           <para>If you need to write your own <emphasis>configure</emphasis>
1511           task for an autotools package you can use oe_runconf to manually
1512           call the configure process when it is required. The following
1513           example from net-snmp shows oe_runconf being called manually so that
1514           the parameter for specifying the endianess can be computed and
1515           passed in to the configure script:<screen>do_configure() {
1516     # Additional flag based on target endiness (see siteinfo.bbclass)
1517     ENDIANESS="${@base_conditional('SITEINFO_ENDIANESS', 'le', '--with-endianness=little', '--with-endianness=big', d)}"
1518     oenote Determined endianess as: $ENDIANESS
1519     oe_runconf $ENDIANESS
1520 }</screen></para>
1521         </listitem>
1522       </varlistentry>
1523
1524       <varlistentry>
1525         <term>oe_libinstall</term>
1526
1527         <listitem>
1528           <para>This function is used to install <emphasis
1529           role="bold">.so</emphasis>, <emphasis role="bold">.a</emphasis> and
1530           associated libtool <emphasis role="bold">.la</emphasis> libraries.
1531           It will determine the appropriate libraries to install and take care
1532           of any modifications that may be require for <emphasis
1533           role="bold">.la</emphasis> files.</para>
1534
1535           <para>This function supports the following options:</para>
1536
1537           <variablelist>
1538             <varlistentry>
1539               <term>-C &lt;dir&gt;</term>
1540
1541               <listitem>
1542                 <para>Change into the specified directory before attempting to
1543                 install a library. Used when the libraries are in
1544                 subdirectories of the main package.</para>
1545               </listitem>
1546             </varlistentry>
1547
1548             <varlistentry>
1549               <term>-s</term>
1550
1551               <listitem>
1552                 <para>Require the presence of a <emphasis
1553                 role="bold">.so</emphasis> library as one of the libraries
1554                 that is installed.</para>
1555               </listitem>
1556             </varlistentry>
1557
1558             <varlistentry>
1559               <term>-a</term>
1560
1561               <listitem>
1562                 <para>Require the presence of a <emphasis
1563                 role="bold">.a</emphasis> library as one of the libraries that
1564                 is installed.</para>
1565               </listitem>
1566             </varlistentry>
1567           </variablelist>
1568
1569           <para>The following example from gdbm shows the installation of
1570           <emphasis role="bold">.so</emphasis>, <emphasis
1571           role="bold">.a</emphasis> (and associated <emphasis
1572           role="bold">.la</emphasis>) libraries into the staging library
1573           area:<screen>do_stage () {
1574     oe_libinstall -so -a libgdbm ${STAGING_LIBDIR}
1575     install -m 0644 ${S}/gdbm.h ${STAGING_INCDIR}/
1576 }</screen></para>
1577         </listitem>
1578       </varlistentry>
1579
1580       <varlistentry>
1581         <term>oenote</term>
1582
1583         <listitem>
1584           <para>Used to display an informational messages to the user.</para>
1585
1586           <para>The following example from net-snmp uses oenote to tell the
1587           user which endianess it determined was appropriate for the target
1588           device:<screen>do_configure() {
1589     # Additional flag based on target endiness (see siteinfo.bbclass)
1590     ENDIANESS="${@base_conditional('SITEINFO_ENDIANESS', 'le', '--with-endianness=little', '--with-endianness=big', d)}"
1591     oenote Determined endianess as: $ENDIANESS
1592     oe_runconf $ENDIANESS
1593 }</screen></para>
1594         </listitem>
1595       </varlistentry>
1596
1597       <varlistentry>
1598         <term>oewarn</term>
1599
1600         <listitem>
1601           <para>Used to display a warning message to the user, warning of
1602           something that may be problematic or unexpected.</para>
1603         </listitem>
1604       </varlistentry>
1605
1606       <varlistentry>
1607         <term>oedebug</term>
1608
1609         <listitem>
1610           <para>Used to display debugging related information. These messages
1611           will only be visible when bitbake is run with the <emphasis
1612           role="bold">-D</emphasis> flag to enable debug output.</para>
1613         </listitem>
1614       </varlistentry>
1615
1616       <varlistentry>
1617         <term>oefatal</term>
1618
1619         <listitem>
1620           <para>Used to display a fatal error message to the user, and then
1621           abort the bitbake run.</para>
1622
1623           <para>The following example from linux-libc-headers shows the use of
1624           oefatal to tell the user when it cannot find the kernel source code
1625           for the specified target architecture:<screen>do_configure () {
1626     case ${TARGET_ARCH} in
1627         alpha*)   ARCH=alpha ;;
1628         arm*)     ARCH=arm ;;
1629         cris*)    ARCH=cris ;;
1630         hppa*)    ARCH=parisc ;;
1631         i*86*)    ARCH=i386 ;;
1632         ia64*)    ARCH=ia64 ;;
1633         mips*)    ARCH=mips ;;
1634         m68k*)    ARCH=m68k ;;
1635         powerpc*) ARCH=ppc ;;
1636         s390*)    ARCH=s390 ;;
1637         sh*)      ARCH=sh ;;
1638         sparc64*) ARCH=sparc64 ;;
1639         sparc*)   ARCH=sparc ;;
1640         x86_64*)  ARCH=x86_64 ;;
1641     esac
1642     if test !  -e include/asm-$ARCH; then
1643         oefatal unable to create asm symlink in kernel headers
1644     fi
1645 ...</screen></para>
1646         </listitem>
1647       </varlistentry>
1648
1649       <varlistentry>
1650         <term>base_conditional (python)</term>
1651
1652         <listitem>
1653           <para>The base conditional python function is used to set a variable
1654           to one of two values based on the definition of a third variable.
1655           The general usage is:<screen>${@base_conditional('&lt;variable-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen>where:</para>
1656
1657           <variablelist>
1658             <varlistentry>
1659               <term>variable-name</term>
1660
1661               <listitem>
1662                 <para>This is the name of a variable to check.</para>
1663               </listitem>
1664             </varlistentry>
1665
1666             <varlistentry>
1667               <term>value</term>
1668
1669               <listitem>
1670                 <para>This is the value to compare the variable
1671                 against.</para>
1672               </listitem>
1673             </varlistentry>
1674
1675             <varlistentry>
1676               <term>true-result</term>
1677
1678               <listitem>
1679                 <para>If the variable equals the value then this is what is
1680                 returned by the function.</para>
1681               </listitem>
1682             </varlistentry>
1683
1684             <varlistentry>
1685               <term>false-result</term>
1686
1687               <listitem>
1688                 <para>If the variable does not equal the value then this is
1689                 what is returned by the function.</para>
1690               </listitem>
1691             </varlistentry>
1692           </variablelist>
1693
1694           <note>
1695             <para>The ${@...} syntax is used to call python functions from
1696             within a recipe or class. This is described in more detail in the
1697             <xref linkend="recipes_advanced_python" /> section.</para>
1698           </note>
1699
1700           <para>The following example from the openssl recipe shows the
1701           addition of either <emphasis role="bold">-DL_ENDING</emphasis> or
1702           <emphasis role="bold">-DB_ENDIAN</emphasis> depending on the value
1703           of <emphasis role="bold">SITEINFO_ENDIANESS</emphasis> which is set
1704           to le for little endian targets and to be for big endian
1705           targets:<screen>do_compile () {
1706     ...
1707     # Additional flag based on target endiness (see siteinfo.bbclass)
1708     CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"
1709     ...</screen></para>
1710         </listitem>
1711       </varlistentry>
1712     </variablelist>
1713   </section>
1714
1715   <section id="recipes_packages" xreflabel="packages">
1716     <title>Packaging: Defining packages and their contents</title>
1717
1718     <para>A bitbake recipe is a set of instructions from creating one, or
1719     more, packages for installation on the target device. Typically these are
1720     .ipkg or .deb packages (although bitbake itself isn't associated with any
1721     particular packaging format).</para>
1722
1723     <para>By default several packages are produced automatically without any
1724     special action required on the part of the recipe author. The following
1725     example of the packaging output from the helloworld example above shows
1726     this packaging in action:<screen>[NOTE: package helloworld-0.1-r0: task do_package_write: started
1727 NOTE: Not creating empty archive for helloworld-dbg-0.1-r0
1728 Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk
1729 Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk
1730 NOTE: Not creating empty archive for helloworld-dev-0.1-r0
1731 NOTE: Not creating empty archive for helloworld-locale-0.1-r0
1732 NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We
1733     can see from above that the packaging did the following:</para>
1734
1735     <itemizedlist>
1736       <listitem>
1737         <para>Created a main package, <emphasis
1738         role="bold">helloworld_0.1-r0_sh4.ipk</emphasis>. This package
1739         contains the helloworld binary <emphasis
1740         role="bold">/usr/bin/helloworld</emphasis>.</para>
1741       </listitem>
1742
1743       <listitem>
1744         <para>Created a documentation package, <emphasis
1745         role="bold">helloworld-doc_0.1-r0_sh4.ipk</emphasis>. This package
1746         contains the readme file <emphasis
1747         role="bold">/usr/share/doc/helloworld/README.txt</emphasis>.</para>
1748       </listitem>
1749
1750       <listitem>
1751         <para>Considered creating a debug package, <emphasis
1752         role="bold">helloworld-dbg-0.1-r0_sh4.ipk</emphasis>, a development
1753         package <emphasis role="bold">helloworld-dev-0.1-r0_sh4.ipk</emphasis>
1754         and a locale package <emphasis
1755         role="bold">helloworld-locale-0.1-r0_sh4.ipk</emphasis>. It didn't
1756         create the package due to the fact that it couldn't find any files
1757         that would actually go in the package.</para>
1758       </listitem>
1759     </itemizedlist>
1760
1761     <para>There are several things happening here which are important to
1762     understand:</para>
1763
1764     <orderedlist>
1765       <listitem>
1766         <para>There is a default set of packages that are considered for
1767         creation. This set of packages is controlled via the <emphasis
1768         role="bold">PACKAGES</emphasis> variable.</para>
1769       </listitem>
1770
1771       <listitem>
1772         <para>For each package there is a default set of files and/or
1773         directories that are considered to belong to those packages. The
1774         documentation packages for example include anything found <emphasis
1775         role="bold">/usr/share/doc</emphasis>. The set of files and
1776         directories is controlled via the <emphasis
1777         role="bold">FILES_&lt;package-name&gt;</emphasis> variables.</para>
1778       </listitem>
1779
1780       <listitem>
1781         <para>By default packages that contain no files are not created and no
1782         error is generated. The decision to create empty packages or not is
1783         controlled via the <emphasis role="bold">ALLOW_EMPTY</emphasis>
1784         variable.</para>
1785       </listitem>
1786     </orderedlist>
1787
1788     <section>
1789       <title>Philosophy</title>
1790
1791       <para>Separate packaging, where possible, is of high importance in
1792       OpenEmbedded. Many of the target devices have limited storage space and
1793       RAM and giving distributions and users the option of not installing a
1794       part of the package they don't need allows them to reduce the amount of
1795       storage space required.</para>
1796
1797       <para>As an example almost no distributions will include documentation
1798       or development libraries since they are not required for the day to day
1799       operation of the device. In particular if your package provides multiple
1800       binaries, and it would be common to only use one or the other, then you
1801       should consider separating them into separate packages.</para>
1802
1803       <para>By default several groups of files are automatically separate out,
1804       including:</para>
1805
1806       <variablelist>
1807         <varlistentry>
1808           <term>dev</term>
1809
1810           <listitem>
1811             <para>Any files required for development. This includes header
1812             files, static libraries, the shared library symlinks required only
1813             for linking etc. These would only ever need to be installed by
1814             someone attempt to compile applications on the target device.
1815             While this does happen it is very uncommon and so these files are
1816             automatically moved into a separate package</para>
1817           </listitem>
1818         </varlistentry>
1819
1820         <varlistentry>
1821           <term>doc</term>
1822
1823           <listitem>
1824             <para>Any documentation related files, including man pages. These
1825             are files which are of informational purposes only. For many
1826             embedded devices there is no way for the user to see any of the
1827             documentation anyway, and documentation can consume a lot of
1828             space. By separating these out they don't take any space by
1829             default but distributions and/or users may choose to install them
1830             if they need some documentation on a specific package.</para>
1831           </listitem>
1832         </varlistentry>
1833
1834         <varlistentry>
1835           <term>locale</term>
1836
1837           <listitem>
1838             <para>Locale information provides translation information for
1839             packages. Many users do not require these translations, and many
1840             devices will only want to provide them for user visible
1841             components, such as UI related items, and not for system binaries.
1842             By separating these out it is left up to the distribution or users
1843             to decide if they are required or not.</para>
1844           </listitem>
1845         </varlistentry>
1846       </variablelist>
1847     </section>
1848
1849     <section>
1850       <title>Default packages and files</title>
1851
1852       <para>The defaults package settings are defined in <emphasis
1853       role="bold">conf/bitbake.conf</emphasis> and are suitable for a lot of
1854       recipes without any changes. The following list shows the default values
1855       for the packaging related variables:</para>
1856
1857       <para><variablelist>
1858           <varlistentry>
1859             <term>PACKAGES</term>
1860
1861             <listitem>
1862               <para>This variable lists the names of each of the packages that
1863               are to be generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen>Note
1864               that the order of packages is important: the packages are
1865               processed in the listed order. So if two packages specify the
1866               same file then the first package listed in packages will get the
1867               file. This is important when packages use wildcards to specify
1868               their contents.</para>
1869
1870               <para>For example if the main package, <emphasis
1871               role="bold">${PN}</emphasis>, contains <emphasis
1872               role="bold">/usr/bin/*</emphasis> (i.e. all files in <emphasis
1873               role="bold">/usr/bin</emphasis>), but you want <emphasis
1874               role="bold">/usr/bin/tprogram</emphasis> in a separate package,
1875               <emphasis role="bold">${PN}-tpackage</emphasis>, you would need
1876               to either ensure that <emphasis
1877               role="bold">${PN}-tpackage</emphasis> is listed prior to
1878               <emphasis role="bold">${PN}</emphasis> in <emphasis
1879               role="bold">PACKAGES</emphasis> or that <emphasis
1880               role="bold">FILES_${PN}</emphasis> was modified to not contain
1881               the wildcard that matches <emphasis
1882               role="bold">/usr/bin/tprogram</emphasis>.</para>
1883
1884               <para>Note that the -dbg package contains the debugging
1885               information that has been extracted from binaries and libraries
1886               prior to them being stripped. This package should always be the
1887               first package in the package list to ensure that the debugging
1888               information is correctly extracted and moved to the package
1889               prior to any other packaging decisions being made.</para>
1890             </listitem>
1891           </varlistentry>
1892
1893           <varlistentry>
1894             <term>FILES_${PN}</term>
1895
1896             <listitem>
1897               <para>The base package, this includes everything needed to
1898               actually run the application on the target system.<screen>FILES_${PN} = "\
1899     ${bindir}/* \
1900     ${sbindir}/* \
1901     ${libexecdir}/* \
1902     ${libdir}/lib*.so.* \
1903     ${sysconfdir} \
1904     ${sharedstatedir} \
1905     ${localstatedir} \
1906     /bin/* \
1907     /sbin/* \
1908     /lib/*.so* \
1909     ${datadir}/${PN} \
1910     ${libdir}/${PN}/* \
1911     ${datadir}/pixmaps \
1912     ${datadir}/applications \
1913     ${datadir}/idl \
1914     ${datadir}/omf \
1915     ${datadir}/sounds \
1916     ${libdir}/bonobo/servers"</screen></para>
1917             </listitem>
1918           </varlistentry>
1919
1920           <varlistentry>
1921             <term>FILES_${PN}-dbg</term>
1922
1923             <listitem>
1924               <para>The debugging information extracted from non-stripped
1925               versions of libraries and executable's. OpenEmbedded
1926               automatically extracts the debugging information into files in
1927               .debug directories and then strips the original files.<screen>FILES_${PN}-dbg = "\
1928     ${bindir}/.debug \
1929     ${sbindir}/.debug \
1930     ${libexecdir}/.debug \
1931     ${libdir}/.debug \
1932     /bin/.debug \
1933     /sbin/.debug \
1934     /lib/.debug \
1935     ${libdir}/${PN}/.debug"</screen></para>
1936             </listitem>
1937           </varlistentry>
1938
1939           <varlistentry>
1940             <term>FILES_${PN}-doc</term>
1941
1942             <listitem>
1943               <para>Documentation related files. All documentation is
1944               separated into it's own package so that it does not need to be
1945               installed unless explicitly required.<screen>FILES_${PN}-doc = "\
1946     ${docdir} \
1947     ${mandir} \
1948     ${infodir} \
1949     ${datadir}/gtk-doc \
1950     ${datadir}/gnome/help"</screen></para>
1951             </listitem>
1952           </varlistentry>
1953
1954           <varlistentry>
1955             <term>FILES_${PN}-dev</term>
1956
1957             <listitem>
1958               <para>Development related files. Any headers, libraries and
1959               support files needed for development work on the target.<screen>FILES_${PN}-dev = "\
1960     ${includedir} \
1961     ${libdir}/lib*.so \
1962     ${libdir}/*.la \
1963     ${libdir}/*.a \
1964     ${libdir}/*.o \
1965     ${libdir}/pkgconfig \
1966     /lib/*.a \
1967     /lib/*.o \
1968     ${datadir}/aclocal"</screen></para>
1969             </listitem>
1970           </varlistentry>
1971
1972           <varlistentry>
1973             <term>FILES_${PN}-locale</term>
1974
1975             <listitem>
1976               <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para>
1977             </listitem>
1978           </varlistentry>
1979         </variablelist></para>
1980     </section>
1981
1982     <section>
1983       <title>Wildcards</title>
1984
1985       <para>Wildcards used in the <emphasis role="bold">FILES</emphasis>
1986       variables are processed via the python function <emphasis
1987       role="bold">fnmatch</emphasis>. The following items are of note about
1988       this function:</para>
1989
1990       <itemizedlist>
1991         <listitem>
1992           <para><emphasis role="bold">/&lt;dir&gt;/*</emphasis>: This will
1993           match all files and directories in the <emphasis
1994           role="bold">dir</emphasis> - it will not match other
1995           directories.</para>
1996         </listitem>
1997
1998         <listitem>
1999           <para><emphasis role="bold">/&lt;dir&gt;/a*</emphasis>: This will
2000           only match files, and not directories.</para>
2001         </listitem>
2002
2003         <listitem>
2004           <para><emphasis role="bold">/dir</emphasis>: will include the
2005           directory <emphasis role="bold">dir</emphasis> in the package, which
2006           in turn will include all files in the directory and all
2007           subdirectories.</para>
2008         </listitem>
2009       </itemizedlist>
2010
2011       <para>Note that the order of packages effects the files that will be
2012       matched via wildcards. Consider the case where we have three binaries in
2013       the <command>/usr/bin</command> directory and we want the test program
2014       in a separate package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So
2015       we define a new package and instruct bitbake to include /usr/bin/test in
2016       it.</para>
2017
2018       <screen>FILES-${PN}-test = "${bindir}/test"
2019 PACKAGES += "FILES-${PN}-test"</screen>
2020
2021       <para>When the package is regenerated no <emphasis
2022       role="bold">${PN}-test</emphasis> package will be created. The reason
2023       for this is that the <emphasis role="bold">PACKAGES</emphasis> line now
2024       looks like this:<screen>{PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale ${PN}-test</screen>Note
2025       how <emphasis role="bold">${PN}</emphasis> is listed prior to <emphasis
2026       role="bold">${PN}-test</emphasis>, and if we look at the definition of
2027       <emphasis role="bold">FILES-${PN}</emphasis> it contains the <emphasis
2028       role="bold">${bindir}/*</emphasis> wildcard. Since <emphasis
2029       role="bold">${PN}</emphasis> is first it'll match that wildcard are be
2030       moved into the <emphasis role="bold">${PN}</emphasis> package prior to
2031       processing of the <emphasis role="bold">${PN}-test</emphasis>
2032       package.</para>
2033
2034       <para>To achieve what we are trying to accomplish we have two
2035       options:</para>
2036
2037       <orderedlist>
2038         <listitem>
2039           <para>Modify the definition of <emphasis
2040           role="bold">${PN}</emphasis> so that the wildcard does not match the
2041           test program.</para>
2042
2043           <para>We could do this for example:<screen>FILES-${PN} = "${bindir}/p*"</screen>So
2044           now this will only match things in the bindir that start with p, and
2045           therefore not match our test program. Note that <emphasis
2046           role="bold">FILES-${PN}</emphasis> contains a lot more entries and
2047           we'd need to add any of the other that refer to files that are to be
2048           included in the package. In this case we have no other files, so
2049           it's safe to do this simple declaration.</para>
2050         </listitem>
2051
2052         <listitem>
2053           <para>Modify the order of packages so that the <emphasis
2054           role="bold">${PN}-test</emphasis> package is listed first.</para>
2055
2056           <para>The most obvious way to do this would be to prepend our new
2057           package name to the packages list instead of appending it:<screen>PACKAGES =+ "FILES-${PN}-test"</screen>In
2058           some cases this would work fine, however there is a problem with
2059           this for packages that include binaries. The package will now be
2060           listed before the -dbg package and often this will result in the
2061           .debug directories being included in the package. In this case we
2062           are explicitly listing only a single file (and not using wildcards)
2063           and therefore it would be ok.</para>
2064
2065           <para>In general it's more common to have to redefine the entire
2066           package list to include your new package plus any of the default
2067           packages that you require:<screen>PACKAGES = "${PN}-dbg ${PN}-test ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para>
2068         </listitem>
2069       </orderedlist>
2070     </section>
2071
2072     <section>
2073       <title>Checking the packages</title>
2074
2075       <para>During recipe development it's useful to be able to check on
2076       exactly what files went into each package, which files were not packaged
2077       and which packages contain no files.</para>
2078
2079       <para>One of easiest method is to run find on the install directory. In
2080       the install directory there is one subdirectory created per package, and
2081       the files are moved into the install directory as they are matched to a
2082       specific package. The following shows the packages and files for the
2083       helloworld example:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/install
2084 tmp/work/helloworld-0.1-r0/install
2085 tmp/work/helloworld-0.1-r0/install/helloworld-locale
2086 tmp/work/helloworld-0.1-r0/install/helloworld-dbg
2087 tmp/work/helloworld-0.1-r0/install/helloworld-dev
2088 tmp/work/helloworld-0.1-r0/install/helloworld-doc
2089 tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr
2090 tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share
2091 tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc
2092 tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld
2093 tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld/README.txt
2094 tmp/work/helloworld-0.1-r0/install/helloworld
2095 tmp/work/helloworld-0.1-r0/install/helloworld/usr
2096 tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin
2097 tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld
2098 ~/oe%&gt;</screen>The above shows that the -local, -dbg and -dev packages are
2099       all empty, and the -doc and base package contain a single file each.
2100       Uses "<emphasis role="bold">-type f</emphasis>" option to find to show
2101       just files will make this clearer as well.</para>
2102
2103       <para>In addition to the install directory the image directory (which
2104       corresponds to the destination directory, <emphasis
2105       role="bold">D</emphasis>) will contain any files that were not
2106       packaged:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image
2107 tmp/work/helloworld-0.1-r0/image
2108 tmp/work/helloworld-0.1-r0/image/usr
2109 tmp/work/helloworld-0.1-r0/image/usr/bin
2110 tmp/work/helloworld-0.1-r0/image/usr/share
2111 tmp/work/helloworld-0.1-r0/image/usr/share/doc
2112 tmp/work/helloworld-0.1-r0/image/usr/share/doc/helloworld
2113 ~/oe%&gt;</screen>In this case all files were packaged and so there are no
2114       left over files. Using find with "<emphasis role="bold">-type
2115       f</emphasis>" makes this much clearer:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image -type f
2116 ~/oe%&gt;</screen></para>
2117
2118       <para>Messages reading missing files are also display by bitbake during
2119       the package task:<screen>NOTE: package helloworld-0.1-r0: task do_package: started
2120 NOTE: the following files were installed but not shipped in any package:
2121 NOTE:   /usualdir/README.txt
2122 NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in
2123       very unusual circumstances there should be no unpackaged files left
2124       behind by a recipe.</para>
2125     </section>
2126
2127     <section>
2128       <title>Excluding files</title>
2129
2130       <para>There's no actual support for explicitly excluding files from
2131       packaging. You could just leave them out of any package, but then you'll
2132       get warnings (or errors if requesting full package checking) during
2133       packaging which is not desirable. It also doesn't let other people know
2134       that you've deliberately avoided packaging the file or files.</para>
2135
2136       <para>In order to exclude a file totally you should avoid installing it
2137       in the first place during the install task.</para>
2138
2139       <para>In some cases it may be easier to let the package install the file
2140       and then explicitly remove the file and the end of the install task. The
2141       following example from the samba recipe shows the removal of several
2142       files that get installed via the default install task generated by the
2143       <xref linkend="autotools_class" />. By using
2144       <emphasis>do_install_append</emphasis> these commands and run after the
2145       autotools generated install task:</para>
2146
2147       <screen>do_install_append() {
2148     ...
2149     rm -f ${D}${bindir}/*.old
2150     rm -f ${D}${sbindir}/*.old
2151     ...
2152 }</screen>
2153     </section>
2154
2155     <section>
2156       <title>Debian naming</title>
2157
2158       <para>A special <emphasis>debian library name</emphasis> policy can be
2159       applied for packages that contain a single shared library. When enabled
2160       packages will be renamed to match the debian policy for such
2161       packages.</para>
2162
2163       <para>Debian naming is enabled by including the debian class via either
2164       <command>local.conf</command> or your distributions configuration
2165       file:<screen>INHERIT += "debian"</screen></para>
2166
2167       <para>The policy works by looking at the shared library name and version
2168       and will automatically rename the package to
2169       <emphasis>&lt;libname&gt;&lt;lib-major-version&gt;</emphasis>. For
2170       example if the package name (PN) is <command>foo</command> and the
2171       package ships a file named <command>libfoo.so.1.2.3</command> then the
2172       package will be renamed to <command>libfoo1</command> to follow the
2173       debian policy.</para>
2174
2175       <para>If we look at the <emphasis>lzo_1.08.bb</emphasis> recipe,
2176       currently at release 14, it generates a package containing a single
2177       shared library :<screen>~oe/build/titan-glibc-25%&gt; find tmp/work/lzo-1.08-r14/install/
2178 tmp/work/lzo-1.08-r14/install/lzo
2179 tmp/work/lzo-1.08-r14/install/lzo/usr
2180 tmp/work/lzo-1.08-r14/install/lzo/usr/lib
2181 tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1
2182 tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen>Without
2183       debian naming this package would have been called
2184       <command>lzo_1.08-r14_sh4.ipk</command> (and the corresponding dev and
2185       dbg packages would have been called
2186       <command>lzo-dbg_1.08-r14_sh4.ipk</command> and
2187       <command>lzo-dev_1.08-r14_sh4.ipk</command>). However with debian naming
2188       enabled the package is renamed based on the name of the shared library,
2189       which is <command>liblzo.so.1.0.0</command> in this case. So the name
2190       <command>lzo</command> is replaced with
2191       <command>liblzo1</command>:<screen>~oe/build/titan-glibc-25%&gt; find tmp/deploy/ipk/ -name '*lzo*'  
2192 tmp/deploy/ipk/sh4/liblzo1_1.08-r14_sh4.ipk
2193 tmp/deploy/ipk/sh4/liblzo-dev_1.08-r14_sh4.ipk
2194 tmp/deploy/ipk/sh4/liblzo-dbg_1.08-r14_sh4.ipk</screen></para>
2195
2196       <para>Some variables are available which effect the operation of the
2197       debian renaming class:</para>
2198
2199       <variablelist>
2200         <varlistentry>
2201           <term>LEAD_SONAME</term>
2202
2203           <listitem>
2204             <para>If the package actually contains multiple shared libraries
2205             then one will be selected automatically and a warning will be
2206             generated. This variable is a regular expression which is used to
2207             select which shared library from those available is to be used for
2208             debian renaming.</para>
2209           </listitem>
2210         </varlistentry>
2211
2212         <varlistentry>
2213           <term>DEBIAN_NOAUTONAME_&lt;pkgname&gt;</term>
2214
2215           <listitem>
2216             <para>If this variable is set to 1 for a package then debian
2217             renaming will not be applied for the package.</para>
2218           </listitem>
2219         </varlistentry>
2220
2221         <varlistentry>
2222           <term>AUTO_LIBNAME_PKGS</term>
2223
2224           <listitem>
2225             <para>If set this variable specifies the prefix of packages which
2226             will be subject to debian renaming. This can be used to prevent
2227             all of the packages being renamed via the renaming policy.</para>
2228           </listitem>
2229         </varlistentry>
2230       </variablelist>
2231     </section>
2232
2233     <section>
2234       <title>Empty packages</title>
2235
2236       <para>By default empty packages are ignored. Occasionally you may wish
2237       to actually created empty packages, typically done when you want a
2238       virtual package which will install other packages via dependencies
2239       without actually installing anything itself. The <emphasis
2240       role="bold">ALLOW_EMPTY</emphasis> variable is used to control the
2241       creation of empty packages:</para>
2242
2243       <variablelist>
2244         <varlistentry>
2245           <term>ALLOW_EMPTY</term>
2246
2247           <listitem>
2248             <para>Controls if empty packages will be created or not. By
2249             default this is <emphasis role="bold">"0"</emphasis> and empty
2250             packages are not created. Setting this to <emphasis
2251             role="bold">"1"</emphasis> will permit the creation of empty
2252             packages (packages containing no files).</para>
2253           </listitem>
2254         </varlistentry>
2255       </variablelist>
2256     </section>
2257   </section>
2258
2259   <section id="recipes_tasks" xreflabel="tasks">
2260     <title>Tasks: Playing with tasks</title>
2261
2262     <para>Bitbake steps through a series of tasks when building a recipe.
2263     Sometimes you need to explicitly define what a class does, such as
2264     providing a <emphasis role="bold">do_install</emphasis> function to
2265     implement the <emphasis>install</emphasis> task in a recipe and sometimes
2266     they are provided for you by common classes, such as the autotools class
2267     providing the default implementations of <emphasis>configure</emphasis>,
2268     <emphasis>compile</emphasis> and <emphasis>install</emphasis>
2269     tasks.</para>
2270
2271     <para>There are several methods available to modify the tasks that are
2272     being run:</para>
2273
2274     <variablelist>
2275       <varlistentry>
2276         <term>Overriding the default task implementation</term>
2277
2278         <listitem>
2279           <para>By defining your own implementation of task you'll override
2280           any default or class provided implementations.</para>
2281
2282           <para>For example, you can define you own implementation of the
2283           compile task to override any default implementation:<screen>do_compile() {
2284       oe_runmake DESTDIR=${D}
2285 }</screen></para>
2286
2287           <para>If you with to totally prevent the task from running you need
2288           to define your own empty implementation. This is typically done via
2289           the definition of the task using a single colon:<screen>do_configure() {
2290     :
2291 }</screen></para>
2292         </listitem>
2293       </varlistentry>
2294
2295       <varlistentry>
2296         <term>Appending or prepending to the task</term>
2297
2298         <listitem>
2299           <para>Sometime you want the default implementation, but you require
2300           addition functionality. This can done by appending or pre-pending
2301           additional functionality onto the task.</para>
2302
2303           <para>The following example from units shows an example of
2304           installing an addition file which for some reason was not installed
2305           via the autotools normal <emphasis>install</emphasis> task:<screen>do_install_append() {
2306        install -d ${D}${datadir}
2307        install -m 0655 units.dat ${D}${datadir}
2308 }</screen></para>
2309
2310           <para>The following example from the cherokee recipe show an example
2311           of adding functionality prior to the default
2312           <emphasis>install</emphasis> task. In this case it compiles a
2313           program that is used during installation natively so that it will
2314           work on the host. Without this the autotools default
2315           <emphasis>install</emphasis> task would fail since it'd try to run
2316           the program on the host which was compiled for the target:<screen>do_install_prepend () {
2317         # It only needs this app during the install, so compile it natively
2318         $BUILD_CC -DHAVE_SYS_STAT_H -o cherokee_replace cherokee_replace.c
2319 }</screen></para>
2320         </listitem>
2321       </varlistentry>
2322
2323       <varlistentry>
2324         <term>Defining a new task</term>
2325
2326         <listitem>
2327           <para>Another option is define a totally new task, and then register
2328           that with bitbake so that it runs in between two of the existing
2329           tasks.</para>
2330
2331           <para>The following example shows a situation in which a cvs tree
2332           needs to be copied over the top of an extracted tar.gz archive, and
2333           this needs to be done before any local patches are applied. So a new
2334           task is defined to perform this action, and then that task is
2335           registered to run between the existing <emphasis>unpack</emphasis>
2336           and <emphasis>patch</emphasis> tasks:<screen>do_unpack_extra(){
2337     cp -pPR ${WORKDIR}/linux/* ${S}
2338 }
2339 addtask unpack_extra after do_unpack before do_patch</screen></para>
2340
2341           <note>
2342             <para>The task to add does not have the do_ prepended to it,
2343             however the tasks to insert it after and before do have the _do
2344             prepended. No errors will be generated if this is wrong, the
2345             additional task simple won't be executed.</para>
2346           </note>
2347         </listitem>
2348       </varlistentry>
2349
2350       <varlistentry>
2351         <term>Using overrides</term>
2352
2353         <listitem>
2354           <para>Overrides (described fully elsewhere) allow for various
2355           functionality to be performed conditionally based on the target
2356           machine, distribution, architecture etc.</para>
2357
2358           <para>While not commonly used it is possible to use overrides when
2359           defining tasks. The following example from udev shows an additional
2360           file being installed for the specified machine only by performing an
2361           append to the <emphasis>install</emphasis> task for the h2200
2362           machine only:<screen>do_install_append_h2200() {
2363     install -m 0644 ${WORKDIR}/50-hostap_cs.rules         ${D}${sysconfdir}/udev/rules.d/50-hostap_cs.rules
2364 }</screen></para>
2365         </listitem>
2366       </varlistentry>
2367     </variablelist>
2368   </section>
2369
2370   <section id="recipes_classes" xreflabel="classes">
2371     <title>Classes: The separation of common functionality</title>
2372
2373     <para>Often a certain pattern is followed in more than one recipe, or
2374     maybe some complex python based functionality is required to achieve the
2375     desired end result. This is achieved through the use of classes, which can
2376     be found in the classes subdirectory at the top-level of on OE
2377     checkout.</para>
2378
2379     <para>Being aware of the available classes and understanding their
2380     functionality is important because classes:</para>
2381
2382     <itemizedlist>
2383       <listitem>
2384         <para>Save developers time being performing actions that they would
2385         otherwise need to perform themselves;</para>
2386       </listitem>
2387
2388       <listitem>
2389         <para>Perform a lot of actions in the background making a lot of
2390         recipes difficult to understand unless you are aware of classes and
2391         how they work;</para>
2392       </listitem>
2393
2394       <listitem>
2395         <para>A lot of detail on how things work can be learnt for looking at
2396         how classes are implement.</para>
2397       </listitem>
2398     </itemizedlist>
2399
2400     <para>A class is used via the inherit method. The following is an example
2401     for the <emphasis>curl</emphasis> recipe showing that it uses three
2402     classes:<screen>inherit autotools pkgconfig binconfig</screen>In this case
2403     it is utilising the services of three separate classes:</para>
2404
2405     <variablelist>
2406       <varlistentry>
2407         <term>autotools</term>
2408
2409         <listitem>
2410           <para>The <xref linkend="autotools_class" /> is used by programs
2411           that use the GNU configuration tools and takes care of the
2412           configuration and compilation of the software;</para>
2413         </listitem>
2414       </varlistentry>
2415
2416       <varlistentry>
2417         <term>pkgconfig</term>
2418
2419         <listitem>
2420           <para>The <xref linkend="pkgconfig_class" /> is used to stage the
2421           <emphasis>.pc</emphasis> files which are used by the <emphasis
2422           role="bold">pkg-config</emphasis> program to provide information
2423           about the package to other software that wants to link to this
2424           software;</para>
2425         </listitem>
2426       </varlistentry>
2427
2428       <varlistentry>
2429         <term>binconfig</term>
2430
2431         <listitem>
2432           <para>The <xref linkend="binconfig_class" /> is used to stage the
2433           <emphasis>&lt;name&gt;-config</emphasis> files which are used to
2434           provide information about the package to other software that wants
2435           to link to this software;</para>
2436         </listitem>
2437       </varlistentry>
2438     </variablelist>
2439
2440     <para>Each class is implemented via the file in the <emphasis
2441     role="bold">classes</emphasis> subdirectory named <emphasis
2442     role="bold">&lt;classname&gt;.bbclass</emphasis> and these can be examined
2443     for further details on a particular class, although sometimes it's not
2444     easy to understand everything that's happening. Many of the classes are
2445     covered in detail in various sections in this user manual.</para>
2446   </section>
2447
2448   <section id="recipes_staging" xreflabel="staging">
2449     <title>Staging: Making includes and libraries available for
2450     building</title>
2451
2452     <para>Staging is the process of making files, such as include files and
2453     libraries, available for use by other recipes. This is different to
2454     installing because installing is about making things available for
2455     packaging and then eventually for use on the target device. Staging on the
2456     other hand is about making things available on the host system for use by
2457     building later applications.</para>
2458
2459     <para>Taking bzip2 as an example you can see that it stages a header file
2460     and it's library files:<screen>do_stage () {
2461     install -m 0644 bzlib.h ${STAGING_INCDIR}/
2462     oe_libinstall -a -so libbz2 ${STAGING_LIBDIR}
2463 }</screen></para>
2464
2465     <para>The <emphasis>oe_libinstall</emphasis> method used in the bzip2
2466     recipe is described in the <xref linkend="recipes_methods" /> section, and
2467     it takes care of installing libraries (into the staging area in this
2468     case). The staging variables are automatically defined to the correct
2469     staging location, in this case the main staging variables are used:</para>
2470
2471     <variablelist>
2472       <varlistentry>
2473         <term>STAGING_INCDIR</term>
2474
2475         <listitem>
2476           <para>The directory into which staged headers files should be
2477           installed. This is the equivalent of the standard <emphasis
2478           role="bold">/usr/include</emphasis> directory.</para>
2479         </listitem>
2480       </varlistentry>
2481
2482       <varlistentry>
2483         <term>STAGING_LIBDIR</term>
2484
2485         <listitem>
2486           <para>The directory into which staged library files should be
2487           installed. This is the equivalent of the standard <emphasis
2488           role="bold">/usr/lib</emphasis> directory.</para>
2489         </listitem>
2490       </varlistentry>
2491     </variablelist>
2492
2493     <para>Additional staging related variables are covered in the <xref
2494     linkend="directories_staging" /> section in <xref
2495     linkend="chapter_reference" />.</para>
2496
2497     <para>Looking in the staging area under tmp you can see the result of the
2498     bzip2 recipes staging task:<screen>%&gt; find tmp/staging -name '*bzlib*'
2499 tmp/staging/sh4-linux/include/bzlib.h
2500 %&gt; find tmp/staging -name '*libbz*'
2501 tmp/staging/sh4-linux/lib/libbz2.so
2502 tmp/staging/sh4-linux/lib/libbz2.so.1.0
2503 tmp/staging/sh4-linux/lib/libbz2.so.1
2504 tmp/staging/sh4-linux/lib/libbz2.so.1.0.2
2505 tmp/staging/sh4-linux/lib/libbz2.a</screen></para>
2506
2507     <para>As well as being used during the stage task the staging related
2508     variables are used when building other packages. Looking at the gnupg
2509     recipe we see two bzip2 related items:<screen>DEPENDS = "zlib <emphasis
2510           role="bold">bzip2</emphasis>"
2511 ...
2512 EXTRA_OECONF = "--disable-ldap \
2513         --with-zlib=${STAGING_LIBDIR}/.. \
2514         <emphasis role="bold">--with-bzip2=${STAGING_LIBDIR}/..</emphasis> \
2515         --disable-selinux-support"
2516 </screen></para>
2517
2518     <para>Bzip2 is referred to in two places in the recipe:</para>
2519
2520     <variablelist>
2521       <varlistentry>
2522         <term>DEPENDS</term>
2523
2524         <listitem>
2525           <para>Remember that <emphasis role="bold">DEPENDS</emphasis> defines
2526           the list of build time dependencies. In this case the staged headers
2527           and libraries from bzip2 are required to build gnupg, and therefore
2528           we need to make sure the bzip2 recipe has run and staging the
2529           headers and libraries. By adding the <emphasis
2530           role="bold">DEPENDS</emphasis> on bzip2 this ensures that this
2531           happens.</para>
2532         </listitem>
2533       </varlistentry>
2534
2535       <varlistentry>
2536         <term><emphasis role="bold">EXTRA_OECONF</emphasis></term>
2537
2538         <listitem>
2539           <para>This variable is used by the <xref
2540           linkend="autotools_class" /> to provide options to the configure
2541           script of the package. In the gnupg case it needs to be told where
2542           the bzip2 headers and libraries files are, and this is done via the
2543           <emphasis>--with-bzip2</emphasis> option. In this case it needs to
2544           the directory which include the lib and include subdirectories.
2545           Since OE doesn't define a variable for one level above the include
2546           and lib directories <emphasis role="bold">..</emphasis> is used to
2547           indicate one directory up. Without this gnupg would search the host
2548           system headers and libraries instead of those we have provided in
2549           the staging area for the target.</para>
2550         </listitem>
2551       </varlistentry>
2552     </variablelist>
2553
2554     <para>Remember that staging is used to make things, such as headers and
2555     libraries, available to used by other recipes later on. While header and
2556     libraries are the most common item requiring staging other items such as
2557     the pkgconfig files need to be staged as well, while for native packages
2558     the binaries also need to be staged.</para>
2559   </section>
2560
2561   <section id="recipes_autoconf" xreflabel="about autoconf">
2562     <title>Autoconf: All about autotools</title>
2563
2564     <para>This section is to be completed:</para>
2565
2566     <itemizedlist>
2567       <listitem>
2568         <para>About building autoconf packages</para>
2569       </listitem>
2570
2571       <listitem>
2572         <para>EXTRA_OECONF</para>
2573       </listitem>
2574
2575       <listitem>
2576         <para>Problems with /usr/include, /usr/lib</para>
2577       </listitem>
2578
2579       <listitem>
2580         <para>Configuring to search in the staging area</para>
2581       </listitem>
2582
2583       <listitem>
2584         <para>-L${STAGING_LIBDIR} vs ${TARGET_LDFLAGS}</para>
2585       </listitem>
2586
2587       <listitem>
2588         <para>Site files</para>
2589       </listitem>
2590     </itemizedlist>
2591   </section>
2592
2593   <section id="recipes_installation_scripts" xreflabel="installation scripts">
2594     <title>Installation scripts: Running scripts during package install and/or
2595     removal</title>
2596
2597     <para>Packaging system such as .ipkg and .deb support pre and post
2598     installation and pre and post removal scripts which are run during package
2599     install and/or package removal on the target system.</para>
2600
2601     <para>These scripts can be defined in your recipes to enable actions to be
2602     performed at the appropriate time. Common uses include starting new
2603     daemons on installation, stopping daemons during uninstall, creating new
2604     user and/or group entries during install, registering and unregistering
2605     alternative implementations of commands and registering the need for
2606     volatiles.</para>
2607
2608     <para>The following scripts are supported:</para>
2609
2610     <variablelist>
2611       <varlistentry>
2612         <term>preinst</term>
2613
2614         <listitem>
2615           <para>The preinst script is run prior to installing the contents of
2616           the package. During preinst the contents of the package are not
2617           available to be used as part of the script. The preinst scripts are
2618           not commonly used.</para>
2619         </listitem>
2620       </varlistentry>
2621
2622       <varlistentry>
2623         <term>postinst</term>
2624
2625         <listitem>
2626           <para>The postinst script is run after the installation of the
2627           package has completed. During postinst the contents of the package
2628           are available to be used. This is often used for the creation of
2629           volatile directories, registration of daemons, starting of daemons
2630           and fixing up of SUID binaries.</para>
2631         </listitem>
2632       </varlistentry>
2633
2634       <varlistentry>
2635         <term>prerm</term>
2636
2637         <listitem>
2638           <para>The prerm is run prior to the removal of the contents of a
2639           package. During prerm the contents of the package are still
2640           available for use by the script. The prerm scripts</para>
2641         </listitem>
2642       </varlistentry>
2643
2644       <varlistentry>
2645         <term>postrm</term>
2646
2647         <listitem>
2648           <para>The postrm script is run after the completion of the removal
2649           of the contents of a package. During postrm the contents of the
2650           package no longer exist and therefore are not available for use by
2651           the script. Postrm is most commonly used for update alternatives (to
2652           tell the alternatives system that this alternative is not available
2653           and another should be selected).</para>
2654         </listitem>
2655       </varlistentry>
2656     </variablelist>
2657
2658     <para>Scripts are registered by defining a function for:</para>
2659
2660     <itemizedlist>
2661       <listitem>
2662         <para>pkg_&lt;scriptname&gt;_&lt;packagename&gt;</para>
2663       </listitem>
2664     </itemizedlist>
2665
2666     <para>The following example from ndisc6 shows postinst scripts being
2667     registered for three of the packages that ndisc6 creates:<screen># Enable SUID bit for applications that need it
2668 pkg_postinst_${PN}-rltraceroute6 () {
2669     chmod 4555 ${bindir}/rltraceroute6
2670 }
2671 pkg_postinst_${PN}-ndisc6 () {
2672     chmod 4555 ${bindir}/ndisc6
2673 }
2674 pkg_postinst_${PN}-rdisc6 () {
2675     chmod 4555 ${bindir}/rdisc6
2676 }</screen></para>
2677
2678     <note>
2679       <para>These scripts will be run via <emphasis
2680       role="bold">/bin/sh</emphasis> on the target device, which is typically
2681       the busybox sh but could also be bash or some other sh compatible shell.
2682       As always you should not use any bash extensions in your scripts and
2683       stick to basic sh syntax.</para>
2684     </note>
2685
2686     <para>Note that several classes will also register scripts, and that any
2687     script you declare will have the script for the classes append to by these
2688     classes. The following classes all generate additional script
2689     contents:</para>
2690
2691     <variablelist>
2692       <varlistentry>
2693         <term>update-rc.d</term>
2694
2695         <listitem>
2696           <para>This class is used by daemons to register there init scripts
2697           with the init code.</para>
2698
2699           <para>Details are provided in the <xref
2700           linkend="recipes_initscripts" /> section.</para>
2701         </listitem>
2702       </varlistentry>
2703
2704       <varlistentry>
2705         <term>module</term>
2706
2707         <listitem>
2708           <para>This class is used by linux kernel modules. It's responsible
2709           for calling depmod and update-modules during kernel module
2710           installation and removal.</para>
2711         </listitem>
2712       </varlistentry>
2713
2714       <varlistentry>
2715         <term>kernel</term>
2716
2717         <listitem>
2718           <para>This class is used by the linux kernel itself. There is a lot
2719           of housekeeping required both when installing and removing a kernel
2720           and this class is responsible for generating the required
2721           scripts.</para>
2722         </listitem>
2723       </varlistentry>
2724
2725       <varlistentry>
2726         <term>qpf</term>
2727
2728         <listitem>
2729           <para>This class is used when installing and/or removing qpf fonts.
2730           It register scripts to update the font paths and font cache
2731           information to ensure that the font information is kept up to date
2732           as fonts and installed and removed.</para>
2733         </listitem>
2734       </varlistentry>
2735
2736       <varlistentry>
2737         <term>update-alternatives</term>
2738
2739         <listitem>
2740           <para>This class is used by packages that contain binaries which may
2741           also be available for other packages. It tells that system that
2742           another alternative is available for consideration. The alternatives
2743           system will create a symlink to the correct alternative from one or
2744           more available on the system.</para>
2745
2746           <para>Details are provided in the <xref
2747           linkend="recipes_alternatives" /> section.</para>
2748         </listitem>
2749       </varlistentry>
2750
2751       <varlistentry>
2752         <term>gtk-icon-cache</term>
2753
2754         <listitem>
2755           <para>This class is used by packages that add new gtk icons. It's
2756           responsible for updating the icon cache when packages are installed
2757           and removed.</para>
2758         </listitem>
2759       </varlistentry>
2760
2761       <varlistentry>
2762         <term>gconf</term>
2763
2764         <listitem>
2765           <para></para>
2766         </listitem>
2767       </varlistentry>
2768
2769       <varlistentry>
2770         <term>package</term>
2771
2772         <listitem>
2773           <para>The base class used by packaging classes such as those for
2774           .ipkg and .deb. The package class may create scripts used to update
2775           the dynamic linkers ld cache.</para>
2776         </listitem>
2777       </varlistentry>
2778     </variablelist>
2779
2780     <para>The following example from p3scan shows and postinst script which
2781     ensure that the required user and group entries exist, and registers the
2782     need for volatiles (directories and/or files under <emphasis
2783     role="bold">/var</emphasis>). In addition to explicitly declaring a
2784     postinst script it uses the update-rc.d class which will result in an
2785     additional entry being added to the postinst script to register the init
2786     scripts and start the daemon (via call to update-rc.d as describes in the
2787     <xref linkend="recipes_alternatives" /> section).<screen>inherit autotools update-rc.d
2788
2789 ...
2790
2791 # Add havp's user and groups
2792 pkg_postinst_${PN} () {
2793         grep -q mail: /etc/group || addgroup --system havp
2794         grep -q mail: /etc/passwd || \
2795             adduser --disabled-password --home=${localstatedir}/mail --system \
2796                     --ingroup mail --no-create-home -g "Mail" mail
2797         /etc/init.d/populate-volatile.sh update
2798 }</screen></para>
2799
2800     <para>Several scripts in existing recipes will be of the following
2801     form:<screen>if [ x"$D" = "x" ]; then
2802     ...
2803 fi</screen></para>
2804
2805     <para>This is testing if the installation directory, <emphasis
2806     role="bold">D</emphasis>, is defined and if it is no actions are
2807     performed. The installation directory will not be defined under normal
2808     circumstances. The primary use of this test is to permit the application
2809     to be installed during root filesystem generation. In that situation the
2810     scripts cannot be run since the root filesystem is generated on the host
2811     system and not on the target. Any required script actions would need to be
2812     performed via an alternative method if the package is to be installed in
2813     the initial root filesystem (such as including any required users and
2814     groups in the default <emphasis role="bold">passwd</emphasis> and
2815     <emphasis role="bold">group</emphasis> files for example.)</para>
2816   </section>
2817
2818   <section id="recipes_conffiles" xreflabel="conf files">
2819     <title>Configuration files</title>
2820
2821     <para>Configuration files that are installed as part of a package require
2822     special handling. Without special handling as soon as the user upgrades to
2823     a new version of the package then changes they have made to the
2824     configuration files will be lost.</para>
2825
2826     <para>In order to prevent this from happening you need to tell the
2827     packaging system which files are configuration files. Such files will
2828     result in the user being asked how the user wants to handle any
2829     configuration file changes (if any), as shown in this example:<screen>Downloading http://nynaeve.twibble.org/ipkg-titan-glibc//./p3scan_2.9.05d-r1_sh4.ipk
2830     Configuration file '/etc/p3scan/p3scan.conf'
2831     ==&gt; File on system created by you or by a script.
2832     ==&gt; File also in package provided by package maintainer.
2833        What would you like to do about it ?  Your options are:
2834         Y or I  : install the package maintainer's version
2835         N or O  : keep your currently-installed version
2836           D     : show the differences between the versions (if diff is installed)
2837      The default action is to keep your current version.
2838     *** p3scan.conf (Y/I/N/O/D) [default=N] ?</screen>To declare a file as a
2839     configuration file you need to define the
2840     <command>CONFFILES_&lt;pkgname&gt;</command> variable as a whitespace
2841     separated list of configuration files. The following example from clamav
2842     shows two files being marked as configuration files:<screen>CONFFILES_${PN}-daemon = "${sysconfdir}/clamd.conf \
2843                           ${sysconfdir}/default/clamav-daemon"</screen>Note
2844     the user of <command>${PN}-daemon</command> as the package name. The
2845     <command>${PN}</command> variable will expand to <command>clamav</command>
2846     and therefore these conf files are declared as being in the clamav-daemon
2847     package.</para>
2848   </section>
2849
2850   <section id="recipes_package_relationships"
2851            xreflabel="package relationships files">
2852     <title>Package relationships</title>
2853
2854     <para>Explicit relationships between packages are support by packaging
2855     formats such as ipkg and deb. These relationships include describing
2856     conflicting packages and recommended packages.</para>
2857
2858     <para>The following variables control the package relationships in the
2859     recipes:</para>
2860
2861     <variablelist>
2862       <varlistentry>
2863         <term>RRECOMMENDS</term>
2864
2865         <listitem>
2866           <para>Used to specify other packages that are recommended to be
2867           installed when this package is installed. Generally this means while
2868           the recommended packages are not required they provide some sort of
2869           functionality which users would usually want.</para>
2870         </listitem>
2871       </varlistentry>
2872
2873       <varlistentry>
2874         <term>RCONFLICTS</term>
2875
2876         <listitem>
2877           <para>Used to specify other packages that conflict with this
2878           package. Two packages that conflict cannot be installed at the same
2879           time.</para>
2880         </listitem>
2881       </varlistentry>
2882
2883       <varlistentry>
2884         <term>RREPLACES</term>
2885
2886         <listitem>
2887           <para>Used to specify that the current package replaces an older
2888           package with a different name. During package installing the package
2889           that is being replaced will be removed since it is no longer needed
2890           when this package is installed.</para>
2891         </listitem>
2892       </varlistentry>
2893
2894       <varlistentry>
2895         <term>RSUGGESTS</term>
2896
2897         <listitem>
2898           <para>Used to provide a list of suggested packages to install. These
2899           are packages that are related to and useful for the current package
2900           but which are not actually required to use the package.</para>
2901         </listitem>
2902       </varlistentry>
2903
2904       <varlistentry>
2905         <term>RPROVIDES</term>
2906
2907         <listitem>
2908           <para>Used to explicitly specify what a package provides at runtime.
2909           For example hotplug support is provided by several packages, such as
2910           udev and linux-hotplug. Both declare that they runtime provide
2911           "hotplug". So any packages that require "hotplug" to work simply
2912           declare that it RDEPENDS on "hotplug". It's up to the distribution
2913           to specify which actual implementation of "virtual/xserver" is
2914           used.</para>
2915         </listitem>
2916       </varlistentry>
2917
2918       <varlistentry>
2919         <term>PROVIDES</term>
2920
2921         <listitem>
2922           <para>Used to explicitly specify what a package provides at build
2923           time. This is typically used when two or more packages can provide
2924           the same functionality. For example there are several different X
2925           servers in OpenEmbedded, and each as declared as providing
2926           "virtual/xserver". Therefore a package that depends on an X server
2927           to build can simply declare that it DEPENDS on "virtual/xserver".
2928           It's up to the distribution to specify which actual implementation
2929           of "virtual/xserver" is used.</para>
2930         </listitem>
2931       </varlistentry>
2932     </variablelist>
2933   </section>
2934
2935   <section id="recipes_fakeroot" xreflabel="fakeroot">
2936     <title>Fakeroot: Dealing with the need for "root"</title>
2937
2938     <para>Sometimes packages requires root permissions in order to perform
2939     some action, such as changing user or group owners or creating device
2940     nodes. Since OpenEmbedded will not keep the user and group information
2941     it's usually preferably to remove that from the makefiles. For device
2942     nodes it's usually preferably to create them from the initial device node
2943     lists or via udev configuration.</para>
2944
2945     <para>However if you can't get by without root permissions then you can
2946     use <xref linkend="fakeroot" /> to simulate a root environment, without
2947     the need to really give root access.</para>
2948
2949     <para>Using <xref linkend="fakeroot" /> is done by prefixing the
2950     task:<screen>fakeroot do_install() {</screen>Since this requires fakeroot
2951     you also need to add a dependency on
2952     <command>fakeroot-native</command>:<screen>DEPENDS = "fakeroot-native"</screen>See
2953     the fuse recipe for an example. Further information on <xref
2954     linkend="fakeroot" />, including a description of it works, is provided in
2955     the reference section: <xref linkend="fakeroot" />.</para>
2956   </section>
2957
2958   <section id="recipes_native" xreflabel="native">
2959     <title>Native: Packages for the build host</title>
2960
2961     <para>This section is to be completed.</para>
2962
2963     <itemizedlist>
2964       <listitem>
2965         <para>What native packages are</para>
2966       </listitem>
2967
2968       <listitem>
2969         <para>Using require with the non-native package</para>
2970       </listitem>
2971     </itemizedlist>
2972   </section>
2973
2974   <section id="recipes_development" xreflabel="development">
2975     <title>Development: Strategies for developing recipes</title>
2976
2977     <para>This section is to be completed.</para>
2978
2979     <itemizedlist>
2980       <listitem>
2981         <para>How to go about developing recipes</para>
2982       </listitem>
2983
2984       <listitem>
2985         <para>How do handle incrementally creating patches</para>
2986       </listitem>
2987
2988       <listitem>
2989         <para>How to deal with site file issues</para>
2990       </listitem>
2991
2992       <listitem>
2993         <para>Strategies for autotools issues</para>
2994       </listitem>
2995     </itemizedlist>
2996   </section>
2997
2998   <section id="recipes_advanced_versioning" xreflabel="advanced versioning">
2999     <title>Advanced versioning: How to deal with rc and pre versions</title>
3000
3001     <para>Special care needs to be taken when specify the version number for
3002     rc and pre versions of packages.</para>
3003
3004     <para>Consider the case where we have an existing 1.5 version and there's
3005     a new 1.6-rc1 release that you want to add.</para>
3006
3007     <itemizedlist>
3008       <listitem>
3009         <para>1.5: Existing version;</para>
3010       </listitem>
3011
3012       <listitem>
3013         <para>1.6-rc1: New version.</para>
3014       </listitem>
3015     </itemizedlist>
3016
3017     <para>If the new package is given the version number 1.6-rc1 then
3018     everything will work fine initially. However when the final release
3019     happens it will be called 1.6. If you now create a 1.6 version of the
3020     package you'll find that the packages are sorted into the following
3021     order:</para>
3022
3023     <orderedlist>
3024       <listitem>
3025         <para>1.5</para>
3026       </listitem>
3027
3028       <listitem>
3029         <para>1.6</para>
3030       </listitem>
3031
3032       <listitem>
3033         <para>1.6-rc1</para>
3034       </listitem>
3035     </orderedlist>
3036
3037     <para>This in turn result in packaging system, such as ipkg, considering
3038     the released version to be older then the rc version.</para>
3039
3040     <para>In OpenEmbedded the correct naming of pre and rc versions is to use
3041     the previous version number followed by a + followed by the new version
3042     number. So the 1.6-rc1 release would be given the version number:</para>
3043
3044     <itemizedlist>
3045       <listitem>
3046         <para>1.5+1.6-rc1</para>
3047       </listitem>
3048     </itemizedlist>
3049
3050     <para>These would result in the eventually ordering being:</para>
3051
3052     <orderedlist>
3053       <listitem>
3054         <para>1.5</para>
3055       </listitem>
3056
3057       <listitem>
3058         <para>1.5+1.6-rc1</para>
3059       </listitem>
3060
3061       <listitem>
3062         <para>1.6</para>
3063       </listitem>
3064     </orderedlist>
3065
3066     <para>This is the correct order and the packaging system will now work as
3067     expected.</para>
3068   </section>
3069
3070   <section id="recipes_require" xreflabel="require">
3071     <title>Require/include: Reusing recipe contents</title>
3072
3073     <para>In many packages where you are maintaining multiple versions you'll
3074     often end up with several recipes which are either identical, or have only
3075     minor differences between them.</para>
3076
3077     <para>The require and/or include directive can be used to include common
3078     content from one file into other. You should always look for a way to
3079     factor out common functionality into an include file when adding new
3080     versions of a recipe.</para>
3081
3082     <note>
3083       <para>Both require and include perform the same function - including the
3084       contents of another file into this recipe. The difference is that
3085       require will generate an error if the file is not found while include
3086       will not. For this reason include should not be used in new
3087       recipes.</para>
3088     </note>
3089
3090     <para>For example the clamav recipe looks like this:<screen>require clamav.inc
3091
3092 PR = "r0"</screen>Note that all of the functionality of the recipe is provided
3093     in the clamav.inc file, only the release number is defined in the recipe.
3094     Each of the recipes includes the same <emphasis
3095     role="bold">clamav.inc</emphasis> file to save having to duplicate any
3096     functionality. This also means that as new versions are released it's a
3097     simple matter of copying the recipe and resetting the release number back
3098     to zero.</para>
3099
3100     <para>The following example from iproute2 shows the recipe adding
3101     additional patches that are not specified by the common included file.
3102     These are patches only needed for newer release and by only adding them in
3103     this recipe it permits the common code to be used for both old and new
3104     recipes:<screen>PR = "r1"
3105
3106 SRC_URI += "file://iproute2-2.6.15_no_strip.diff;patch=1;pnum=0 \
3107             file://new-flex-fix.patch;patch=1"
3108
3109 require iproute2.inc
3110
3111 DATE = "060323"</screen></para>
3112
3113     <para>The following example from cherokee shows a similar method of
3114     including additional patches for this version only. However it also show
3115     another technique in which the configure task is defined in the recipe for
3116     this version, thus replacing the <emphasis>configure</emphasis> task that
3117     is provided by the common include:<screen>PR = "r7"
3118
3119 SRC_URI_append = "file://configure.patch;patch=1 \
3120                   file://Makefile.in.patch;patch=1 \
3121                   file://Makefile.cget.patch;patch=1 \
3122                   file://util.patch;patch=1"
3123
3124 require cherokee.inc
3125
3126 do_configure() {
3127         gnu-configize
3128         oe_runconf
3129         sed -i 's:-L\$:-L${STAGING_LIBDIR} -L\$:' ${S}/*libtool
3130 }</screen></para>
3131   </section>
3132
3133   <section id="recipes_advanced_python" xreflabel="advanced python">
3134     <title>Python: Advanced functionality with python</title>
3135
3136     <para>Recipes permit the use of python code in order to perform complex
3137     operations which are not possible with the normal recipe syntax and
3138     variables. Python can be used in both variable assignments and in the
3139     implementation of tasks.</para>
3140
3141     <para>For variable assignments python code is indicated via the use of
3142     <emphasis>${@...}</emphasis>, as shown in the following example:<screen>TAG = ${@bb.data.getVar('PV',d,1).replace('.', '_')}</screen></para>
3143
3144     <para>The above example retrieves the PV variable from the bitbake data
3145     object, the replaces any dots with underscores. Therefore if the <emphasis
3146     role="bold">PV</emphasis> was <emphasis role="bold">0.9.0</emphasis> then
3147     <emphasis role="bold">TAG</emphasis> will be set to <emphasis
3148     role="bold">0-9-0</emphasis>.</para>
3149
3150     <para>Some of the more common python code in use in existing recipes is
3151     shown in the following table:</para>
3152
3153     <variablelist>
3154       <varlistentry>
3155         <term>bb.data.getVar(&lt;var&gt;,d,1)</term>
3156
3157         <listitem>
3158           <para>Retrieve the data for the specified variable from the bitbake
3159           database for the current recipe.</para>
3160         </listitem>
3161       </varlistentry>
3162
3163       <varlistentry>
3164         <term>&lt;variable&gt;.replace(&lt;key&gt;,
3165         &lt;replacement&gt;)</term>
3166
3167         <listitem>
3168           <para>Find each instance of the key and replace it with the
3169           replacement value. This can also be used to remove part of a string
3170           by specifying <emphasis role="bold">''</emphasis> (two single
3171           quotes) as the replacement.</para>
3172
3173           <para>The following example would remove the <emphasis
3174           role="bold">'-frename-registers'</emphasis> option from the
3175           <emphasis role="bold">CFLAGS</emphasis> variable:<screen>CFLAGS := "${@'${CFLAGS}'.replace('-frename-registers', '')}"</screen></para>
3176         </listitem>
3177       </varlistentry>
3178
3179       <varlistentry>
3180         <term>os.path.dirname(&lt;filename&gt;)</term>
3181
3182         <listitem>
3183           <para>Return the directory only part of a filename.</para>
3184
3185           <para>This is most commonly seen in existing recipes when settings
3186           the <emphasis role="bold">FILESDIR</emphasis> variable (as described
3187           in the <xref linkend="recipes_filespath_dir" /> section). By
3188           obtaining name of the recipe file itself, <emphasis
3189           role="bold">FILE</emphasis>, and then using os.path.dirname to strip
3190           the filename part:<screen>FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/make-${PV}"</screen>Note
3191           however that this is no longer required as <emphasis
3192           role="bold">FILE_DIRNAME</emphasis> is automatically set to the
3193           dirname of the <emphasis role="bold">FILE</emphasis> variable and
3194           therefore this would be written in new recipes as:<screen>FILESDIR = "$FILE_DIRNAME/make-${PV}"</screen></para>
3195         </listitem>
3196       </varlistentry>
3197
3198       <varlistentry>
3199         <term>&lt;variable&gt;.split(&lt;key&gt;)[&lt;index&gt;]</term>
3200
3201         <listitem>
3202           <para>Splits are variable around the specified key. Use <emphasis
3203           role="bold">[&lt;index&gt;]</emphasis> to select one of the matching
3204           items from the array generated by the split command.</para>
3205
3206           <para>The following example from the recipe g<emphasis
3207           role="bold">enext2fs_1.3+1.4rc1.bb</emphasis> would take the
3208           <emphasis role="bold">PV</emphasis> of <emphasis
3209           role="bold">1.3+1.4rc1</emphasis> and split it around the <emphasis
3210           role="bold">+</emphasis> sign, resulting in an array containing
3211           <emphasis role="bold">1.3</emphasis> and <emphasis
3212           role="bold">1.4rc1</emphasis>. It then uses the index of <emphasis
3213           role="bold">[1]</emphasis> to select the second item from the list
3214           (the first item is at index <emphasis role="bold">0</emphasis>).
3215           Therefore <emphasis role="bold">TRIMMEDV</emphasis> would be set to
3216           <emphasis role="bold">1.4rc1</emphasis> for this recipe:</para>
3217
3218           <screen>TRIMMEDV = "${@bb.data.getVar('PV', d, 1).split('+')[1]}"</screen>
3219         </listitem>
3220       </varlistentry>
3221     </variablelist>
3222
3223     <para>As well as directly calling built-in python functions, those
3224     functions defined by the existing classes may also be called. A set of
3225     common functions is provided by the base class in <emphasis
3226     role="bold">classes/base.bbclass</emphasis>:</para>
3227
3228     <variablelist>
3229       <varlistentry>
3230         <term>base_conditional</term>
3231