summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml7381
-rw-r--r--documentation/dev-manual/dev-manual-customization.xsl10
-rw-r--r--documentation/dev-manual/dev-manual-eclipse-customization.xsl27
-rw-r--r--documentation/dev-manual/dev-manual-intro.xml207
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2069
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml1687
-rw-r--r--documentation/dev-manual/dev-manual-start.xml415
-rw-r--r--documentation/dev-manual/dev-manual.xml107
-rw-r--r--documentation/dev-manual/dev-style.css979
-rw-r--r--documentation/dev-manual/figures/app-dev-flow.pngbin0 -> 53301 bytes
-rw-r--r--documentation/dev-manual/figures/bsp-dev-flow.pngbin0 -> 42751 bytes
-rw-r--r--documentation/dev-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/dev-manual/figures/git-workflow.pngbin0 -> 26586 bytes
-rw-r--r--documentation/dev-manual/figures/index-downloads.pngbin0 -> 100374 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin0 -> 35561 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-1.pngbin0 -> 35839 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-2-generic.pngbin0 -> 39931 bytes
-rw-r--r--documentation/dev-manual/figures/recipe-workflow.pngbin0 -> 48276 bytes
-rw-r--r--documentation/dev-manual/figures/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/dev-manual/figures/yp-download.pngbin0 -> 193275 bytes
20 files changed, 12882 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
new file mode 100644
index 0000000..445ca17
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,7381 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='extendpoky'>
6
7<title>Common Tasks</title>
8 <para>
9 This chapter describes fundamental procedures such as creating layers,
10 adding new software packages, extending or customizing images,
11 porting work to new hardware (adding a new machine), and so forth.
12 You will find that the procedures documented here occur often in the
13 development cycle using the Yocto Project.
14 </para>
15
16 <section id="understanding-and-creating-layers">
17 <title>Understanding and Creating Layers</title>
18
19 <para>
20 The OpenEmbedded build system supports organizing
21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from
23 each other.
24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular your Metadata, the easier
27 it is to cope with future changes.
28 </para>
29
30 <para>
31 To illustrate how layers are used to keep things modular, consider
32 machine customizations.
33 These types of customizations typically reside in a special layer,
34 rather than a general layer, called a Board Support Package (BSP)
35 Layer.
36 Furthermore, the machine customizations should be isolated from
37 recipes and Metadata that support a new GUI environment,
38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
44 with those machine-specific changes.
45 You can accomplish this through a recipe that is a BitBake append
46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
48 </para>
49
50 <para>
51 </para>
52
53 <section id='yocto-project-layers'>
54 <title>Layers</title>
55
56 <para>
57 The <link linkend='source-directory'>Source Directory</link>
58 contains both general layers and BSP
59 layers right out of the box.
60 You can easily identify layers that ship with a
61 Yocto Project release in the Source Directory by their
62 folder names.
63 Folders that represent layers typically have names that begin with
64 the string <filename>meta-</filename>.
65 <note>
66 It is not a requirement that a layer name begin with the
67 prefix <filename>meta-</filename>, but it is a commonly
68 accepted standard in the Yocto Project community.
69 </note>
70 For example, when you set up the Source Directory structure,
71 you will see several layers:
72 <filename>meta</filename>,
73 <filename>meta-skeleton</filename>,
74 <filename>meta-yocto</filename>, and
75 <filename>meta-yocto-bsp</filename>.
76 Each of these folders represents a distinct layer.
77 </para>
78
79 <para>
80 As another example, if you set up a local copy of the
81 <filename>meta-intel</filename> Git repository
82 and then explore the folder of that general layer,
83 you will discover many Intel-specific BSP layers inside.
84 For more information on BSP layers, see the
85 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
86 section in the Yocto Project Board Support Package (BSP)
87 Developer's Guide.
88 </para>
89 </section>
90
91 <section id='creating-your-own-layer'>
92 <title>Creating Your Own Layer</title>
93
94 <para>
95 It is very easy to create your own layers to use with the
96 OpenEmbedded build system.
97 The Yocto Project ships with scripts that speed up creating
98 general layers and BSP layers.
99 This section describes the steps you perform by hand to create
100 a layer so that you can better understand them.
101 For information about the layer-creation scripts, see the
102 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
103 section in the Yocto Project Board Support Package (BSP)
104 Developer's Guide and the
105 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
106 section further down in this manual.
107 </para>
108
109 <para>
110 Follow these general steps to create your layer:
111 <orderedlist>
112 <listitem><para><emphasis>Check Existing Layers:</emphasis>
113 Before creating a new layer, you should be sure someone
114 has not already created a layer containing the Metadata
115 you need.
116 You can see the
117 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
118 for a list of layers from the OpenEmbedded community
119 that can be used in the Yocto Project.
120 </para></listitem>
121 <listitem><para><emphasis>Create a Directory:</emphasis>
122 Create the directory for your layer.
123 While not strictly required, prepend the name of the
124 folder with the string <filename>meta-</filename>.
125 For example:
126 <literallayout class='monospaced'>
127 meta-mylayer
128 meta-GUI_xyz
129 meta-mymachine
130 </literallayout>
131 </para></listitem>
132 <listitem><para><emphasis>Create a Layer Configuration
133 File:</emphasis>
134 Inside your new layer folder, you need to create a
135 <filename>conf/layer.conf</filename> file.
136 It is easiest to take an existing layer configuration
137 file and copy that to your layer's
138 <filename>conf</filename> directory and then modify the
139 file as needed.</para>
140 <para>The
141 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
142 demonstrates the required syntax:
143 <literallayout class='monospaced'>
144 # We have a conf and classes directory, add to BBPATH
145 BBPATH .= ":${LAYERDIR}"
146
147 # We have recipes-* directories, add to BBFILES
148 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
149 ${LAYERDIR}/recipes-*/*/*.bbappend"
150
151 BBFILE_COLLECTIONS += "yoctobsp"
152 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
153 BBFILE_PRIORITY_yoctobsp = "5"
154 LAYERVERSION_yoctobsp = "2"
155 </literallayout></para>
156 <para>Here is an explanation of the example:
157 <itemizedlist>
158 <listitem><para>The configuration and
159 classes directory is appended to
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
161 <note>
162 All non-distro layers, which include all BSP
163 layers, are expected to append the layer
164 directory to the
165 <filename>BBPATH</filename>.
166 On the other hand, distro layers, such as
167 <filename>meta-yocto</filename>, can choose
168 to enforce their own precedence over
169 <filename>BBPATH</filename>.
170 For an example of that syntax, see the
171 <filename>layer.conf</filename> file for
172 the <filename>meta-yocto</filename> layer.
173 </note></para></listitem>
174 <listitem><para>The recipes for the layers are
175 appended to
176 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
177 </para></listitem>
178 <listitem><para>The
179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
180 variable is then appended with the layer name.
181 </para></listitem>
182 <listitem><para>The
183 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
184 variable is set to a regular expression and is
185 used to match files from
186 <filename>BBFILES</filename> into a particular
187 layer.
188 In this case,
189 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
190 is used to make <filename>BBFILE_PATTERN</filename> match within the
191 layer's path.</para></listitem>
192 <listitem><para>The
193 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
194 variable then assigns a priority to the layer.
195 Applying priorities is useful in situations
196 where the same package might appear in multiple
197 layers and allows you to choose the layer
198 that takes precedence.</para></listitem>
199 <listitem><para>The
200 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
201 variable optionally specifies the version of a
202 layer as a single number.</para></listitem>
203 </itemizedlist></para>
204 <para>Note the use of the
205 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
206 variable, which expands to the directory of the current
207 layer.</para>
208 <para>Through the use of the <filename>BBPATH</filename>
209 variable, BitBake locates class files
210 (<filename>.bbclass</filename>),
211 configuration files, and files that are included
212 with <filename>include</filename> and
213 <filename>require</filename> statements.
214 For these cases, BitBake uses the first file that
215 matches the name found in <filename>BBPATH</filename>.
216 This is similar to the way the <filename>PATH</filename>
217 variable is used for binaries.
218 It is recommended, therefore, that you use unique
219 class and configuration
220 filenames in your custom layer.</para></listitem>
221 <listitem><para><emphasis>Add Content:</emphasis> Depending
222 on the type of layer, add the content.
223 If the layer adds support for a machine, add the machine
224 configuration in a <filename>conf/machine/</filename>
225 file within the layer.
226 If the layer adds distro policy, add the distro
227 configuration in a <filename>conf/distro/</filename>
228 file within the layer.
229 If the layer introduces new recipes, put the recipes
230 you need in <filename>recipes-*</filename>
231 subdirectories within the layer.
232 <note>In order to be compliant with the Yocto Project,
233 a layer must contain a
234 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
235 </note></para></listitem>
236 </orderedlist>
237 </para>
238 </section>
239
240 <section id='best-practices-to-follow-when-creating-layers'>
241 <title>Best Practices to Follow When Creating Layers</title>
242
243 <para>
244 To create layers that are easier to maintain and that will
245 not impact builds for other machines, you should consider the
246 information in the following sections.
247 </para>
248
249 <section id='avoid-overlaying-entire-recipes'>
250 <title>Avoid "Overlaying" Entire Recipes</title>
251
252 <para>
253 Avoid "overlaying" entire recipes from other layers in your
254 configuration.
255 In other words, do not copy an entire recipe into your
256 layer and then modify it.
257 Rather, use an append file (<filename>.bbappend</filename>)
258 to override
259 only those parts of the original recipe you need to modify.
260 </para>
261 </section>
262
263 <section id='avoid-duplicating-include-files'>
264 <title>Avoid Duplicating Include Files</title>
265
266 <para>
267 Avoid duplicating include files.
268 Use append files (<filename>.bbappend</filename>)
269 for each recipe
270 that uses an include file.
271 Or, if you are introducing a new recipe that requires
272 the included file, use the path relative to the original
273 layer directory to refer to the file.
274 For example, use
275 <filename>require recipes-core/somepackage/somefile.inc</filename>
276 instead of <filename>require somefile.inc</filename>.
277 If you're finding you have to overlay the include file,
278 it could indicate a deficiency in the include file in
279 the layer to which it originally belongs.
280 If this is the case, you need to address that deficiency
281 instead of overlaying the include file.
282 </para>
283
284 <para>
285 For example, consider how support plug-ins for the Qt 4
286 database are configured.
287 The Source Directory does not have MySQL or PostgreSQL.
288 However, OpenEmbedded's layer <filename>meta-oe</filename>
289 does.
290 Consequently, <filename>meta-oe</filename> uses
291 append files to modify the
292 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
293 enable the appropriate plug-ins.
294 This variable was added to the <filename>qt4.inc</filename>
295 include file in the Source Directory specifically to allow
296 the <filename>meta-oe</filename> layer to be able to control
297 which plug-ins are built.
298 </para>
299 </section>
300
301 <section id='structure-your-layers'>
302 <title>Structure Your Layers</title>
303
304 <para>
305 Proper use of overrides within append files and placement
306 of machine-specific files within your layer can ensure that
307 a build is not using the wrong Metadata and negatively
308 impacting a build for a different machine.
309 Following are some examples:
310 <itemizedlist>
311 <listitem><para><emphasis>Modifying Variables to Support
312 a Different Machine:</emphasis>
313 Suppose you have a layer named
314 <filename>meta-one</filename> that adds support
315 for building machine "one".
316 To do so, you use an append file named
317 <filename>base-files.bbappend</filename> and
318 create a dependency on "foo" by altering the
319 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
320 variable:
321 <literallayout class='monospaced'>
322 DEPENDS = "foo"
323 </literallayout>
324 The dependency is created during any build that
325 includes the layer
326 <filename>meta-one</filename>.
327 However, you might not want this dependency
328 for all machines.
329 For example, suppose you are building for
330 machine "two" but your
331 <filename>bblayers.conf</filename> file has the
332 <filename>meta-one</filename> layer included.
333 During the build, the
334 <filename>base-files</filename> for machine
335 "two" will also have the dependency on
336 <filename>foo</filename>.</para>
337 <para>To make sure your changes apply only when
338 building machine "one", use a machine override
339 with the <filename>DEPENDS</filename> statement:
340 <literallayout class='monospaced'>
341 DEPENDS_one = "foo"
342 </literallayout>
343 You should follow the same strategy when using
344 <filename>_append</filename> and
345 <filename>_prepend</filename> operations:
346 <literallayout class='monospaced'>
347 DEPENDS_append_one = " foo"
348 DEPENDS_prepend_one = "foo "
349 </literallayout>
350 <note>
351 Avoiding "+=" and "=+" and using
352 machine-specific
353 <filename>_append</filename>
354 and <filename>_prepend</filename> operations
355 is recommended as well.
356 </note></para></listitem>
357 <listitem><para><emphasis>Place Machine-Specific Files
358 in Machine-Specific Locations:</emphasis>
359 When you have a base recipe, such as
360 <filename>base-files.bb</filename>, that
361 contains a
362 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
363 statement to a file, you can use an append file
364 to cause the build to use your own version of
365 the file.
366 For example, an append file in your layer at
367 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
368 could extend
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
370 using
371 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
372 as follows:
373 <literallayout class='monospaced'>
374 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
375 </literallayout>
376 The build for machine "one" will pick up your
377 machine-specific file as long as you have the
378 file in
379 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
380 However, if you are building for a different
381 machine and the
382 <filename>bblayers.conf</filename> file includes
383 the <filename>meta-one</filename> layer and
384 the location of your machine-specific file is
385 the first location where that file is found
386 according to <filename>FILESPATH</filename>,
387 builds for all machines will also use that
388 machine-specific file.</para>
389 <para>You can make sure that a machine-specific
390 file is used for a particular machine by putting
391 the file in a subdirectory specific to the
392 machine.
393 For example, rather than placing the file in
394 <filename>meta-one/recipes-core/base-files/base-files/</filename>
395 as shown above, put it in
396 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
397 Not only does this make sure the file is used
398 only when building for machine "one", but the
399 build process locates the file more quickly.</para>
400 <para>In summary, you need to place all files
401 referenced from <filename>SRC_URI</filename>
402 in a machine-specific subdirectory within the
403 layer in order to restrict those files to
404 machine-specific builds.</para></listitem>
405 </itemizedlist>
406 </para>
407 </section>
408
409 <section id='other-recommendations'>
410 <title>Other Recommendations</title>
411
412 <para>
413 We also recommend the following:
414 <itemizedlist>
415 <listitem><para>Store custom layers in a Git repository
416 that uses the
417 <filename>meta-&lt;layer_name&gt;</filename> format.
418 </para></listitem>
419 <listitem><para>Clone the repository alongside other
420 <filename>meta</filename> directories in the
421 <link linkend='source-directory'>Source Directory</link>.
422 </para></listitem>
423 </itemizedlist>
424 Following these recommendations keeps your Source Directory and
425 its configuration entirely inside the Yocto Project's core
426 base.
427 </para>
428 </section>
429 </section>
430
431 <section id='enabling-your-layer'>
432 <title>Enabling Your Layer</title>
433
434 <para>
435 Before the OpenEmbedded build system can use your new layer,
436 you need to enable it.
437 To enable your layer, simply add your layer's path to the
438 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
439 variable in your <filename>conf/bblayers.conf</filename> file,
440 which is found in the
441 <link linkend='build-directory'>Build Directory</link>.
442 The following example shows how to enable a layer named
443 <filename>meta-mylayer</filename>:
444 <literallayout class='monospaced'>
445 LCONF_VERSION = "6"
446
447 BBPATH = "${TOPDIR}"
448 BBFILES ?= ""
449
450 BBLAYERS ?= " \
451 $HOME/poky/meta \
452 $HOME/poky/meta-yocto \
453 $HOME/poky/meta-yocto-bsp \
454 $HOME/poky/meta-mylayer \
455 "
456
457 BBLAYERS_NON_REMOVABLE ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 "
461 </literallayout>
462 </para>
463
464 <para>
465 BitBake parses each <filename>conf/layer.conf</filename> file
466 as specified in the <filename>BBLAYERS</filename> variable
467 within the <filename>conf/bblayers.conf</filename> file.
468 During the processing of each
469 <filename>conf/layer.conf</filename> file, BitBake adds the
470 recipes, classes and configurations contained within the
471 particular layer to the source directory.
472 </para>
473 </section>
474
475 <section id='using-bbappend-files'>
476 <title>Using .bbappend Files</title>
477
478 <para>
479 Recipes used to append Metadata to other recipes are called
480 BitBake append files.
481 BitBake append files use the <filename>.bbappend</filename> file
482 type suffix, while the corresponding recipes to which Metadata
483 is being appended use the <filename>.bb</filename> file type
484 suffix.
485 </para>
486
487 <para>
488 A <filename>.bbappend</filename> file allows your layer to make
489 additions or changes to the content of another layer's recipe
490 without having to copy the other recipe into your layer.
491 Your <filename>.bbappend</filename> file resides in your layer,
492 while the main <filename>.bb</filename> recipe file to
493 which you are appending Metadata resides in a different layer.
494 </para>
495
496 <para>
497 Append files must have the same root names as their corresponding
498 recipes.
499 For example, the append file
500 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
501 <filename>someapp_&DISTRO;.bb</filename>.
502 This means the original recipe and append file names are version
503 number-specific.
504 If the corresponding recipe is renamed to update to a newer
505 version, the corresponding <filename>.bbappend</filename> file must
506 be renamed (and possibly updated) as well.
507 During the build process, BitBake displays an error on starting
508 if it detects a <filename>.bbappend</filename> file that does
509 not have a corresponding recipe with a matching name.
510 See the
511 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
512 variable for information on how to handle this error.
513 </para>
514
515 <para>
516 Being able to append information to an existing recipe not only
517 avoids duplication, but also automatically applies recipe
518 changes in a different layer to your layer.
519 If you were copying recipes, you would have to manually merge
520 changes as they occur.
521 </para>
522
523 <para>
524 As an example, consider the main formfactor recipe and a
525 corresponding formfactor append file both from the
526 <link linkend='source-directory'>Source Directory</link>.
527 Here is the main formfactor recipe, which is named
528 <filename>formfactor_0.0.bb</filename> and located in the
529 "meta" layer at
530 <filename>meta/recipes-bsp/formfactor</filename>:
531 <literallayout class='monospaced'>
532 SUMMARY = "Device formfactor information"
533 SECTION = "base"
534 LICENSE = "MIT"
535 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
536 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
537 PR = "r44"
538
539 SRC_URI = "file://config file://machconfig"
540 S = "${WORKDIR}"
541
542 PACKAGE_ARCH = "${MACHINE_ARCH}"
543 INHIBIT_DEFAULT_DEPS = "1"
544
545 do_install() {
546 # Only install file if it has a contents
547 install -d ${D}${sysconfdir}/formfactor/
548 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
549 if [ -s "${S}/machconfig" ]; then
550 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
551 fi
552 }
553 </literallayout>
554 In the main recipe, note the
555 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
556 variable, which tells the OpenEmbedded build system where to
557 find files during the build.
558 </para>
559
560 <para>
561 Following is the append file, which is named
562 <filename>formfactor_0.0.bbappend</filename> and is from the
563 Crown Bay BSP Layer named
564 <filename>meta-intel/meta-crownbay</filename>.
565 The file is in <filename>recipes-bsp/formfactor</filename>:
566 <literallayout class='monospaced'>
567 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
568 </literallayout>
569 </para>
570
571 <para>
572 By default, the build system uses the
573 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
574 variable to locate files.
575 This append file extends the locations by setting the
576 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
577 variable.
578 Setting this variable in the <filename>.bbappend</filename>
579 file is the most reliable and recommended method for adding
580 directories to the search path used by the build system
581 to find files.
582 </para>
583
584 <para>
585 The statement in this example extends the directories to include
586 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
587 which resolves to a directory named
588 <filename>formfactor</filename> in the same directory
589 in which the append file resides (i.e.
590 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
591 This implies that you must have the supporting directory
592 structure set up that will contain any files or patches you
593 will be including from the layer.
594 </para>
595
596 <para>
597 Using the immediate expansion assignment operator
598 <filename>:=</filename> is important because of the reference to
599 <filename>THISDIR</filename>.
600 The trailing colon character is important as it ensures that
601 items in the list remain colon-separated.
602 <note>
603 <para>
604 BitBake automatically defines the
605 <filename>THISDIR</filename> variable.
606 You should never set this variable yourself.
607 Using "_prepend" ensures your path will
608 be searched prior to other paths in the final list.
609 </para>
610
611 <para>
612 Also, not all append files add extra files.
613 Many append files simply exist to add build options
614 (e.g. <filename>systemd</filename>).
615 For these cases, it is not necessary to use the
616 "_prepend" part of the statement.
617 </para>
618 </note>
619 </para>
620 </section>
621
622 <section id='prioritizing-your-layer'>
623 <title>Prioritizing Your Layer</title>
624
625 <para>
626 Each layer is assigned a priority value.
627 Priority values control which layer takes precedence if there
628 are recipe files with the same name in multiple layers.
629 For these cases, the recipe file from the layer with a higher
630 priority number takes precedence.
631 Priority values also affect the order in which multiple
632 <filename>.bbappend</filename> files for the same recipe are
633 applied.
634 You can either specify the priority manually, or allow the
635 build system to calculate it based on the layer's dependencies.
636 </para>
637
638 <para>
639 To specify the layer's priority manually, use the
640 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
641 variable.
642 For example:
643 <literallayout class='monospaced'>
644 BBFILE_PRIORITY_mylayer = "1"
645 </literallayout>
646 </para>
647
648 <note>
649 <para>It is possible for a recipe with a lower version number
650 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
651 in a layer that has a higher priority to take precedence.</para>
652 <para>Also, the layer priority does not currently affect the
653 precedence order of <filename>.conf</filename>
654 or <filename>.bbclass</filename> files.
655 Future versions of BitBake might address this.</para>
656 </note>
657 </section>
658
659 <section id='managing-layers'>
660 <title>Managing Layers</title>
661
662 <para>
663 You can use the BitBake layer management tool to provide a view
664 into the structure of recipes across a multi-layer project.
665 Being able to generate output that reports on configured layers
666 with their paths and priorities and on
667 <filename>.bbappend</filename> files and their applicable
668 recipes can help to reveal potential problems.
669 </para>
670
671 <para>
672 Use the following form when running the layer management tool.
673 <literallayout class='monospaced'>
674 $ bitbake-layers &lt;command&gt; [arguments]
675 </literallayout>
676 The following list describes the available commands:
677 <itemizedlist>
678 <listitem><para><filename><emphasis>help:</emphasis></filename>
679 Displays general help or help on a specified command.
680 </para></listitem>
681 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
682 Shows the current configured layers.
683 </para></listitem>
684 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
685 Lists available recipes and the layers that provide them.
686 </para></listitem>
687 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
688 Lists overlayed recipes.
689 A recipe is overlayed when a recipe with the same name
690 exists in another layer that has a higher layer
691 priority.
692 </para></listitem>
693 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
694 Lists <filename>.bbappend</filename> files and the
695 recipe files to which they apply.
696 </para></listitem>
697 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
698 Lists dependency relationships between recipes that
699 cross layer boundaries.
700 </para></listitem>
701 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
702 Flattens the layer configuration into a separate output
703 directory.
704 Flattening your layer configuration builds a "flattened"
705 directory that contains the contents of all layers,
706 with any overlayed recipes removed and any
707 <filename>.bbappend</filename> files appended to the
708 corresponding recipes.
709 You might have to perform some manual cleanup of the
710 flattened layer as follows:
711 <itemizedlist>
712 <listitem><para>Non-recipe files (such as patches)
713 are overwritten.
714 The flatten command shows a warning for these
715 files.
716 </para></listitem>
717 <listitem><para>Anything beyond the normal layer
718 setup has been added to the
719 <filename>layer.conf</filename> file.
720 Only the lowest priority layer's
721 <filename>layer.conf</filename> is used.
722 </para></listitem>
723 <listitem><para>Overridden and appended items from
724 <filename>.bbappend</filename> files need to be
725 cleaned up.
726 The contents of each
727 <filename>.bbappend</filename> end up in the
728 flattened recipe.
729 However, if there are appended or changed
730 variable values, you need to tidy these up
731 yourself.
732 Consider the following example.
733 Here, the <filename>bitbake-layers</filename>
734 command adds the line
735 <filename>#### bbappended ...</filename> so that
736 you know where the following lines originate:
737 <literallayout class='monospaced'>
738 ...
739 DESCRIPTION = "A useful utility"
740 ...
741 EXTRA_OECONF = "--enable-something"
742 ...
743
744 #### bbappended from meta-anotherlayer ####
745
746 DESCRIPTION = "Customized utility"
747 EXTRA_OECONF += "--enable-somethingelse"
748 </literallayout>
749 Ideally, you would tidy up these utilities as
750 follows:
751 <literallayout class='monospaced'>
752 ...
753 DESCRIPTION = "Customized utility"
754 ...
755 EXTRA_OECONF = "--enable-something --enable-somethingelse"
756 ...
757 </literallayout></para></listitem>
758 </itemizedlist></para></listitem>
759 </itemizedlist>
760 </para>
761 </section>
762
763 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
764 <title>Creating a General Layer Using the yocto-layer Script</title>
765
766 <para>
767 The <filename>yocto-layer</filename> script simplifies
768 creating a new general layer.
769 <note>
770 For information on BSP layers, see the
771 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
772 section in the Yocto Project Board Specific (BSP)
773 Developer's Guide.
774 </note>
775 The default mode of the script's operation is to prompt you for
776 information needed to generate the layer:
777 <itemizedlist>
778 <listitem><para>The layer priority
779 </para></listitem>
780 <listitem><para>Whether or not to create a sample recipe.
781 </para></listitem>
782 <listitem><para>Whether or not to create a sample
783 append file.
784 </para></listitem>
785 </itemizedlist>
786 </para>
787
788 <para>
789 Use the <filename>yocto-layer create</filename> sub-command
790 to create a new general layer.
791 In its simplest form, you can create a layer as follows:
792 <literallayout class='monospaced'>
793 $ yocto-layer create mylayer
794 </literallayout>
795 The previous example creates a layer named
796 <filename>meta-mylayer</filename> in the current directory.
797 </para>
798
799 <para>
800 As the <filename>yocto-layer create</filename> command runs,
801 default values for the prompts appear in brackets.
802 Pressing enter without supplying anything for the prompts
803 or pressing enter and providing an invalid response causes the
804 script to accept the default value.
805 Once the script completes, the new layer
806 is created in the current working directory.
807 The script names the layer by prepending
808 <filename>meta-</filename> to the name you provide.
809 </para>
810
811 <para>
812 Minimally, the script creates the following within the layer:
813 <itemizedlist>
814 <listitem><para><emphasis>The <filename>conf</filename>
815 directory:</emphasis>
816 This directory contains the layer's configuration file.
817 The root name for the file is the same as the root name
818 your provided for the layer (e.g.
819 <filename>&lt;layer&gt;.conf</filename>).
820 </para></listitem>
821 <listitem><para><emphasis>The
822 <filename>COPYING.MIT</filename> file:</emphasis>
823 The copyright and use notice for the software.
824 </para></listitem>
825 <listitem><para><emphasis>The <filename>README</filename>
826 file:</emphasis>
827 A file describing the contents of your new layer.
828 </para></listitem>
829 </itemizedlist>
830 </para>
831
832 <para>
833 If you choose to generate a sample recipe file, the script
834 prompts you for the name for the recipe and then creates it
835 in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
836 The script creates a <filename>.bb</filename> file and a
837 directory, which contains a sample
838 <filename>helloworld.c</filename> source file, along with
839 a sample patch file.
840 If you do not provide a recipe name, the script uses
841 "example".
842 </para>
843
844 <para>
845 If you choose to generate a sample append file, the script
846 prompts you for the name for the file and then creates it
847 in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
848 The script creates a <filename>.bbappend</filename> file and a
849 directory, which contains a sample patch file.
850 If you do not provide a recipe name, the script uses
851 "example".
852 The script also prompts you for the version of the append file.
853 The version should match the recipe to which the append file
854 is associated.
855 </para>
856
857 <para>
858 The easiest way to see how the <filename>yocto-layer</filename>
859 script works is to experiment with the script.
860 You can also read the usage information by entering the
861 following:
862 <literallayout class='monospaced'>
863 $ yocto-layer help
864 </literallayout>
865 </para>
866
867 <para>
868 Once you create your general layer, you must add it to your
869 <filename>bblayers.conf</filename> file.
870 Here is an example where a layer named
871 <filename>meta-mylayer</filename> is added:
872 <literallayout class='monospaced'>
873 BBLAYERS = ?" \
874 /usr/local/src/yocto/meta \
875 /usr/local/src/yocto/meta-yocto \
876 /usr/local/src/yocto/meta-yocto-bsp \
877 /usr/local/src/yocto/meta-mylayer \
878 "
879
880 BBLAYERS_NON_REMOVABLE ?= " \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 "
884 </literallayout>
885 Adding the layer to this file enables the build system to
886 locate the layer during the build.
887 </para>
888 </section>
889 </section>
890
891 <section id='usingpoky-extend-customimage'>
892 <title>Customizing Images</title>
893
894 <para>
895 You can customize images to satisfy particular requirements.
896 This section describes several methods and provides guidelines for each.
897 </para>
898
899 <section id='usingpoky-extend-customimage-localconf'>
900 <title>Customizing Images Using <filename>local.conf</filename></title>
901
902 <para>
903 Probably the easiest way to customize an image is to add a
904 package by way of the <filename>local.conf</filename>
905 configuration file.
906 Because it is limited to local use, this method generally only
907 allows you to add packages and is not as flexible as creating
908 your own customized image.
909 When you add packages using local variables this way, you need
910 to realize that these variable changes are in effect for every
911 build and consequently affect all images, which might not
912 be what you require.
913 </para>
914
915 <para>
916 To add a package to your image using the local configuration
917 file, use the
918 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
919 variable with the <filename>_append</filename> operator:
920 <literallayout class='monospaced'>
921 IMAGE_INSTALL_append = " strace"
922 </literallayout>
923 Use of the syntax is important - specifically, the space between
924 the quote and the package name, which is
925 <filename>strace</filename> in this example.
926 This space is required since the <filename>_append</filename>
927 operator does not add the space.
928 </para>
929
930 <para>
931 Furthermore, you must use <filename>_append</filename> instead
932 of the <filename>+=</filename> operator if you want to avoid
933 ordering issues.
934 The reason for this is because doing so unconditionally appends
935 to the variable and avoids ordering problems due to the
936 variable being set in image recipes and
937 <filename>.bbclass</filename> files with operators like
938 <filename>?=</filename>.
939 Using <filename>_append</filename> ensures the operation takes
940 affect.
941 </para>
942
943 <para>
944 As shown in its simplest use,
945 <filename>IMAGE_INSTALL_append</filename> affects all images.
946 It is possible to extend the syntax so that the variable
947 applies to a specific image only.
948 Here is an example:
949 <literallayout class='monospaced'>
950 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
951 </literallayout>
952 This example adds <filename>strace</filename> to the
953 <filename>core-image-minimal</filename> image only.
954 </para>
955
956 <para>
957 You can add packages using a similar approach through the
958 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
959 variable.
960 If you use this variable, only
961 <filename>core-image-*</filename> images are affected.
962 </para>
963 </section>
964
965 <section id='usingpoky-extend-customimage-imagefeatures'>
966 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
967 <filename>EXTRA_IMAGE_FEATURES</filename></title>
968
969 <para>
970 Another method for customizing your image is to enable or
971 disable high-level image features by using the
972 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
973 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
974 variables.
975 Although the functions for both variables are nearly equivalent,
976 best practices dictate using <filename>IMAGE_FEATURES</filename>
977 from within a recipe and using
978 <filename>EXTRA_IMAGE_FEATURES</filename> from within
979 your <filename>local.conf</filename> file, which is found in the
980 <link linkend='build-directory'>Build Directory</link>.
981 </para>
982
983 <para>
984 To understand how these features work, the best reference is
985 <filename>meta/classes/core-image.bbclass</filename>.
986 In summary, the file looks at the contents of the
987 <filename>IMAGE_FEATURES</filename> variable and then maps
988 those contents into a set of package groups.
989 Based on this information, the build system automatically
990 adds the appropriate packages to the
991 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
992 variable.
993 Effectively, you are enabling extra features by extending the
994 class or creating a custom class for use with specialized image
995 <filename>.bb</filename> files.
996 </para>
997
998 <para>
999 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1000 from within your local configuration file.
1001 Using a separate area from which to enable features with
1002 this variable helps you avoid overwriting the features in the
1003 image recipe that are enabled with
1004 <filename>IMAGE_FEATURES</filename>.
1005 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1006 to <filename>IMAGE_FEATURES</filename> within
1007 <filename>meta/conf/bitbake.conf</filename>.
1008 </para>
1009
1010 <para>
1011 To illustrate how you can use these variables to modify your
1012 image, consider an example that selects the SSH server.
1013 The Yocto Project ships with two SSH servers you can use
1014 with your images: Dropbear and OpenSSH.
1015 Dropbear is a minimal SSH server appropriate for
1016 resource-constrained environments, while OpenSSH is a
1017 well-known standard SSH server implementation.
1018 By default, the <filename>core-image-sato</filename> image
1019 is configured to use Dropbear.
1020 The <filename>core-image-full-cmdline</filename> and
1021 <filename>core-image-lsb</filename> images both
1022 include OpenSSH.
1023 The <filename>core-image-minimal</filename> image does not
1024 contain an SSH server.
1025 </para>
1026
1027 <para>
1028 You can customize your image and change these defaults.
1029 Edit the <filename>IMAGE_FEATURES</filename> variable
1030 in your recipe or use the
1031 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1032 <filename>local.conf</filename> file so that it configures the
1033 image you are working with to include
1034 <filename>ssh-server-dropbear</filename> or
1035 <filename>ssh-server-openssh</filename>.
1036 </para>
1037
1038 <note>
1039 See the
1040 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1041 section in the Yocto Project Reference Manual for a complete
1042 list of image features that ship with the Yocto Project.
1043 </note>
1044 </section>
1045
1046 <section id='usingpoky-extend-customimage-custombb'>
1047 <title>Customizing Images Using Custom .bb Files</title>
1048
1049 <para>
1050 You can also customize an image by creating a custom recipe
1051 that defines additional software as part of the image.
1052 The following example shows the form for the two lines you need:
1053 <literallayout class='monospaced'>
1054 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1055
1056 inherit core-image
1057 </literallayout>
1058 </para>
1059
1060 <para>
1061 Defining the software using a custom recipe gives you total
1062 control over the contents of the image.
1063 It is important to use the correct names of packages in the
1064 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1065 variable.
1066 You must use the OpenEmbedded notation and not the Debian notation for the names
1067 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
1068 </para>
1069
1070 <para>
1071 The other method for creating a custom image is to base it on an existing image.
1072 For example, if you want to create an image based on <filename>core-image-sato</filename>
1073 but add the additional package <filename>strace</filename> to the image,
1074 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1075 new <filename>.bb</filename> and add the following line to the end of the copy:
1076 <literallayout class='monospaced'>
1077 IMAGE_INSTALL += "strace"
1078 </literallayout>
1079 </para>
1080 </section>
1081
1082 <section id='usingpoky-extend-customimage-customtasks'>
1083 <title>Customizing Images Using Custom Package Groups</title>
1084
1085 <para>
1086 For complex custom images, the best approach for customizing
1087 an image is to create a custom package group recipe that is
1088 used to build the image or images.
1089 A good example of a package group recipe is
1090 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1091 The
1092 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1093 variable lists the package group packages you wish to produce.
1094 <filename>inherit packagegroup</filename> sets appropriate
1095 default values and automatically adds <filename>-dev</filename>,
1096 <filename>-dbg</filename>, and <filename>-ptest</filename>
1097 complementary packages for every package specified in
1098 <filename>PACKAGES</filename>.
1099 Note that the inherit line should be towards
1100 the top of the recipe, certainly before you set
1101 <filename>PACKAGES</filename>.
1102 For each package you specify in <filename>PACKAGES</filename>,
1103 you can use
1104 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1105 and
1106 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1107 entries to provide a list of packages the parent task package
1108 should contain.
1109 Following is an example:
1110 <literallayout class='monospaced'>
1111 DESCRIPTION = "My Custom Package Groups"
1112
1113 inherit packagegroup
1114
1115 PACKAGES = "\
1116 packagegroup-custom-apps \
1117 packagegroup-custom-tools \
1118 "
1119
1120 RDEPENDS_packagegroup-custom-apps = "\
1121 dropbear \
1122 portmap \
1123 psplash"
1124
1125 RDEPENDS_packagegroup-custom-tools = "\
1126 oprofile \
1127 oprofileui-server \
1128 lttng-control \
1129 lttng-viewer"
1130
1131 RRECOMMENDS_packagegroup-custom-tools = "\
1132 kernel-module-oprofile"
1133 </literallayout>
1134 </para>
1135
1136 <para>
1137 In the previous example, two package group packages are created with their dependencies and their
1138 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1139 <filename>packagegroup-custom-tools</filename>.
1140 To build an image using these package group packages, you need to add
1141 <filename>packagegroup-custom-apps</filename> and/or
1142 <filename>packagegroup-custom-tools</filename> to
1143 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1144 For other forms of image dependencies see the other areas of this section.
1145 </para>
1146 </section>
1147 </section>
1148
1149 <section id='new-recipe-writing-a-new-recipe'>
1150 <title>Writing a New Recipe</title>
1151
1152 <para>
1153 Recipes (<filename>.bb</filename> files) are fundamental components
1154 in the Yocto Project environment.
1155 Each software component built by the OpenEmbedded build system
1156 requires a recipe to define the component.
1157 This section describes how to create, write, and test a new
1158 recipe.
1159 <note>
1160 For information on variables that are useful for recipes and
1161 for information about recipe naming issues, see the
1162 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1163 section of the Yocto Project Reference Manual.
1164 </note>
1165 </para>
1166
1167 <section id='new-recipe-overview'>
1168 <title>Overview</title>
1169
1170 <para>
1171 The following figure shows the basic process for creating a
1172 new recipe.
1173 The remainder of the section provides details for the steps.
1174 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1175 </para>
1176 </section>
1177
1178 <section id='new-recipe-locate-a-base-recipe'>
1179 <title>Locate a Base Recipe</title>
1180
1181 <para>
1182 Before writing a recipe from scratch, it is often useful to
1183 discover whether someone else has already written one that
1184 meets (or comes close to meeting) your needs.
1185 The Yocto Project and OpenEmbedded communities maintain many
1186 recipes that might be candidates for what you are doing.
1187 You can find a good central index of these recipes in the
1188 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1189 </para>
1190
1191 <para>
1192 Working from an existing recipe or a skeleton recipe is the
1193 best way to get started.
1194 Here are some points on both methods:
1195 <itemizedlist>
1196 <listitem><para><emphasis>Locate and modify a recipe that
1197 is close to what you want to do:</emphasis>
1198 This method works when you are familiar with the
1199 current recipe space.
1200 The method does not work so well for those new to
1201 the Yocto Project or writing recipes.</para>
1202 <para>Some risks associated with this method are
1203 using a recipe that has areas totally unrelated to
1204 what you are trying to accomplish with your recipe,
1205 not recognizing areas of the recipe that you might
1206 have to add from scratch, and so forth.
1207 All these risks stem from unfamiliarity with the
1208 existing recipe space.</para></listitem>
1209 <listitem><para><emphasis>Use and modify the following
1210 skeleton recipe:</emphasis>
1211 <literallayout class='monospaced'>
1212 SUMMARY = ""
1213 HOMEPAGE = ""
1214 LICENSE = ""
1215
1216 LIC_FILES_CHKSUM = ""
1217
1218 SRC_URI = ""
1219 SRC_URI[md5sum] = ""
1220 SRC_URI[sha256sum] = ""
1221
1222 S = "${WORKDIR}/${PN}-${PV}"
1223
1224 inherit &lt;stuff&gt;
1225 </literallayout>
1226 Modifying this recipe is the recommended method for
1227 creating a new recipe.
1228 The recipe provides the fundamental areas that you need
1229 to include, exclude, or alter to fit your needs.
1230 </para></listitem>
1231 </itemizedlist>
1232 </para>
1233 </section>
1234
1235 <section id='new-recipe-storing-and-naming-the-recipe'>
1236 <title>Storing and Naming the Recipe</title>
1237
1238 <para>
1239 Once you have your base recipe, you should put it in your
1240 own layer and name it appropriately.
1241 Locating it correctly ensures that the OpenEmbedded build
1242 system can find it when you use BitBake to process the
1243 recipe.
1244 </para>
1245
1246 <itemizedlist>
1247 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1248 The OpenEmbedded build system locates your recipe
1249 through the layer's <filename>conf/layer.conf</filename>
1250 file and the
1251 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1252 variable.
1253 This variable sets up a path from which the build system can
1254 locate recipes.
1255 Here is the typical use:
1256 <literallayout class='monospaced'>
1257 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1258 ${LAYERDIR}/recipes-*/*/*.bbappend"
1259 </literallayout>
1260 Consequently, you need to be sure you locate your new recipe
1261 inside your layer such that it can be found.</para>
1262 <para>You can find more information on how layers are
1263 structured in the
1264 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1265 section.</para></listitem>
1266 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1267 When you name your recipe, you need to follow this naming
1268 convention:
1269 <literallayout class='monospaced'>
1270 &lt;basename&gt;_&lt;version&gt;.bb
1271 </literallayout>
1272 Use lower-cased characters and do not include the reserved
1273 suffixes <filename>-native</filename>,
1274 <filename>-cross</filename>, <filename>-initial</filename>,
1275 or <filename>-dev</filename> casually (i.e. do not use them
1276 as part of your recipe name unless the string applies).
1277 Here are some examples:
1278 <literallayout class='monospaced'>
1279 cups_1.7.0.bb
1280 gawk_4.0.2.bb
1281 xdg-utils_1.1.0-rc1.bb
1282 </literallayout></para></listitem>
1283 </itemizedlist>
1284 </section>
1285
1286 <section id='new-recipe-running-a-build-on-the-recipe'>
1287 <title>Running a Build on the Recipe</title>
1288
1289 <para>
1290 Creating a new recipe is usually an iterative process that
1291 requires using BitBake to process the recipe multiple times in
1292 order to progressively discover and add information to the
1293 recipe.
1294 </para>
1295
1296 <para>
1297 Assuming you have sourced a build environment setup script (i.e.
1298 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1299 or
1300 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1301 and you are in the
1302 <link linkend='build-directory'>Build Directory</link>,
1303 use BitBake to process your recipe.
1304 All you need to provide is the
1305 <filename>&lt;basename&gt;</filename> of the recipe as described
1306 in the previous section:
1307 <literallayout class='monospaced'>
1308 $ bitbake &lt;basename&gt;
1309 </literallayout>
1310
1311 </para>
1312
1313 <para>
1314 During the build, the OpenEmbedded build system creates a
1315 temporary work directory for the recipe
1316 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1317 where it keeps extracted source files, log files, intermediate
1318 compilation and packaging files, and so forth.
1319 </para>
1320
1321 <para>
1322 The temporary work directory is constructed as follows and
1323 depends on several factors:
1324 <literallayout class='monospaced'>
1325 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1326 </literallayout>
1327 As an example, assume a Source Directory top-level folder named
1328 <filename>poky</filename>, a default Build Directory at
1329 <filename>poky/build</filename>, and a
1330 <filename>qemux86-poky-linux</filename> machine target system.
1331 Furthermore, suppose your recipe is named
1332 <filename>foo_1.3.0-r0.bb</filename>.
1333 In this case, the work directory the build system uses to
1334 build the package would be as follows:
1335 <literallayout class='monospaced'>
1336 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1337 </literallayout>
1338 Inside this directory you can find sub-directories such as
1339 <filename>image</filename>, <filename>packages-split</filename>,
1340 and <filename>temp</filename>.
1341 After the build, you can examine these to determine how well
1342 the build went.
1343 <note>
1344 You can find log files for each task in the recipe's
1345 <filename>temp</filename> directory (e.g.
1346 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1347 Log files are named <filename>log.&lt;taskname&gt;</filename>
1348 (e.g. <filename>log.do_configure</filename>,
1349 <filename>log.do_fetch</filename>, and
1350 <filename>log.do_compile</filename>).
1351 </note>
1352 </para>
1353
1354 <para>
1355 You can find more information about the build process in the
1356 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1357 chapter of the Yocto Project Reference Manual.
1358 </para>
1359
1360 <para>
1361 You can also reference the following variables in the
1362 Yocto Project Reference Manual's glossary for more information:
1363 <itemizedlist>
1364 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1365 The top-level build output directory</listitem>
1366 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1367 The target system identifier</listitem>
1368 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1369 The recipe name</listitem>
1370 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1371 The epoch - (if
1372 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1373 is not specified, which is usually the case for most
1374 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1375 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1376 The recipe version</listitem>
1377 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1378 The recipe revision</listitem>
1379 </itemizedlist>
1380 </para>
1381 </section>
1382
1383 <section id='new-recipe-fetching-code'>
1384 <title>Fetching Code</title>
1385
1386 <para>
1387 The first thing your recipe must do is specify how to fetch
1388 the source files.
1389 Fetching is controlled mainly through the
1390 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1391 variable.
1392 Your recipe must have a <filename>SRC_URI</filename> variable
1393 that points to where the source is located.
1394 For a graphical representation of source locations, see the
1395 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1396 section in the Yocto Project Reference Manual.
1397 </para>
1398
1399 <para>
1400 The <filename>do_fetch</filename> task uses the prefix of
1401 each entry in the <filename>SRC_URI</filename> variable value
1402 to determine what fetcher to use to get your source files.
1403 It is the <filename>SRC_URI</filename> variable that triggers
1404 the fetcher.
1405 The <filename>do_patch</filename> task uses the variable after
1406 source is fetched to apply patches.
1407 The OpenEmbedded build system uses
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1409 for scanning directory locations for local files in
1410 <filename>SRC_URI</filename>.
1411 </para>
1412
1413 <para>
1414 The <filename>SRC_URI</filename> variable in your recipe must
1415 define each unique location for your source files.
1416 It is good practice to not hard-code pathnames in an URL used
1417 in <filename>SRC_URI</filename>.
1418 Rather than hard-code these paths, use
1419 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1420 which causes the fetch process to use the version specified in
1421 the recipe filename.
1422 Specifying the version in this manner means that upgrading the
1423 recipe to a future version is as simple as renaming the recipe
1424 to match the new version.
1425 </para>
1426
1427 <para>
1428 Here is a simple example from the
1429 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
1430 recipe where the source comes from a single tarball.
1431 Notice the use of the
1432 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1433 variable:
1434 <literallayout class='monospaced'>
1435 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1436 </literallayout>
1437 </para>
1438
1439 <para>
1440 Files mentioned in <filename>SRC_URI</filename> whose names end
1441 in a typical archive extension (e.g. <filename>.tar</filename>,
1442 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1443 <filename>.zip</filename>, and so forth), are automatically
1444 extracted during the <filename>do_unpack</filename> task.
1445 For another example that specifies these types of files, see
1446 the
1447 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1448 section.
1449 </para>
1450
1451 <para>
1452 Another way of specifying source is from an SCM.
1453 For Git repositories, you must specify
1454 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1455 and you should specify
1456 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1457 to include the revision with
1458 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1459 Here is an example from the recipe
1460 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1461 <literallayout class='monospaced'>
1462 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1463
1464 PR = "r6"
1465 PV = "1.0.5+git${SRCPV}"
1466
1467 SRC_URI = "git://git.kernel.dk/blktrace.git \
1468 file://ldflags.patch"
1469 </literallayout>
1470 </para>
1471
1472 <para>
1473 If your <filename>SRC_URI</filename> statement includes
1474 URLs pointing to individual files fetched from a remote server
1475 other than a version control system, BitBake attempts to
1476 verify the files against checksums defined in your recipe to
1477 ensure they have not been tampered with or otherwise modified
1478 since the recipe was written.
1479 Two checksums are used:
1480 <filename>SRC_URI[md5sum]</filename> and
1481 <filename>SRC_URI[sha256sum]</filename>.
1482 </para>
1483
1484 <para>
1485 If your <filename>SRC_URI</filename> variable points to
1486 more than a single URL (excluding SCM URLs), you need to
1487 provide the <filename>md5</filename> and
1488 <filename>sha256</filename> checksums for each URL.
1489 For these cases, you provide a name for each URL as part of
1490 the <filename>SRC_URI</filename> and then reference that name
1491 in the subsequent checksum statements.
1492 Here is an example:
1493 <literallayout class='monospaced'>
1494 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1495 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1496
1497 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1498 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1499
1500 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1501 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1502 </literallayout>
1503 </para>
1504
1505 <para>
1506 To find these checksums, you can comment the statements out
1507 and then attempt to build the software.
1508 The build will produce an error for each missing checksum
1509 and as part of the error message provide the correct checksum
1510 string.
1511 Once you have the correct checksums, simply copy them into your
1512 recipe for a subsequent build.
1513 </para>
1514
1515 <para>
1516 This final example is a bit more complicated and is from the
1517 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1518 recipe.
1519 The example's <filename>SRC_URI</filename> statement identifies
1520 multiple files as the source files for the recipe: a tarball, a
1521 patch file, a desktop file, and an icon.
1522 <literallayout class='monospaced'>
1523 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1524 file://xwc.patch \
1525 file://rxvt.desktop \
1526 file://rxvt.png"
1527 </literallayout>
1528 </para>
1529
1530 <para>
1531 When you specify local files using the
1532 <filename>file://</filename> URI protocol, the build system
1533 fetches files from the local machine.
1534 The path is relative to the
1535 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1536 variable and searches specific directories in a certain order:
1537 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1538 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1539 and <filename>files</filename>.
1540 The directories are assumed to be subdirectories of the
1541 directory in which the recipe or append file resides.
1542 For another example that specifies these types of files, see the
1543 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1544 section.
1545 </para>
1546
1547 <para>
1548 The previous example also specifies a patch file.
1549 Patch files are files whose names end in
1550 <filename>.patch</filename> or <filename>.diff</filename>.
1551 The build system automatically applies patches as described
1552 in the
1553 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1554 </para>
1555 </section>
1556
1557 <section id='new-recipe-unpacking-code'>
1558 <title>Unpacking Code</title>
1559
1560 <para>
1561 During the build, the <filename>do_unpack</filename> task
1562 unpacks the source with
1563 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1564 pointing to where it is unpacked.
1565 </para>
1566
1567 <para>
1568 If you are fetching your source files from an upstream source
1569 archived tarball and the tarball's internal structure matches
1570 the common convention of a top-level subdirectory named
1571 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1572 then you do not need to set <filename>S</filename>.
1573 However, if <filename>SRC_URI</filename> specifies to fetch
1574 source from an archive that does not use this convention,
1575 or from an SCM like Git or Subversion, your recipe needs to
1576 define <filename>S</filename>.
1577 </para>
1578
1579 <para>
1580 If processing your recipe using BitBake successfully unpacks
1581 the source files, you need to be sure that the directory
1582 pointed to by <filename>${S}</filename> matches the structure
1583 of the source.
1584 </para>
1585 </section>
1586
1587 <section id='new-recipe-patching-code'>
1588 <title>Patching Code</title>
1589
1590 <para>
1591 Sometimes it is necessary to patch code after it has been
1592 fetched.
1593 Any files mentioned in <filename>SRC_URI</filename> whose
1594 names end in <filename>.patch</filename> or
1595 <filename>.diff</filename> are treated as patches.
1596 The <filename>do_patch</filename> task automatically applies
1597 these patches.
1598 </para>
1599
1600 <para>
1601 The build system should be able to apply patches with the "-p1"
1602 option (i.e. one directory level in the path will be stripped
1603 off).
1604 If your patch needs to have more directory levels stripped off,
1605 specify the number of levels using the "striplevel" option in
1606 the <filename>SRC_URI</filename> entry for the patch.
1607 Alternatively, if your patch needs to be applied in a specific
1608 subdirectory that is not specified in the patch file, use the
1609 "patchdir" option in the entry.
1610 </para>
1611 </section>
1612
1613 <section id='new-recipe-licensing'>
1614 <title>Licensing</title>
1615
1616 <para>
1617 Your recipe needs to have both the
1618 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1619 and
1620 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1621 variables:
1622 <itemizedlist>
1623 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1624 This variable specifies the license for the software.
1625 If you do not know the license under which the software
1626 you are building is distributed, you should go to the
1627 source code and look for that information.
1628 Typical files containing this information include
1629 <filename>COPYING</filename>,
1630 <filename>LICENSE</filename>, and
1631 <filename>README</filename> files.
1632 You could also find the information near the top of
1633 a source file.
1634 For example, given a piece of software licensed under
1635 the GNU General Public License version 2, you would
1636 set <filename>LICENSE</filename> as follows:
1637 <literallayout class='monospaced'>
1638 LICENSE = "GPLv2"
1639 </literallayout></para>
1640 <para>The licenses you specify within
1641 <filename>LICENSE</filename> can have any name as long
1642 as you do not use spaces, since spaces are used as
1643 separators between license names.
1644 For standard licenses, use the names of the files in
1645 <filename>meta/files/common-licenses/</filename>
1646 or the <filename>SPDXLICENSEMAP</filename> flag names
1647 defined in <filename>meta/conf/licenses.conf</filename>.
1648 </para></listitem>
1649 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1650 The OpenEmbedded build system uses this variable to
1651 make sure the license text has not changed.
1652 If it has, the build produces an error and it affords
1653 you the chance to figure it out and correct the problem.
1654 </para>
1655 <para>You need to specify all applicable licensing
1656 files for the software.
1657 At the end of the configuration step, the build process
1658 will compare the checksums of the files to be sure
1659 the text has not changed.
1660 Any differences result in an error with the message
1661 containing the current checksum.
1662 For more explanation and examples of how to set the
1663 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1664 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1665 section in the Yocto Project Reference Manual.</para>
1666 <para>To determine the correct checksum string, you
1667 can list the appropriate files in the
1668 <filename>LIC_FILES_CHKSUM</filename> variable with
1669 incorrect md5 strings, attempt to build the software,
1670 and then note the resulting error messages that will
1671 report the correct md5 strings.
1672 Here is an example that assumes the software has a
1673 <filename>COPYING</filename> file:
1674 <literallayout class='monospaced'>
1675 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
1676 </literallayout>
1677 When you try to build the software, the build system
1678 will produce an error and give you the correct string
1679 that you can substitute into the recipe file for a
1680 subsequent build.
1681 </para></listitem>
1682 </itemizedlist>
1683 </para>
1684
1685<!--
1686
1687 <para>
1688 For trying this out I created a new recipe named
1689 <filename>htop_1.0.2.bb</filename> and put it in
1690 <filename>poky/meta/recipes-extended/htop</filename>.
1691 There are two license type statements in my very simple
1692 recipe:
1693 <literallayout class='monospaced'>
1694 LICENSE = ""
1695
1696 LIC_FILES_CHKSUM = ""
1697
1698 SRC_URI[md5sum] = ""
1699 SRC_URI[sha256sum] = ""
1700 </literallayout>
1701 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
1702 Next, you delete or comment out the two <filename>SRC_URI</filename>
1703 lines at the end and then attempt to build the software with
1704 <filename>bitbake htop</filename>.
1705 Doing so causes BitBake to report some errors and and give
1706 you the actual strings you need for the last two
1707 <filename>SRC_URI</filename> lines.
1708 Prior to this, you have to dig around in the home page of the
1709 source for <filename>htop</filename> and determine that the
1710 software is released under GPLv2.
1711 You can provide that in the <filename>LICENSE</filename>
1712 statement.
1713 Now you edit your recipe to have those two strings for
1714 the <filename>SRC_URI</filename> statements:
1715 <literallayout class='monospaced'>
1716 LICENSE = "GPLv2"
1717
1718 LIC_FILES_CHKSUM = ""
1719
1720 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
1721 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
1722 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
1723 </literallayout>
1724 At this point, you can build the software again using the
1725 <filename>bitbake htop</filename> command.
1726 There is just a set of errors now associated with the
1727 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
1728 </para>
1729-->
1730
1731 </section>
1732
1733 <section id='new-recipe-configuring-the-recipe'>
1734 <title>Configuring the Recipe</title>
1735
1736 <para>
1737 Most software provides some means of setting build-time
1738 configuration options before compilation.
1739 Typically, setting these options is accomplished by running a
1740 configure script with some options, or by modifying a build
1741 configuration file.
1742 </para>
1743
1744 <para>
1745 A major part of build-time configuration is about checking for
1746 build-time dependencies and possibly enabling optional
1747 functionality as a result.
1748 You need to specify any build-time dependencies for the
1749 software you are building in your recipe's
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1751 value, in terms of other recipes that satisfy those
1752 dependencies.
1753 You can often find build-time or runtime
1754 dependencies described in the software's documentation.
1755 </para>
1756
1757 <para>
1758 The following list provides configuration items of note based
1759 on how your software is built:
1760 <itemizedlist>
1761 <listitem><para><emphasis>Autotools:</emphasis>
1762 If your source files have a
1763 <filename>configure.ac</filename> file, then your
1764 software is built using Autotools.
1765 If this is the case, you just need to worry about
1766 tweaking the configuration.</para>
1767 <para>When using Autotools, your recipe needs to inherit
1768 the
1769 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1770 class and your recipe does not have to contain a
1771 <filename>do_configure</filename> task.
1772 However, you might still want to make some adjustments.
1773 For example, you can set
1774 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1775 to pass any needed configure options that are specific
1776 to the recipe.</para></listitem>
1777 <listitem><para><emphasis>CMake:</emphasis>
1778 If your source files have a
1779 <filename>CMakeLists.txt</filename> file, then your
1780 software is built using CMake.
1781 If this is the case, you just need to worry about
1782 tweaking the configuration.</para>
1783 <para>When you use CMake, your recipe needs to inherit
1784 the
1785 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
1786 class and your recipe does not have to contain a
1787 <filename>do_configure</filename> task.
1788 You can make some adjustments by setting
1789 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1790 to pass any needed configure options that are specific
1791 to the recipe.</para></listitem>
1792 <listitem><para><emphasis>Other:</emphasis>
1793 If your source files do not have a
1794 <filename>configure.ac</filename> or
1795 <filename>CMakeLists.txt</filename> file, then your
1796 software is built using some method other than Autotools
1797 or CMake.
1798 If this is the case, you normally need to provide a
1799 <filename>do_configure</filename> task in your recipe
1800 unless, of course, there is nothing to configure.
1801 </para>
1802 <para>Even if your software is not being built by
1803 Autotools or CMake, you still might not need to deal
1804 with any configuration issues.
1805 You need to determine if configuration is even a required step.
1806 You might need to modify a Makefile or some configuration file
1807 used for the build to specify necessary build options.
1808 Or, perhaps you might need to run a provided, custom
1809 configure script with the appropriate options.</para>
1810 <para>For the case involving a custom configure
1811 script, you would run
1812 <filename>./configure --help</filename> and look for
1813 the options you need to set.</para></listitem>
1814 </itemizedlist>
1815 </para>
1816
1817 <para>
1818 Once configuration succeeds, it is always good practice to
1819 look at the <filename>log.do_configure</filename> file to
1820 ensure that the appropriate options have been enabled and no
1821 additional build-time dependencies need to be added to
1822 <filename>DEPENDS</filename>.
1823 For example, if the configure script reports that it found
1824 something not mentioned in <filename>DEPENDS</filename>, or
1825 that it did not find something that it needed for some
1826 desired optional functionality, then you would need to add
1827 those to <filename>DEPENDS</filename>.
1828 Looking at the log might also reveal items being checked for
1829 and/or enabled that you do not want, or items not being found
1830 that are in <filename>DEPENDS</filename>, in which case
1831 you would need to look at passing extra options to the
1832 configure script as needed.
1833 For reference information on configure options specific to the
1834 software you are building, you can consult the output of the
1835 <filename>./configure --help</filename> command within
1836 <filename>${S}</filename> or consult the software's upstream
1837 documentation.
1838 </para>
1839 </section>
1840
1841 <section id='new-recipe-compilation'>
1842 <title>Compilation</title>
1843
1844 <para>
1845 During a build, the <filename>do_compile</filename> task
1846 happens after source is fetched, unpacked, and configured.
1847 If the recipe passes through <filename>do_compile</filename>
1848 successfully, nothing needs to be done.
1849 </para>
1850
1851 <para>
1852 However, if the compile step fails, you need to diagnose the
1853 failure.
1854 Here are some common issues that cause failures:
1855 <itemizedlist>
1856 <listitem><para><emphasis>Parallel build failures:</emphasis>
1857 These failures manifest themselves as intermittent
1858 errors, or errors reporting that a file or directory
1859 that should be created by some other part of the build
1860 process could not be found.
1861 This type of failure can occur even if, upon inspection,
1862 the file or directory does exist after the build has
1863 failed, because that part of the build process happened
1864 in the wrong order.</para>
1865 <para>To fix the problem, you need to either satisfy
1866 the missing dependency in the Makefile or whatever
1867 script produced the Makefile, or (as a workaround)
1868 set
1869 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
1870 to an empty string:
1871 <literallayout class='monospaced'>
1872 PARALLEL_MAKE = ""
1873 </literallayout></para></listitem>
1874 <listitem><para><emphasis>Improper host path usage:</emphasis>
1875 This failure applies to recipes building for the target
1876 or <filename>nativesdk</filename> only.
1877 The failure occurs when the compilation process uses
1878 improper headers, libraries, or other files from the
1879 host system when cross-compiling for the target.
1880 </para>
1881 <para>To fix the problem, examine the
1882 <filename>log.do_compile</filename> file to identify
1883 the host paths being used (e.g.
1884 <filename>/usr/include</filename>,
1885 <filename>/usr/lib</filename>, and so forth) and then
1886 either add configure options, apply a patch, or do both.
1887 </para></listitem>
1888 <listitem><para><emphasis>Failure to find required
1889 libraries/headers:</emphasis>
1890 If a build-time dependency is missing because it has
1891 not been declared in
1892 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
1893 or because the dependency exists but the path used by
1894 the build process to find the file is incorrect and the
1895 configure step did not detect it, the compilation
1896 process could fail.
1897 For either of these failures, the compilation process
1898 notes that files could not be found.
1899 In these cases, you need to go back and add additional
1900 options to the configure script as well as possibly
1901 add additional build-time dependencies to
1902 <filename>DEPENDS</filename>.
1903 Occasionally, it is necessary to apply a patch to the
1904 source to ensure the correct paths are used.
1905 </para></listitem>
1906 </itemizedlist>
1907 </para>
1908 </section>
1909
1910 <section id='new-recipe-installing'>
1911 <title>Installing</title>
1912
1913 <para>
1914 During <filename>do_install</filename>, the task copies the
1915 built files along with their hierarchy to locations that
1916 would mirror their locations on the target device.
1917 The installation process copies files from the
1918 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
1919 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
1920 and
1921 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1922 directories to the
1923 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1924 directory to create the structure as it should appear on the
1925 target system.
1926 </para>
1927
1928 <para>
1929 How your software is built affects what you must do to be
1930 sure your software is installed correctly.
1931 The following list describes what you must do for installation
1932 depending on the type of build system used by the software
1933 being built:
1934 <itemizedlist>
1935 <listitem><para><emphasis>Autotools and CMake:</emphasis>
1936 If the software your recipe is building uses Autotools
1937 or CMake, the OpenEmbedded build
1938 system understands how to install the software.
1939 Consequently, you do not have to have a
1940 <filename>do_install</filename> task as part of your
1941 recipe.
1942 You just need to make sure the install portion of the
1943 build completes with no issues.
1944 However, if you wish to install additional files not
1945 already being installed by
1946 <filename>make install</filename>, you should do this
1947 using a <filename>do_install_append</filename> function
1948 using the install command as described in
1949 <emphasis>Manual</emphasis> later in this list.
1950 </para></listitem>
1951 <listitem><para><emphasis>Other (using
1952 <filename>make install</filename>):</emphasis>
1953 You need to define a
1954 <filename>do_install</filename> function in your
1955 recipe.
1956 The function should call
1957 <filename>oe_runmake install</filename> and will likely
1958 need to pass in the destination directory as well.
1959 How you pass that path is dependent on how the
1960 <filename>Makefile</filename> being run is written
1961 (e.g. <filename>DESTDIR=${D}</filename>,
1962 <filename>PREFIX=${D}</filename>,
1963 <filename>INSTALLROOT=${D}</filename>, and so forth).
1964 </para>
1965 <para>For an example recipe using
1966 <filename>make install</filename>, see the
1967 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
1968 section.</para></listitem>
1969 <listitem><para><emphasis>Manual:</emphasis>
1970 You need to define a
1971 <filename>do_install</filename> function in your
1972 recipe.
1973 The function must first use
1974 <filename>install -d</filename> to create the
1975 directories.
1976 Once the directories exist, your function can use
1977 <filename>install</filename> to manually install the
1978 built software into the directories.</para>
1979 <para>You can find more information on
1980 <filename>install</filename> at
1981 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
1982 </para></listitem>
1983 </itemizedlist>
1984 </para>
1985
1986 <para>
1987 For the scenarios that do not use Autotools or
1988 CMake, you need to track the installation
1989 and diagnose and fix any issues until everything installs
1990 correctly.
1991 You need to look in the default location of
1992 <filename>${D}</filename>, which is
1993 <filename>${WORKDIR}/image</filename>, to be sure your
1994 files have been installed correctly.
1995 </para>
1996
1997 <note>
1998 During the installation process, you might need to modify
1999 some of the installed files to suit the target layout.
2000 For example, you might need to replace hard-coded paths in an
2001 initscript with values of variables provided by the build
2002 system, such as replacing <filename>/usr/bin/</filename> with
2003 <filename>${bindir}</filename>.
2004 If you do perform such modifications during
2005 <filename>do_install</filename>, be sure to modify the
2006 destination file after copying rather than before copying.
2007 Modifying after copying ensures that the build system can
2008 re-execute <filename>do_install</filename> if needed.
2009 </note>
2010
2011 <note>
2012 <filename>oe_runmake install</filename>, which can be run
2013 directly or can be run indirectly by the
2014 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2015 and
2016 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2017 classes, runs <filename>make install</filename> in parallel.
2018 Sometimes, a Makefile can have missing dependencies between
2019 targets that can result in race conditions.
2020 If you experience intermittent failures during
2021 <filename>do_install</filename>, you might be able to work
2022 around them by disabling parallel Makefile installs
2023 by adding the following to the recipe:
2024 <literallayout class='monospaced'>
2025 PARALLEL_MAKEINST = ""
2026 </literallayout>
2027 See
2028 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2029 for additional information.
2030 </note>
2031 </section>
2032
2033 <section id='new-recipe-enabling-system-services'>
2034 <title>Enabling System Services</title>
2035
2036 <para>
2037 If you want to install a service, which is a process that
2038 usually starts on boot and runs in the background, then
2039 you must include some additional definitions in your recipe.
2040 </para>
2041
2042 <para>
2043 If you are adding services and the service initialization
2044 script or the service file itself is not installed, you must
2045 provide for that installation in your recipe using a
2046 <filename>do_install_append</filename> function.
2047 If your recipe already has a <filename>do_install</filename>
2048 function, update the function near its end rather than
2049 adding an additional <filename>do_install_append</filename>
2050 function.
2051 </para>
2052
2053 <para>
2054 When you create the installation for your services, you need
2055 to accomplish what is normally done by
2056 <filename>make install</filename>.
2057 In other words, make sure your installation arranges the output
2058 similar to how it is arranged on the target system.
2059 </para>
2060
2061 <para>
2062 The OpenEmbedded build system provides support for starting
2063 services two different ways:
2064 <itemizedlist>
2065 <listitem><para><emphasis>SysVinit:</emphasis>
2066 SysVinit is a system and service manager that
2067 manages the init system used to control the very basic
2068 functions of your system.
2069 The init program is the first program
2070 started by the Linux kernel when the system boots.
2071 Init then controls the startup, running and shutdown
2072 of all other programs.</para>
2073 <para>To enable a service using SysVinit, your recipe
2074 needs to inherit the
2075 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2076 class.
2077 The class helps facilitate safely installing the
2078 package on the target.</para>
2079 <para>You will need to set the
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2081 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2082 and
2083 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2084 variables within your recipe.</para></listitem>
2085 <listitem><para><emphasis>systemd:</emphasis>
2086 System Management Daemon (systemd) was designed to
2087 replace SysVinit and to provide
2088 enhanced management of services.
2089 For more information on systemd, see the systemd
2090 homepage at
2091 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2092 </para>
2093 <para>To enable a service using systemd, your recipe
2094 needs to inherit the
2095 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2096 class.
2097 See the <filename>systemd.class</filename> file
2098 located in your
2099 <link linkend='source-directory'>Source Directory</link>.
2100 section for more information.
2101 </para></listitem>
2102 </itemizedlist>
2103 </para>
2104 </section>
2105
2106 <section id='new-recipe-packaging'>
2107 <title>Packaging</title>
2108
2109 <para>
2110 The <filename>do_package</filename> task splits the files
2111 produced by the recipe into logical components.
2112 Even software that produces a single binary might still have
2113 debug symbols, documentation, and other logical components
2114 that should be split out.
2115 The <filename>do_package</filename> task ensures that files
2116 are split up and packaged correctly.
2117 </para>
2118
2119 <para>
2120 After you build your software, you need to be sure your packages
2121 are correct.
2122 Examine the
2123 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2124 directory and make sure files are where you expect them to be.
2125 </para>
2126
2127 <para>
2128 If you discover problems, you can set
2129 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2130 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2131 <filename>do_install(_append)</filename>, and so forth as
2132 needed.
2133 </para>
2134
2135 <para>
2136 See the
2137 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2138 section for an example that shows how you might split
2139 your software into more than one package.
2140 </para>
2141
2142 <para>
2143 For an example showing how to install a post-installation
2144 script, see the
2145 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2146 section.
2147 </para>
2148 </section>
2149
2150 <section id='new-recipe-post-installation-scripts'>
2151 <title>Post-Installation Scripts</title>
2152
2153 <para>
2154 Post-installation scripts run immediately after installing
2155 a package on the target, or during image creation when a
2156 package is included in an image.
2157 To add a post-installation script to a package, add a
2158 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2159 the recipe file (<filename>.bb</filename>) and use
2160 <filename>PACKAGENAME</filename> as the name of the package
2161 you want to attach to the <filename>postinst</filename>
2162 script.
2163 To apply the post-installation script to the main package
2164 for the recipe, which is usually what is required, specify
2165 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2166 in place of <filename>PACKAGENAME</filename>.
2167 </para>
2168
2169 <para>
2170 A post-installation function has the following structure:
2171 <literallayout class='monospaced'>
2172 pkg_postinst_PACKAGENAME () {
2173 #!/bin/sh -e
2174 # Commands to carry out
2175 }
2176 </literallayout>
2177 </para>
2178
2179 <para>
2180 The script defined in the post-installation function is
2181 called when the root filesystem is created.
2182 If the script succeeds, the package is marked as installed.
2183 If the script fails, the package is marked as unpacked and
2184 the script is executed when the image boots again.
2185 </para>
2186
2187 <para>
2188 Sometimes it is necessary for the execution of a
2189 post-installation script to be delayed until the first boot.
2190 For example, the script might need to be executed on the
2191 device itself.
2192 To delay script execution until boot time, use the following
2193 structure in the post-installation script:
2194 <literallayout class='monospaced'>
2195 pkg_postinst_PACKAGENAME () {
2196 #!/bin/sh -e
2197 if [ x"$D" = "x" ]; then
2198 # Actions to carry out on the device go here
2199 else
2200 exit 1
2201 fi
2202 }
2203 </literallayout>
2204 </para>
2205
2206 <para>
2207 The previous example delays execution until the image boots
2208 again because the
2209 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2210 variable points to the directory containing the image when
2211 the root filesystem is created at build time but is unset
2212 when executed on the first boot.
2213 </para>
2214
2215 <note>
2216 Equivalent support for pre-install, pre-uninstall, and
2217 post-uninstall scripts exist by way of
2218 <filename>pkg_preinst</filename>,
2219 <filename>pkg_prerm</filename>, and
2220 <filename>pkg_postrm</filename>, respectively.
2221 These scrips work in exactly the same way as does
2222 <filename>pkg_postinst</filename> with the exception that they
2223 run at different times.
2224 Also, because of when they run, they are not applicable to
2225 being run at image creation time like
2226 <filename>pkg_postinst</filename>.
2227 </note>
2228 </section>
2229
2230 <section id='new-recipe-testing'>
2231 <title>Testing</title>
2232
2233 <para>
2234 The final step for completing your recipe is to be sure that
2235 the software you built runs correctly.
2236 To accomplish runtime testing, add the build's output
2237 packages to your image and test them on the target.
2238 </para>
2239
2240 <para>
2241 For information on how to customize your image by adding
2242 specific packages, see the
2243 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2244 section.
2245 </para>
2246 </section>
2247
2248 <section id='new-recipe-testing-examples'>
2249 <title>Examples</title>
2250
2251 <para>
2252 To help summarize how to write a recipe, this section provides
2253 some examples given various scenarios:
2254 <itemizedlist>
2255 <listitem><para>Recipes that use local files</para></listitem>
2256 <listitem><para>Using an Autotooled package</para></listitem>
2257 <listitem><para>Using a Makefile-based package</para></listitem>
2258 <listitem><para>Splitting an application into multiple packages</para></listitem>
2259 </itemizedlist>
2260 </para>
2261
2262 <section id='new-recipe-single-c-file-package-hello-world'>
2263 <title>Single .c File Package (Hello World!)</title>
2264
2265 <para>
2266 Building an application from a single file that is stored
2267 locally (e.g. under <filename>files/</filename>) requires
2268 a recipe that has the file listed in the
2269 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2270 variable.
2271 Additionally, you need to manually write the
2272 <filename>do_compile</filename> and
2273 <filename>do_install</filename> tasks.
2274 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2275 variable defines the directory containing the source code,
2276 which is set to
2277 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2278 in this case - the directory BitBake uses for the build.
2279 <literallayout class='monospaced'>
2280 SUMMARY = "Simple helloworld application"
2281 SECTION = "examples"
2282 LICENSE = "MIT"
2283 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2284
2285 SRC_URI = "file://helloworld.c"
2286
2287 S = "${WORKDIR}"
2288
2289 do_compile() {
2290 ${CC} helloworld.c -o helloworld
2291 }
2292
2293 do_install() {
2294 install -d ${D}${bindir}
2295 install -m 0755 helloworld ${D}${bindir}
2296 }
2297 </literallayout>
2298 </para>
2299
2300 <para>
2301 By default, the <filename>helloworld</filename>,
2302 <filename>helloworld-dbg</filename>, and
2303 <filename>helloworld-dev</filename> packages are built.
2304 For information on how to customize the packaging process,
2305 see the
2306 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2307 section.
2308 </para>
2309 </section>
2310
2311 <section id='new-recipe-autotooled-package'>
2312 <title>Autotooled Package</title>
2313 <para>
2314 Applications that use Autotools such as <filename>autoconf</filename> and
2315 <filename>automake</filename> require a recipe that has a source archive listed in
2316 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2317 also inherit the
2318 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2319 class, which contains the definitions of all the steps
2320 needed to build an Autotool-based application.
2321 The result of the build is automatically packaged.
2322 And, if the application uses NLS for localization, packages with local information are
2323 generated (one package per language).
2324 Following is one example: (<filename>hello_2.3.bb</filename>)
2325 <literallayout class='monospaced'>
2326 SUMMARY = "GNU Helloworld application"
2327 SECTION = "examples"
2328 LICENSE = "GPLv2+"
2329 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2330
2331 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2332
2333 inherit autotools gettext
2334 </literallayout>
2335 </para>
2336
2337 <para>
2338 The variable
2339 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2340 is used to track source license changes as described in the
2341 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2342 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2343 </para>
2344 </section>
2345
2346 <section id='new-recipe-makefile-based-package'>
2347 <title>Makefile-Based Package</title>
2348
2349 <para>
2350 Applications that use GNU <filename>make</filename> also require a recipe that has
2351 the source archive listed in
2352 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2353 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2354 starts the <filename>make</filename> command to compile the application.
2355 If you need additional <filename>make</filename> options, you should store them in the
2356 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2357 variable.
2358 BitBake passes these options into the <filename>make</filename> GNU invocation.
2359 Note that a <filename>do_install</filename> task is still required.
2360 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2361 </para>
2362
2363 <para>
2364 Some applications might require extra parameters to be passed to the compiler.
2365 For example, the application might need an additional header path.
2366 You can accomplish this by adding to the
2367 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2368 The following example shows this:
2369 <literallayout class='monospaced'>
2370 CFLAGS_prepend = "-I ${S}/include "
2371 </literallayout>
2372 </para>
2373
2374 <para>
2375 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2376 <literallayout class='monospaced'>
2377 SUMMARY = "Tools for managing memory technology devices."
2378 SECTION = "base"
2379 DEPENDS = "zlib lzo e2fsprogs util-linux"
2380 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2381 LICENSE = "GPLv2+"
2382 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2383 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2384
2385 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2386 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2387
2388 S = "${WORKDIR}/git/"
2389
2390 PR = "r1"
2391
2392 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2393 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2394
2395 do_install () {
2396 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2397 INCLUDEDIR=${includedir}
2398 install -d ${D}${includedir}/mtd/
2399 for f in ${S}/include/mtd/*.h; do
2400 install -m 0644 $f ${D}${includedir}/mtd/
2401 done
2402 }
2403
2404 PARALLEL_MAKE = ""
2405
2406 BBCLASSEXTEND = "native"
2407 </literallayout>
2408 </para>
2409 </section>
2410
2411 <section id='splitting-an-application-into-multiple-packages'>
2412 <title>Splitting an Application into Multiple Packages</title>
2413
2414 <para>
2415 You can use the variables
2416 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2417 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2418 to split an application into multiple packages.
2419 </para>
2420
2421 <para>
2422 Following is an example that uses the <filename>libxpm</filename> recipe.
2423 By default, this recipe generates a single package that contains the library along
2424 with a few binaries.
2425 You can modify the recipe to split the binaries into separate packages:
2426 <literallayout class='monospaced'>
2427 require xorg-lib-common.inc
2428
2429 SUMMARY = "X11 Pixmap library"
2430 LICENSE = "X-BSD"
2431 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2432 DEPENDS += "libxext libsm libxt"
2433 PR = "r3"
2434 PE = "1"
2435
2436 XORG_PN = "libXpm"
2437
2438 PACKAGES =+ "sxpm cxpm"
2439 FILES_cxpm = "${bindir}/cxpm"
2440 FILES_sxpm = "${bindir}/sxpm"
2441 </literallayout>
2442 </para>
2443
2444 <para>
2445 In the previous example, we want to ship the <filename>sxpm</filename>
2446 and <filename>cxpm</filename> binaries in separate packages.
2447 Since <filename>bindir</filename> would be packaged into the main
2448 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2449 package by default, we prepend the <filename>PACKAGES</filename>
2450 variable so additional package names are added to the start of list.
2451 This results in the extra <filename>FILES_*</filename>
2452 variables then containing information that define which files and
2453 directories go into which packages.
2454 Files included by earlier packages are skipped by latter packages.
2455 Thus, the main <filename>PN</filename> package
2456 does not include the above listed files.
2457 </para>
2458 </section>
2459 </section>
2460 </section>
2461
2462 <section id="platdev-newmachine">
2463 <title>Adding a New Machine</title>
2464
2465 <para>
2466 Adding a new machine to the Yocto Project is a straight forward
2467 process.
2468 This section describes how to add machines that are similar
2469 to those that the Yocto Project already supports.
2470 <note>
2471 Although well within the capabilities of the Yocto Project,
2472 adding a totally new architecture might require
2473 changes to <filename>gcc/eglibc</filename> and to the site
2474 information, which is beyond the scope of this manual.
2475 </note>
2476 </para>
2477
2478 <para>
2479 For a complete example that shows how to add a new machine,
2480 see the
2481 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
2482 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
2483 </para>
2484
2485 <section id="platdev-newmachine-conffile">
2486 <title>Adding the Machine Configuration File</title>
2487
2488 <para>
2489 To add a new machine, you need to add a new machine
2490 configuration file to the layer's
2491 <filename>conf/machine</filename> directory.
2492 This configuration file provides details about the device
2493 you are adding.
2494 </para>
2495
2496 <para>
2497 The OpenEmbedded build system uses the root name of the
2498 machine configuration file to reference the new machine.
2499 For example, given a machine configuration file named
2500 <filename>crownbay.conf</filename>, the build system
2501 recognizes the machine as "crownbay".
2502 </para>
2503
2504 <para>
2505 The most important variables you must set in your machine
2506 configuration file are as follows:
2507 <itemizedlist>
2508 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
2509 (e.g. "arm")</para></listitem>
2510 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
2511 (see below)</para></listitem>
2512 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
2513 (e.g. "apm screen wifi")</para></listitem>
2514 </itemizedlist>
2515 </para>
2516
2517 <para>
2518 You might also need these variables:
2519 <itemizedlist>
2520 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
2521 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
2522 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
2523 (e.g. "zImage")</para></listitem>
2524 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
2525 (e.g. "tar.gz jffs2")</para></listitem>
2526 </itemizedlist>
2527 </para>
2528
2529 <para>
2530 You can find full details on these variables in the reference
2531 section.
2532 You can leverage existing machine <filename>.conf</filename>
2533 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
2534 </para>
2535 </section>
2536
2537 <section id="platdev-newmachine-kernel">
2538 <title>Adding a Kernel for the Machine</title>
2539
2540 <para>
2541 The OpenEmbedded build system needs to be able to build a kernel
2542 for the machine.
2543 You need to either create a new kernel recipe for this machine,
2544 or extend an existing kernel recipe.
2545 You can find several kernel recipe examples in the
2546 Source Directory at
2547 <filename>meta/recipes-kernel/linux</filename>
2548 that you can use as references.
2549 </para>
2550
2551 <para>
2552 If you are creating a new kernel recipe, normal recipe-writing
2553 rules apply for setting up a
2554 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2555 Thus, you need to specify any necessary patches and set
2556 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2557 to point at the source code.
2558 You need to create a <filename>do_configure</filename> task that
2559 configures the unpacked kernel with a
2560 <filename>defconfig</filename> file.
2561 You can do this by using a <filename>make defconfig</filename>
2562 command or, more commonly, by copying in a suitable
2563 <filename>defconfig</filename> file and then running
2564 <filename>make oldconfig</filename>.
2565 By making use of <filename>inherit kernel</filename> and
2566 potentially some of the <filename>linux-*.inc</filename> files,
2567 most other functionality is centralized and the defaults of the
2568 class normally work well.
2569 </para>
2570
2571 <para>
2572 If you are extending an existing kernel recipe, it is usually
2573 a matter of adding a suitable <filename>defconfig</filename>
2574 file.
2575 The file needs to be added into a location similar to
2576 <filename>defconfig</filename> files used for other machines
2577 in a given kernel recipe.
2578 A possible way to do this is by listing the file in the
2579 <filename>SRC_URI</filename> and adding the machine to the
2580 expression in
2581 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
2582 <literallayout class='monospaced'>
2583 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2584 </literallayout>
2585 </para>
2586 </section>
2587
2588 <section id="platdev-newmachine-formfactor">
2589 <title>Adding a Formfactor Configuration File</title>
2590
2591 <para>
2592 A formfactor configuration file provides information about the
2593 target hardware for which the image is being built and information that
2594 the build system cannot obtain from other sources such as the kernel.
2595 Some examples of information contained in a formfactor configuration file include
2596 framebuffer orientation, whether or not the system has a keyboard,
2597 the positioning of the keyboard in relation to the screen, and
2598 the screen resolution.
2599 </para>
2600
2601 <para>
2602 The build system uses reasonable defaults in most cases.
2603 However, if customization is
2604 necessary, you need to create a <filename>machconfig</filename> file
2605 in the <filename>meta/recipes-bsp/formfactor/files</filename>
2606 directory.
2607 This directory contains directories for specific machines such as
2608 <filename>qemuarm</filename> and <filename>qemux86</filename>.
2609 For information about the settings available and the defaults, see the
2610 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
2611 same area.
2612 </para>
2613
2614 <para>
2615 Following is an example for "qemuarm" machine:
2616 <literallayout class='monospaced'>
2617 HAVE_TOUCHSCREEN=1
2618 HAVE_KEYBOARD=1
2619
2620 DISPLAY_CAN_ROTATE=0
2621 DISPLAY_ORIENTATION=0
2622 #DISPLAY_WIDTH_PIXELS=640
2623 #DISPLAY_HEIGHT_PIXELS=480
2624 #DISPLAY_BPP=16
2625 DISPLAY_DPI=150
2626 DISPLAY_SUBPIXEL_ORDER=vrgb
2627 </literallayout>
2628 </para>
2629 </section>
2630 </section>
2631
2632 <section id="platdev-working-with-libraries">
2633 <title>Working With Libraries</title>
2634
2635 <para>
2636 Libraries are an integral part of your system.
2637 This section describes some common practices you might find
2638 helpful when working with libraries to build your system:
2639 <itemizedlist>
2640 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
2641 </para></listitem>
2642 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
2643 </para></listitem>
2644 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
2645 </para></listitem>
2646 </itemizedlist>
2647 </para>
2648
2649 <section id='including-static-library-files'>
2650 <title>Including Static Library Files</title>
2651
2652 <para>
2653 If you are building a library and the library offers static linking, you can control
2654 which static library files (<filename>*.a</filename> files) get included in the
2655 built library.
2656 </para>
2657
2658 <para>
2659 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
2660 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
2661 variables in the
2662 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
2663 by the <filename>do_install</filename> task are packaged.
2664 By default, the <filename>PACKAGES</filename> variable contains
2665 <filename>${PN}-staticdev</filename>, which includes all static library files.
2666 <note>
2667 Some previously released versions of the Yocto Project
2668 defined the static library files through
2669 <filename>${PN}-dev</filename>.
2670 </note>
2671 Following, is part of the BitBake configuration file.
2672 You can see where the static library files are defined:
2673 <literallayout class='monospaced'>
2674 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
2675 PACKAGES_DYNAMIC = "${PN}-locale-*"
2676 FILES = ""
2677
2678 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
2679 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
2680 ${base_bindir}/* ${base_sbindir}/* \
2681 ${base_libdir}/*${SOLIBS} \
2682 ${datadir}/${BPN} ${libdir}/${BPN}/* \
2683 ${datadir}/pixmaps ${datadir}/applications \
2684 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
2685 ${libdir}/bonobo/servers"
2686
2687 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
2688 ${datadir}/gnome/help"
2689 SECTION_${PN}-doc = "doc"
2690
2691 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
2692 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
2693 ${datadir}/aclocal ${base_libdir}/*.o"
2694 SECTION_${PN}-dev = "devel"
2695 ALLOW_EMPTY_${PN}-dev = "1"
2696 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
2697
2698 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
2699 SECTION_${PN}-staticdev = "devel"
2700 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
2701 </literallayout>
2702 </para>
2703 </section>
2704
2705 <section id="combining-multiple-versions-library-files-into-one-image">
2706 <title>Combining Multiple Versions of Library Files into One Image</title>
2707
2708 <para>
2709 The build system offers the ability to build libraries with different
2710 target optimizations or architecture formats and combine these together
2711 into one system image.
2712 You can link different binaries in the image
2713 against the different libraries as needed for specific use cases.
2714 This feature is called "Multilib."
2715 </para>
2716
2717 <para>
2718 An example would be where you have most of a system compiled in 32-bit
2719 mode using 32-bit libraries, but you have something large, like a database
2720 engine, that needs to be a 64-bit application and uses 64-bit libraries.
2721 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
2722 </para>
2723
2724 <para>
2725 While the Multilib feature is most commonly used for 32 and 64-bit differences,
2726 the approach the build system uses facilitates different target optimizations.
2727 You could compile some binaries to use one set of libraries and other binaries
2728 to use other different sets of libraries.
2729 The libraries could differ in architecture, compiler options, or other
2730 optimizations.
2731 </para>
2732
2733 <para>
2734 This section overviews the Multilib process only.
2735 For more details on how to implement Multilib, see the
2736 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
2737 page.
2738 </para>
2739
2740 <para>
2741 Aside from this wiki page, several examples exist in the
2742 <filename>meta-skeleton</filename> layer found in the
2743 <link linkend='source-directory'>Source Directory</link>:
2744 <itemizedlist>
2745 <listitem><para><filename>conf/multilib-example.conf</filename>
2746 configuration file</para></listitem>
2747 <listitem><para><filename>conf/multilib-example2.conf</filename>
2748 configuration file</para></listitem>
2749 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
2750 recipe</para></listitem>
2751 </itemizedlist>
2752 </para>
2753
2754 <section id='preparing-to-use-multilib'>
2755 <title>Preparing to Use Multilib</title>
2756
2757 <para>
2758 User-specific requirements drive the Multilib feature.
2759 Consequently, there is no one "out-of-the-box" configuration that likely
2760 exists to meet your needs.
2761 </para>
2762
2763 <para>
2764 In order to enable Multilib, you first need to ensure your recipe is
2765 extended to support multiple libraries.
2766 Many standard recipes are already extended and support multiple libraries.
2767 You can check in the <filename>meta/conf/multilib.conf</filename>
2768 configuration file in the
2769 <link linkend='source-directory'>Source Directory</link> to see how this is
2770 done using the
2771 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
2772 variable.
2773 Eventually, all recipes will be covered and this list will
2774 not be needed.
2775 </para>
2776
2777 <para>
2778 For the most part, the Multilib class extension works automatically to
2779 extend the package name from <filename>${PN}</filename> to
2780 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
2781 is the particular multilib (e.g. "lib32-" or "lib64-").
2782 Standard variables such as
2783 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2784 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
2785 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
2786 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
2787 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2788 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
2789 If you are extending any manual code in the recipe, you can use the
2790 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
2791 correctly.
2792 This automatic extension code resides in <filename>multilib.bbclass</filename>.
2793 </para>
2794 </section>
2795
2796 <section id='using-multilib'>
2797 <title>Using Multilib</title>
2798
2799 <para>
2800 After you have set up the recipes, you need to define the actual
2801 combination of multiple libraries you want to build.
2802 You accomplish this through your <filename>local.conf</filename>
2803 configuration file in the
2804 <link linkend='build-directory'>Build Directory</link>.
2805 An example configuration would be as follows:
2806 <literallayout class='monospaced'>
2807 MACHINE = "qemux86-64"
2808 require conf/multilib.conf
2809 MULTILIBS = "multilib:lib32"
2810 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
2811 IMAGE_INSTALL = "lib32-connman"
2812 </literallayout>
2813 This example enables an
2814 additional library named <filename>lib32</filename> alongside the
2815 normal target packages.
2816 When combining these "lib32" alternatives, the example uses "x86" for tuning.
2817 For information on this particular tuning, see
2818 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
2819 </para>
2820
2821 <para>
2822 The example then includes <filename>lib32-connman</filename>
2823 in all the images, which illustrates one method of including a
2824 multiple library dependency.
2825 You can use a normal image build to include this dependency,
2826 for example:
2827 <literallayout class='monospaced'>
2828 $ bitbake core-image-sato
2829 </literallayout>
2830 You can also build Multilib packages specifically with a command like this:
2831 <literallayout class='monospaced'>
2832 $ bitbake lib32-connman
2833 </literallayout>
2834 </para>
2835 </section>
2836
2837 <section id='additional-implementation-details'>
2838 <title>Additional Implementation Details</title>
2839
2840 <para>
2841 Different packaging systems have different levels of native Multilib
2842 support.
2843 For the RPM Package Management System, the following implementation details
2844 exist:
2845 <itemizedlist>
2846 <listitem><para>A unique architecture is defined for the Multilib packages,
2847 along with creating a unique deploy folder under
2848 <filename>tmp/deploy/rpm</filename> in the
2849 <link linkend='build-directory'>Build Directory</link>.
2850 For example, consider <filename>lib32</filename> in a
2851 <filename>qemux86-64</filename> image.
2852 The possible architectures in the system are "all", "qemux86_64",
2853 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
2854 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
2855 <filename>${PN}</filename> during RPM packaging.
2856 The naming for a normal RPM package and a Multilib RPM package in a
2857 <filename>qemux86-64</filename> system resolves to something similar to
2858 <filename>bash-4.1-r2.x86_64.rpm</filename> and
2859 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
2860 </para></listitem>
2861 <listitem><para>When installing a Multilib image, the RPM backend first
2862 installs the base image and then installs the Multilib libraries.
2863 </para></listitem>
2864 <listitem><para>The build system relies on RPM to resolve the identical files in the
2865 two (or more) Multilib packages.</para></listitem>
2866 </itemizedlist>
2867 </para>
2868
2869 <para>
2870 For the IPK Package Management System, the following implementation details exist:
2871 <itemizedlist>
2872 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
2873 <filename>${PN}</filename> during IPK packaging.
2874 The naming for a normal RPM package and a Multilib IPK package in a
2875 <filename>qemux86-64</filename> system resolves to something like
2876 <filename>bash_4.1-r2.x86_64.ipk</filename> and
2877 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
2878 </para></listitem>
2879 <listitem><para>The IPK deploy folder is not modified with
2880 <filename>${MLPREFIX}</filename> because packages with and without
2881 the Multilib feature can exist in the same folder due to the
2882 <filename>${PN}</filename> differences.</para></listitem>
2883 <listitem><para>IPK defines a sanity check for Multilib installation
2884 using certain rules for file comparison, overridden, etc.
2885 </para></listitem>
2886 </itemizedlist>
2887 </para>
2888 </section>
2889 </section>
2890
2891 <section id='installing-multiple-versions-of-the-same-library'>
2892 <title>Installing Multiple Versions of the Same Library</title>
2893
2894 <para>
2895 Situations can exist where you need to install and use
2896 multiple versions of the same library on the same system
2897 at the same time.
2898 These situations almost always exist when a library API
2899 changes and you have multiple pieces of software that
2900 depend on the separate versions of the library.
2901 To accommodate these situations, you can install multiple
2902 versions of the same library in parallel on the same system.
2903 </para>
2904
2905 <para>
2906 The process is straight forward as long as the libraries use
2907 proper versioning.
2908 With properly versioned libraries, all you need to do to
2909 individually specify the libraries is create separate,
2910 appropriately named recipes where the
2911 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
2912 name includes a portion that differentiates each library version
2913 (e.g.the major part of the version number).
2914 Thus, instead of having a single recipe that loads one version
2915 of a library (e.g. <filename>clutter</filename>), you provide
2916 multiple recipes that result in different versions
2917 of the libraries you want.
2918 As an example, the following two recipes would allow the
2919 two separate versions of the <filename>clutter</filename>
2920 library to co-exist on the same system:
2921 <literallayout class='monospaced'>
2922 clutter-1.6_1.6.20.bb
2923 clutter-1.8_1.8.4.bb
2924 </literallayout>
2925 Additionally, if you have other recipes that depend on a given
2926 library, you need to use the
2927 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2928 variable to create the dependency.
2929 Continuing with the same example, if you want to have a recipe
2930 depend on the 1.8 version of the <filename>clutter</filename>
2931 library, use the following in your recipe:
2932 <literallayout class='monospaced'>
2933 DEPENDS = "clutter-1.8"
2934 </literallayout>
2935 </para>
2936 </section>
2937 </section>
2938
2939 <section id='configuring-the-kernel'>
2940 <title>Configuring the Kernel</title>
2941
2942 <para>
2943 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
2944 file has all the right information in it for the image you are building.
2945 You can use the <filename>menuconfig</filename> tool and configuration fragments to
2946 make sure your <filename>.config</filename> file is just how you need it.
2947 This section describes how to use <filename>menuconfig</filename>, create and use
2948 configuration fragments, and how to interactively tweak your <filename>.config</filename>
2949 file to create the leanest kernel configuration file possible.
2950 </para>
2951
2952 <para>
2953 For more information on kernel configuration, see the
2954 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
2955 section in the Yocto Project Linux Kernel Development Manual.
2956 </para>
2957
2958 <section id='using-menuconfig'>
2959 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
2960
2961 <para>
2962 The easiest way to define kernel configurations is to set them through the
2963 <filename>menuconfig</filename> tool.
2964 This tool provides an interactive method with which
2965 to set kernel configurations.
2966 For general information on <filename>menuconfig</filename>, see
2967 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
2968 </para>
2969
2970 <para>
2971 To use the <filename>menuconfig</filename> tool in the Yocto Project development
2972 environment, you must launch it using BitBake.
2973 Thus, the environment must be set up using the
2974 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
2975 or
2976 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
2977 script found in the
2978 <link linkend='build-directory'>Build Directory</link>.
2979 The following commands run <filename>menuconfig</filename> assuming the
2980 <link linkend='source-directory'>Source Directory</link>
2981 top-level folder is <filename>~/poky</filename>:
2982 <literallayout class='monospaced'>
2983 $ cd poky
2984 $ source oe-init-build-env
2985 $ bitbake linux-yocto -c menuconfig
2986 </literallayout>
2987 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
2988 interactively examine and configure all the kernel configuration parameters.
2989 After making your changes, simply exit the tool and save your changes to
2990 create an updated version of the <filename>.config</filename> configuration file.
2991 </para>
2992
2993 <para>
2994 Consider an example that configures the <filename>linux-yocto-3.14</filename>
2995 kernel.
2996 The OpenEmbedded build system recognizes this kernel as
2997 <filename>linux-yocto</filename>.
2998 Thus, the following commands from the shell in which you previously sourced the
2999 environment initialization script cleans the shared state cache and the
3000 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
3001 directory and then runs <filename>menuconfig</filename>:
3002 <literallayout class='monospaced'>
3003 $ bitbake linux-yocto -c menuconfig
3004 </literallayout>
3005 </para>
3006
3007 <para>
3008 Once <filename>menuconfig</filename> launches, use the interface
3009 to navigate through the selections to find the configuration settings in
3010 which you are interested.
3011 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
3012 You can find it at <filename>Processor Type and Features</filename> under
3013 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
3014 After highlighting the selection, use the arrow keys to select or deselect
3015 the setting.
3016 When you are finished with all your selections, exit out and save them.
3017 </para>
3018
3019 <para>
3020 Saving the selections updates the <filename>.config</filename> configuration file.
3021 This is the file that the OpenEmbedded build system uses to configure the
3022 kernel during the build.
3023 You can find and examine this file in the Build Directory in
3024 <filename>tmp/work/</filename>.
3025 The actual <filename>.config</filename> is located in the area where the
3026 specific kernel is built.
3027 For example, if you were building a Linux Yocto kernel based on the
3028 Linux 3.14 kernel and you were building a QEMU image targeted for
3029 <filename>x86</filename> architecture, the
3030 <filename>.config</filename> file would be located here:
3031 <literallayout class='monospaced'>
3032 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
3033 ...656ed30-r1/linux-qemux86-standard-build
3034 </literallayout>
3035 <note>
3036 The previous example directory is artificially split and many of the characters
3037 in the actual filename are omitted in order to make it more readable.
3038 Also, depending on the kernel you are using, the exact pathname
3039 for <filename>linux-yocto-3.14...</filename> might differ.
3040 </note>
3041 </para>
3042
3043 <para>
3044 Within the <filename>.config</filename> file, you can see the kernel settings.
3045 For example, the following entry shows that symmetric multi-processor support
3046 is not set:
3047 <literallayout class='monospaced'>
3048 # CONFIG_SMP is not set
3049 </literallayout>
3050 </para>
3051
3052 <para>
3053 A good method to isolate changed configurations is to use a combination of the
3054 <filename>menuconfig</filename> tool and simple shell commands.
3055 Before changing configurations with <filename>menuconfig</filename>, copy the
3056 existing <filename>.config</filename> and rename it to something else,
3057 use <filename>menuconfig</filename> to make
3058 as many changes as you want and save them, then compare the renamed configuration
3059 file against the newly created file.
3060 You can use the resulting differences as your base to create configuration fragments
3061 to permanently save in your kernel layer.
3062 <note>
3063 Be sure to make a copy of the <filename>.config</filename> and don't just
3064 rename it.
3065 The build system needs an existing <filename>.config</filename>
3066 from which to work.
3067 </note>
3068 </para>
3069 </section>
3070
3071 <section id='creating-config-fragments'>
3072 <title>Creating Configuration Fragments</title>
3073
3074 <para>
3075 Configuration fragments are simply kernel options that appear in a file
3076 placed where the OpenEmbedded build system can find and apply them.
3077 Syntactically, the configuration statement is identical to what would appear
3078 in the <filename>.config</filename> file, which is in the
3079 <link linkend='build-directory'>Build Directory</link> in
3080 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
3081 </para>
3082
3083 <para>
3084 It is simple to create a configuration fragment.
3085 For example, issuing the following from the shell creates a configuration fragment
3086 file named <filename>my_smp.cfg</filename> that enables multi-processor support
3087 within the kernel:
3088 <literallayout class='monospaced'>
3089 $ echo "CONFIG_SMP=y" >> my_smp.cfg
3090 </literallayout>
3091 <note>
3092 All configuration files must use the <filename>.cfg</filename> extension in order
3093 for the OpenEmbedded build system to recognize them as a configuration fragment.
3094 </note>
3095 </para>
3096
3097 <para>
3098 Where do you put your configuration files?
3099 You can place these configuration files in the same area pointed to by
3100 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3101 The OpenEmbedded build system will pick up the configuration and add it to the
3102 kernel's configuration.
3103 For example, suppose you had a set of configuration options in a file called
3104 <filename>myconfig.cfg</filename>.
3105 If you put that file inside a directory named <filename>linux-yocto</filename>
3106 that resides in the same directory as the kernel's append file and then add
3107 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
3108 those configuration options will be picked up and applied when the kernel is built.
3109 <literallayout class='monospaced'>
3110 SRC_URI += "file://myconfig.cfg"
3111 </literallayout>
3112 </para>
3113
3114 <para>
3115 As mentioned earlier, you can group related configurations into multiple files and
3116 name them all in the <filename>SRC_URI</filename> statement as well.
3117 For example, you could group separate configurations specifically for Ethernet and graphics
3118 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
3119 following in your append file:
3120 <literallayout class='monospaced'>
3121 SRC_URI += "file://myconfig.cfg \
3122 file://eth.cfg \
3123 file://gfx.cfg"
3124 </literallayout>
3125 </para>
3126 </section>
3127
3128 <section id='fine-tuning-the-kernel-configuration-file'>
3129 <title>Fine-Tuning the Kernel Configuration File</title>
3130
3131 <para>
3132 You can make sure the <filename>.config</filename> file is as lean or efficient as
3133 possible by reading the output of the kernel configuration fragment audit,
3134 noting any issues, making changes to correct the issues, and then repeating.
3135 </para>
3136
3137 <para>
3138 As part of the kernel build process, the
3139 <filename>kernel_configcheck</filename> task runs.
3140 This task validates the kernel configuration by checking the final
3141 <filename>.config</filename> file against the input files.
3142 During the check, the task produces warning messages for the following
3143 issues:
3144 <itemizedlist>
3145 <listitem><para>Requested options that did not make the final
3146 <filename>.config</filename> file.</para></listitem>
3147 <listitem><para>Configuration items that appear twice in the same
3148 configuration fragment.</para></listitem>
3149 <listitem><para>Configuration items tagged as "required" that were overridden.
3150 </para></listitem>
3151 <listitem><para>A board overrides a non-board specific option.</para></listitem>
3152 <listitem><para>Listed options not valid for the kernel being processed.
3153 In other words, the option does not appear anywhere.</para></listitem>
3154 </itemizedlist>
3155 <note>
3156 The <filename>kernel_configcheck</filename> task can also optionally report
3157 if an option is overridden during processing.
3158 </note>
3159 </para>
3160
3161 <para>
3162 For each output warning, a message points to the file
3163 that contains a list of the options and a pointer to the config
3164 fragment that defines them.
3165 Collectively, the files are the key to streamlining the configuration.
3166 </para>
3167
3168 <para>
3169 To streamline the configuration, do the following:
3170 <orderedlist>
3171 <listitem><para>Start with a full configuration that you know
3172 works - it builds and boots successfully.
3173 This configuration file will be your baseline.</para></listitem>
3174 <listitem><para>Separately run the <filename>configme</filename> and
3175 <filename>kernel_configcheck</filename> tasks.</para></listitem>
3176 <listitem><para>Take the resulting list of files from the
3177 <filename>kernel_configcheck</filename> task warnings and do the following:
3178 <itemizedlist>
3179 <listitem><para>Drop values that are redefined in the fragment but do not
3180 change the final <filename>.config</filename> file.</para></listitem>
3181 <listitem><para>Analyze and potentially drop values from the
3182 <filename>.config</filename> file that override required
3183 configurations.</para></listitem>
3184 <listitem><para>Analyze and potentially remove non-board specific options.
3185 </para></listitem>
3186 <listitem><para>Remove repeated and invalid options.</para></listitem>
3187 </itemizedlist></para></listitem>
3188 <listitem><para>After you have worked through the output of the kernel configuration
3189 audit, you can re-run the <filename>configme</filename>
3190 and <filename>kernel_configcheck</filename> tasks to see the results of your
3191 changes.
3192 If you have more issues, you can deal with them as described in the
3193 previous step.</para></listitem>
3194 </orderedlist>
3195 </para>
3196
3197 <para>
3198 Iteratively working through steps two through four eventually yields
3199 a minimal, streamlined configuration file.
3200 Once you have the best <filename>.config</filename>, you can build the Linux
3201 Yocto kernel.
3202 </para>
3203 </section>
3204 </section>
3205
3206 <section id="patching-the-kernel">
3207 <title>Patching the Kernel</title>
3208
3209 <para>
3210 Patching the kernel involves changing or adding configurations to an existing kernel,
3211 changing or adding recipes to the kernel that are needed to support specific hardware features,
3212 or even altering the source code itself.
3213 <note>
3214 You can use the <filename>yocto-kernel</filename> script
3215 found in the <link linkend='source-directory'>Source Directory</link>
3216 under <filename>scripts</filename> to manage kernel patches and configuration.
3217 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
3218 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
3219 more information.</note>
3220 </para>
3221
3222 <para>
3223 This example creates a simple patch by adding some QEMU emulator console
3224 output at boot time through <filename>printk</filename> statements in the kernel's
3225 <filename>calibrate.c</filename> source code file.
3226 Applying the patch and booting the modified image causes the added
3227 messages to appear on the emulator's console.
3228 </para>