summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml7418
1 files changed, 7418 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..bead56c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,7418 @@
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 irssi_0.8.16-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='properly-versioning-pre-release-recipes'>
2151 <title>Properly Versioning Pre-Release Recipes</title>
2152
2153 <para>
2154 Sometimes the name of a recipe can lead to versioning
2155 problems when the recipe is upgraded to a final release.
2156 For example, consider the
2157 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2158 the list of example recipes in the
2159 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2160 section.
2161 This recipe is at a release candidate stage (i.e.
2162 "rc1").
2163 When the recipe is released, the recipe filename becomes
2164 <filename>irssi_0.8.16.bb</filename>.
2165 The version change from <filename>0.8.16-rc1</filename>
2166 to <filename>0.8.16</filename> is seen as a decrease by the
2167 build system and package managers, so the resulting packages
2168 will not correctly trigger an upgrade.
2169 </para>
2170
2171 <para>
2172 In order to ensure the versions compare properly, the
2173 recommended convention is to set
2174 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2175 within the recipe to
2176 "&lt;previous version&gt;+&lt;current version&gt;".
2177 You can use an additional variable so that you can use the
2178 current version elsewhere.
2179 Here is an example:
2180 <literallayout class='monospaced'>
2181 REALPV = "0.8.16-rc1"
2182 PV = "0.8.15+${REALPV}"
2183 </literallayout>
2184 </para>
2185 </section>
2186
2187 <section id='new-recipe-post-installation-scripts'>
2188 <title>Post-Installation Scripts</title>
2189
2190 <para>
2191 Post-installation scripts run immediately after installing
2192 a package on the target, or during image creation when a
2193 package is included in an image.
2194 To add a post-installation script to a package, add a
2195 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2196 the recipe file (<filename>.bb</filename>) and use
2197 <filename>PACKAGENAME</filename> as the name of the package
2198 you want to attach to the <filename>postinst</filename>
2199 script.
2200 To apply the post-installation script to the main package
2201 for the recipe, which is usually what is required, specify
2202 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2203 in place of <filename>PACKAGENAME</filename>.
2204 </para>
2205
2206 <para>
2207 A post-installation function has the following structure:
2208 <literallayout class='monospaced'>
2209 pkg_postinst_PACKAGENAME () {
2210 #!/bin/sh -e
2211 # Commands to carry out
2212 }
2213 </literallayout>
2214 </para>
2215
2216 <para>
2217 The script defined in the post-installation function is
2218 called when the root filesystem is created.
2219 If the script succeeds, the package is marked as installed.
2220 If the script fails, the package is marked as unpacked and
2221 the script is executed when the image boots again.
2222 </para>
2223
2224 <para>
2225 Sometimes it is necessary for the execution of a
2226 post-installation script to be delayed until the first boot.
2227 For example, the script might need to be executed on the
2228 device itself.
2229 To delay script execution until boot time, use the following
2230 structure in the post-installation script:
2231 <literallayout class='monospaced'>
2232 pkg_postinst_PACKAGENAME () {
2233 #!/bin/sh -e
2234 if [ x"$D" = "x" ]; then
2235 # Actions to carry out on the device go here
2236 else
2237 exit 1
2238 fi
2239 }
2240 </literallayout>
2241 </para>
2242
2243 <para>
2244 The previous example delays execution until the image boots
2245 again because the
2246 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2247 variable points to the directory containing the image when
2248 the root filesystem is created at build time but is unset
2249 when executed on the first boot.
2250 </para>
2251
2252 <note>
2253 Equivalent support for pre-install, pre-uninstall, and
2254 post-uninstall scripts exist by way of
2255 <filename>pkg_preinst</filename>,
2256 <filename>pkg_prerm</filename>, and
2257 <filename>pkg_postrm</filename>, respectively.
2258 These scrips work in exactly the same way as does
2259 <filename>pkg_postinst</filename> with the exception that they
2260 run at different times.
2261 Also, because of when they run, they are not applicable to
2262 being run at image creation time like
2263 <filename>pkg_postinst</filename>.
2264 </note>
2265 </section>
2266
2267 <section id='new-recipe-testing'>
2268 <title>Testing</title>
2269
2270 <para>
2271 The final step for completing your recipe is to be sure that
2272 the software you built runs correctly.
2273 To accomplish runtime testing, add the build's output
2274 packages to your image and test them on the target.
2275 </para>
2276
2277 <para>
2278 For information on how to customize your image by adding
2279 specific packages, see the
2280 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2281 section.
2282 </para>
2283 </section>
2284
2285 <section id='new-recipe-testing-examples'>
2286 <title>Examples</title>
2287
2288 <para>
2289 To help summarize how to write a recipe, this section provides
2290 some examples given various scenarios:
2291 <itemizedlist>
2292 <listitem><para>Recipes that use local files</para></listitem>
2293 <listitem><para>Using an Autotooled package</para></listitem>
2294 <listitem><para>Using a Makefile-based package</para></listitem>
2295 <listitem><para>Splitting an application into multiple packages</para></listitem>
2296 </itemizedlist>
2297 </para>
2298
2299 <section id='new-recipe-single-c-file-package-hello-world'>
2300 <title>Single .c File Package (Hello World!)</title>
2301
2302 <para>
2303 Building an application from a single file that is stored
2304 locally (e.g. under <filename>files/</filename>) requires
2305 a recipe that has the file listed in the
2306 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2307 variable.
2308 Additionally, you need to manually write the
2309 <filename>do_compile</filename> and
2310 <filename>do_install</filename> tasks.
2311 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2312 variable defines the directory containing the source code,
2313 which is set to
2314 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2315 in this case - the directory BitBake uses for the build.
2316 <literallayout class='monospaced'>
2317 SUMMARY = "Simple helloworld application"
2318 SECTION = "examples"
2319 LICENSE = "MIT"
2320 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2321
2322 SRC_URI = "file://helloworld.c"
2323
2324 S = "${WORKDIR}"
2325
2326 do_compile() {
2327 ${CC} helloworld.c -o helloworld
2328 }
2329
2330 do_install() {
2331 install -d ${D}${bindir}
2332 install -m 0755 helloworld ${D}${bindir}
2333 }
2334 </literallayout>
2335 </para>
2336
2337 <para>
2338 By default, the <filename>helloworld</filename>,
2339 <filename>helloworld-dbg</filename>, and
2340 <filename>helloworld-dev</filename> packages are built.
2341 For information on how to customize the packaging process,
2342 see the
2343 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2344 section.
2345 </para>
2346 </section>
2347
2348 <section id='new-recipe-autotooled-package'>
2349 <title>Autotooled Package</title>
2350 <para>
2351 Applications that use Autotools such as <filename>autoconf</filename> and
2352 <filename>automake</filename> require a recipe that has a source archive listed in
2353 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2354 also inherit the
2355 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2356 class, which contains the definitions of all the steps
2357 needed to build an Autotool-based application.
2358 The result of the build is automatically packaged.
2359 And, if the application uses NLS for localization, packages with local information are
2360 generated (one package per language).
2361 Following is one example: (<filename>hello_2.3.bb</filename>)
2362 <literallayout class='monospaced'>
2363 SUMMARY = "GNU Helloworld application"
2364 SECTION = "examples"
2365 LICENSE = "GPLv2+"
2366 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2367
2368 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2369
2370 inherit autotools gettext
2371 </literallayout>
2372 </para>
2373
2374 <para>
2375 The variable
2376 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2377 is used to track source license changes as described in the
2378 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2379 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2380 </para>
2381 </section>
2382
2383 <section id='new-recipe-makefile-based-package'>
2384 <title>Makefile-Based Package</title>
2385
2386 <para>
2387 Applications that use GNU <filename>make</filename> also require a recipe that has
2388 the source archive listed in
2389 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2390 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2391 starts the <filename>make</filename> command to compile the application.
2392 If you need additional <filename>make</filename> options, you should store them in the
2393 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2394 variable.
2395 BitBake passes these options into the <filename>make</filename> GNU invocation.
2396 Note that a <filename>do_install</filename> task is still required.
2397 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2398 </para>
2399
2400 <para>
2401 Some applications might require extra parameters to be passed to the compiler.
2402 For example, the application might need an additional header path.
2403 You can accomplish this by adding to the
2404 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2405 The following example shows this:
2406 <literallayout class='monospaced'>
2407 CFLAGS_prepend = "-I ${S}/include "
2408 </literallayout>
2409 </para>
2410
2411 <para>
2412 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2413 <literallayout class='monospaced'>
2414 SUMMARY = "Tools for managing memory technology devices."
2415 SECTION = "base"
2416 DEPENDS = "zlib lzo e2fsprogs util-linux"
2417 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2418 LICENSE = "GPLv2+"
2419 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2420 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2421
2422 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2423 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2424
2425 S = "${WORKDIR}/git/"
2426
2427 PR = "r1"
2428
2429 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2430 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2431
2432 do_install () {
2433 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2434 INCLUDEDIR=${includedir}
2435 install -d ${D}${includedir}/mtd/
2436 for f in ${S}/include/mtd/*.h; do
2437 install -m 0644 $f ${D}${includedir}/mtd/
2438 done
2439 }
2440
2441 PARALLEL_MAKE = ""
2442
2443 BBCLASSEXTEND = "native"
2444 </literallayout>
2445 </para>
2446 </section>
2447
2448 <section id='splitting-an-application-into-multiple-packages'>
2449 <title>Splitting an Application into Multiple Packages</title>
2450
2451 <para>
2452 You can use the variables
2453 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2454 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2455 to split an application into multiple packages.
2456 </para>
2457
2458 <para>
2459 Following is an example that uses the <filename>libxpm</filename> recipe.
2460 By default, this recipe generates a single package that contains the library along
2461 with a few binaries.
2462 You can modify the recipe to split the binaries into separate packages:
2463 <literallayout class='monospaced'>
2464 require xorg-lib-common.inc
2465
2466 SUMMARY = "X11 Pixmap library"
2467 LICENSE = "X-BSD"
2468 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2469 DEPENDS += "libxext libsm libxt"
2470 PR = "r3"
2471 PE = "1"
2472
2473 XORG_PN = "libXpm"
2474
2475 PACKAGES =+ "sxpm cxpm"
2476 FILES_cxpm = "${bindir}/cxpm"
2477 FILES_sxpm = "${bindir}/sxpm"
2478 </literallayout>
2479 </para>
2480
2481 <para>
2482 In the previous example, we want to ship the <filename>sxpm</filename>
2483 and <filename>cxpm</filename> binaries in separate packages.
2484 Since <filename>bindir</filename> would be packaged into the main
2485 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2486 package by default, we prepend the <filename>PACKAGES</filename>
2487 variable so additional package names are added to the start of list.
2488 This results in the extra <filename>FILES_*</filename>
2489 variables then containing information that define which files and
2490 directories go into which packages.
2491 Files included by earlier packages are skipped by latter packages.
2492 Thus, the main <filename>PN</filename> package
2493 does not include the above listed files.
2494 </para>
2495 </section>
2496 </section>
2497 </section>
2498
2499 <section id="platdev-newmachine">
2500 <title>Adding a New Machine</title>
2501
2502 <para>
2503 Adding a new machine to the Yocto Project is a straight forward
2504 process.
2505 This section describes how to add machines that are similar
2506 to those that the Yocto Project already supports.
2507 <note>
2508 Although well within the capabilities of the Yocto Project,
2509 adding a totally new architecture might require
2510 changes to <filename>gcc/eglibc</filename> and to the site
2511 information, which is beyond the scope of this manual.
2512 </note>
2513 </para>
2514
2515 <para>
2516 For a complete example that shows how to add a new machine,
2517 see the
2518 "<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>"
2519 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
2520 </para>
2521
2522 <section id="platdev-newmachine-conffile">
2523 <title>Adding the Machine Configuration File</title>
2524
2525 <para>
2526 To add a new machine, you need to add a new machine
2527 configuration file to the layer's
2528 <filename>conf/machine</filename> directory.
2529 This configuration file provides details about the device
2530 you are adding.
2531 </para>
2532
2533 <para>
2534 The OpenEmbedded build system uses the root name of the
2535 machine configuration file to reference the new machine.
2536 For example, given a machine configuration file named
2537 <filename>crownbay.conf</filename>, the build system
2538 recognizes the machine as "crownbay".
2539 </para>
2540
2541 <para>
2542 The most important variables you must set in your machine
2543 configuration file are as follows:
2544 <itemizedlist>
2545 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
2546 (e.g. "arm")</para></listitem>
2547 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
2548 (see below)</para></listitem>
2549 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
2550 (e.g. "apm screen wifi")</para></listitem>
2551 </itemizedlist>
2552 </para>
2553
2554 <para>
2555 You might also need these variables:
2556 <itemizedlist>
2557 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
2558 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
2559 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
2560 (e.g. "zImage")</para></listitem>
2561 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
2562 (e.g. "tar.gz jffs2")</para></listitem>
2563 </itemizedlist>
2564 </para>
2565
2566 <para>
2567 You can find full details on these variables in the reference
2568 section.
2569 You can leverage existing machine <filename>.conf</filename>
2570 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
2571 </para>
2572 </section>
2573
2574 <section id="platdev-newmachine-kernel">
2575 <title>Adding a Kernel for the Machine</title>
2576
2577 <para>
2578 The OpenEmbedded build system needs to be able to build a kernel
2579 for the machine.
2580 You need to either create a new kernel recipe for this machine,
2581 or extend an existing kernel recipe.
2582 You can find several kernel recipe examples in the
2583 Source Directory at
2584 <filename>meta/recipes-kernel/linux</filename>
2585 that you can use as references.
2586 </para>
2587
2588 <para>
2589 If you are creating a new kernel recipe, normal recipe-writing
2590 rules apply for setting up a
2591 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2592 Thus, you need to specify any necessary patches and set
2593 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2594 to point at the source code.
2595 You need to create a <filename>do_configure</filename> task that
2596 configures the unpacked kernel with a
2597 <filename>defconfig</filename> file.
2598 You can do this by using a <filename>make defconfig</filename>
2599 command or, more commonly, by copying in a suitable
2600 <filename>defconfig</filename> file and then running
2601 <filename>make oldconfig</filename>.
2602 By making use of <filename>inherit kernel</filename> and
2603 potentially some of the <filename>linux-*.inc</filename> files,
2604 most other functionality is centralized and the defaults of the
2605 class normally work well.
2606 </para>
2607
2608 <para>
2609 If you are extending an existing kernel recipe, it is usually
2610 a matter of adding a suitable <filename>defconfig</filename>
2611 file.
2612 The file needs to be added into a location similar to
2613 <filename>defconfig</filename> files used for other machines
2614 in a given kernel recipe.
2615 A possible way to do this is by listing the file in the
2616 <filename>SRC_URI</filename> and adding the machine to the
2617 expression in
2618 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
2619 <literallayout class='monospaced'>
2620 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2621 </literallayout>
2622 </para>
2623 </section>
2624
2625 <section id="platdev-newmachine-formfactor">
2626 <title>Adding a Formfactor Configuration File</title>
2627
2628 <para>
2629 A formfactor configuration file provides information about the
2630 target hardware for which the image is being built and information that
2631 the build system cannot obtain from other sources such as the kernel.
2632 Some examples of information contained in a formfactor configuration file include
2633 framebuffer orientation, whether or not the system has a keyboard,
2634 the positioning of the keyboard in relation to the screen, and
2635 the screen resolution.
2636 </para>
2637
2638 <para>
2639 The build system uses reasonable defaults in most cases.
2640 However, if customization is
2641 necessary, you need to create a <filename>machconfig</filename> file
2642 in the <filename>meta/recipes-bsp/formfactor/files</filename>
2643 directory.
2644 This directory contains directories for specific machines such as
2645 <filename>qemuarm</filename> and <filename>qemux86</filename>.
2646 For information about the settings available and the defaults, see the
2647 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
2648 same area.
2649 </para>
2650
2651 <para>
2652 Following is an example for "qemuarm" machine:
2653 <literallayout class='monospaced'>
2654 HAVE_TOUCHSCREEN=1
2655 HAVE_KEYBOARD=1
2656
2657 DISPLAY_CAN_ROTATE=0
2658 DISPLAY_ORIENTATION=0
2659 #DISPLAY_WIDTH_PIXELS=640
2660 #DISPLAY_HEIGHT_PIXELS=480
2661 #DISPLAY_BPP=16
2662 DISPLAY_DPI=150
2663 DISPLAY_SUBPIXEL_ORDER=vrgb
2664 </literallayout>
2665 </para>
2666 </section>
2667 </section>
2668
2669 <section id="platdev-working-with-libraries">
2670 <title>Working With Libraries</title>
2671
2672 <para>
2673 Libraries are an integral part of your system.
2674 This section describes some common practices you might find
2675 helpful when working with libraries to build your system:
2676 <itemizedlist>
2677 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
2678 </para></listitem>
2679 <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>
2680 </para></listitem>
2681 <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>
2682 </para></listitem>
2683 </itemizedlist>
2684 </para>
2685
2686 <section id='including-static-library-files'>
2687 <title>Including Static Library Files</title>
2688
2689 <para>
2690 If you are building a library and the library offers static linking, you can control
2691 which static library files (<filename>*.a</filename> files) get included in the
2692 built library.
2693 </para>
2694
2695 <para>
2696 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
2697 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
2698 variables in the
2699 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
2700 by the <filename>do_install</filename> task are packaged.
2701 By default, the <filename>PACKAGES</filename> variable contains
2702 <filename>${PN}-staticdev</filename>, which includes all static library files.
2703 <note>
2704 Some previously released versions of the Yocto Project
2705 defined the static library files through
2706 <filename>${PN}-dev</filename>.
2707 </note>
2708 Following, is part of the BitBake configuration file.
2709 You can see where the static library files are defined:
2710 <literallayout class='monospaced'>
2711 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
2712 PACKAGES_DYNAMIC = "${PN}-locale-*"
2713 FILES = ""
2714
2715 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
2716 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
2717 ${base_bindir}/* ${base_sbindir}/* \
2718 ${base_libdir}/*${SOLIBS} \
2719 ${datadir}/${BPN} ${libdir}/${BPN}/* \
2720 ${datadir}/pixmaps ${datadir}/applications \
2721 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
2722 ${libdir}/bonobo/servers"
2723
2724 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
2725 ${datadir}/gnome/help"
2726 SECTION_${PN}-doc = "doc"
2727
2728 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
2729 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
2730 ${datadir}/aclocal ${base_libdir}/*.o"
2731 SECTION_${PN}-dev = "devel"
2732 ALLOW_EMPTY_${PN}-dev = "1"
2733 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
2734
2735 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
2736 SECTION_${PN}-staticdev = "devel"
2737 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
2738 </literallayout>
2739 </para>
2740 </section>
2741
2742 <section id="combining-multiple-versions-library-files-into-one-image">
2743 <title>Combining Multiple Versions of Library Files into One Image</title>
2744
2745 <para>
2746 The build system offers the ability to build libraries with different
2747 target optimizations or architecture formats and combine these together
2748 into one system image.
2749 You can link different binaries in the image
2750 against the different libraries as needed for specific use cases.
2751 This feature is called "Multilib."
2752 </para>
2753
2754 <para>
2755 An example would be where you have most of a system compiled in 32-bit
2756 mode using 32-bit libraries, but you have something large, like a database
2757 engine, that needs to be a 64-bit application and uses 64-bit libraries.
2758 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
2759 </para>
2760
2761 <para>
2762 While the Multilib feature is most commonly used for 32 and 64-bit differences,
2763 the approach the build system uses facilitates different target optimizations.
2764 You could compile some binaries to use one set of libraries and other binaries
2765 to use other different sets of libraries.
2766 The libraries could differ in architecture, compiler options, or other
2767 optimizations.
2768 </para>
2769
2770 <para>
2771 This section overviews the Multilib process only.
2772 For more details on how to implement Multilib, see the
2773 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
2774 page.
2775 </para>
2776
2777 <para>
2778 Aside from this wiki page, several examples exist in the
2779 <filename>meta-skeleton</filename> layer found in the
2780 <link linkend='source-directory'>Source Directory</link>:
2781 <itemizedlist>
2782 <listitem><para><filename>conf/multilib-example.conf</filename>
2783 configuration file</para></listitem>
2784 <listitem><para><filename>conf/multilib-example2.conf</filename>
2785 configuration file</para></listitem>
2786 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
2787 recipe</para></listitem>
2788 </itemizedlist>
2789 </para>
2790
2791 <section id='preparing-to-use-multilib'>
2792 <title>Preparing to Use Multilib</title>
2793
2794 <para>
2795 User-specific requirements drive the Multilib feature.
2796 Consequently, there is no one "out-of-the-box" configuration that likely
2797 exists to meet your needs.
2798 </para>
2799
2800 <para>
2801 In order to enable Multilib, you first need to ensure your recipe is
2802 extended to support multiple libraries.
2803 Many standard recipes are already extended and support multiple libraries.
2804 You can check in the <filename>meta/conf/multilib.conf</filename>
2805 configuration file in the
2806 <link linkend='source-directory'>Source Directory</link> to see how this is
2807 done using the
2808 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
2809 variable.
2810 Eventually, all recipes will be covered and this list will
2811 not be needed.
2812 </para>
2813
2814 <para>
2815 For the most part, the Multilib class extension works automatically to
2816 extend the package name from <filename>${PN}</filename> to
2817 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
2818 is the particular multilib (e.g. "lib32-" or "lib64-").
2819 Standard variables such as
2820 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2821 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
2822 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
2823 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
2824 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2825 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
2826 If you are extending any manual code in the recipe, you can use the
2827 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
2828 correctly.
2829 This automatic extension code resides in <filename>multilib.bbclass</filename>.
2830 </para>
2831 </section>
2832
2833 <section id='using-multilib'>
2834 <title>Using Multilib</title>
2835
2836 <para>
2837 After you have set up the recipes, you need to define the actual
2838 combination of multiple libraries you want to build.
2839 You accomplish this through your <filename>local.conf</filename>
2840 configuration file in the
2841 <link linkend='build-directory'>Build Directory</link>.
2842 An example configuration would be as follows:
2843 <literallayout class='monospaced'>
2844 MACHINE = "qemux86-64"
2845 require conf/multilib.conf
2846 MULTILIBS = "multilib:lib32"
2847 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
2848 IMAGE_INSTALL = "lib32-connman"
2849 </literallayout>
2850 This example enables an
2851 additional library named <filename>lib32</filename> alongside the
2852 normal target packages.
2853 When combining these "lib32" alternatives, the example uses "x86" for tuning.
2854 For information on this particular tuning, see
2855 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
2856 </para>
2857
2858 <para>
2859 The example then includes <filename>lib32-connman</filename>
2860 in all the images, which illustrates one method of including a
2861 multiple library dependency.
2862 You can use a normal image build to include this dependency,
2863 for example:
2864 <literallayout class='monospaced'>
2865 $ bitbake core-image-sato
2866 </literallayout>
2867 You can also build Multilib packages specifically with a command like this:
2868 <literallayout class='monospaced'>
2869 $ bitbake lib32-connman
2870 </literallayout>
2871 </para>
2872 </section>
2873
2874 <section id='additional-implementation-details'>
2875 <title>Additional Implementation Details</title>
2876
2877 <para>
2878 Different packaging systems have different levels of native Multilib
2879 support.
2880 For the RPM Package Management System, the following implementation details
2881 exist:
2882 <itemizedlist>
2883 <listitem><para>A unique architecture is defined for the Multilib packages,
2884 along with creating a unique deploy folder under
2885 <filename>tmp/deploy/rpm</filename> in the
2886 <link linkend='build-directory'>Build Directory</link>.
2887 For example, consider <filename>lib32</filename> in a
2888 <filename>qemux86-64</filename> image.
2889 The possible architectures in the system are "all", "qemux86_64",
2890 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
2891 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
2892 <filename>${PN}</filename> during RPM packaging.
2893 The naming for a normal RPM package and a Multilib RPM package in a
2894 <filename>qemux86-64</filename> system resolves to something similar to
2895 <filename>bash-4.1-r2.x86_64.rpm</filename> and
2896 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
2897 </para></listitem>
2898 <listitem><para>When installing a Multilib image, the RPM backend first
2899 installs the base image and then installs the Multilib libraries.
2900 </para></listitem>
2901 <listitem><para>The build system relies on RPM to resolve the identical files in the
2902 two (or more) Multilib packages.</para></listitem>
2903 </itemizedlist>
2904 </para>
2905
2906 <para>
2907 For the IPK Package Management System, the following implementation details exist:
2908 <itemizedlist>
2909 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
2910 <filename>${PN}</filename> during IPK packaging.
2911 The naming for a normal RPM package and a Multilib IPK package in a
2912 <filename>qemux86-64</filename> system resolves to something like
2913 <filename>bash_4.1-r2.x86_64.ipk</filename> and
2914 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
2915 </para></listitem>
2916 <listitem><para>The IPK deploy folder is not modified with
2917 <filename>${MLPREFIX}</filename> because packages with and without
2918 the Multilib feature can exist in the same folder due to the
2919 <filename>${PN}</filename> differences.</para></listitem>
2920 <listitem><para>IPK defines a sanity check for Multilib installation
2921 using certain rules for file comparison, overridden, etc.
2922 </para></listitem>
2923 </itemizedlist>
2924 </para>
2925 </section>
2926 </section>
2927
2928 <section id='installing-multiple-versions-of-the-same-library'>
2929 <title>Installing Multiple Versions of the Same Library</title>
2930
2931 <para>
2932 Situations can exist where you need to install and use
2933 multiple versions of the same library on the same system
2934 at the same time.
2935 These situations almost always exist when a library API
2936 changes and you have multiple pieces of software that
2937 depend on the separate versions of the library.
2938 To accommodate these situations, you can install multiple
2939 versions of the same library in parallel on the same system.
2940 </para>
2941
2942 <para>
2943 The process is straight forward as long as the libraries use
2944 proper versioning.
2945 With properly versioned libraries, all you need to do to
2946 individually specify the libraries is create separate,
2947 appropriately named recipes where the
2948 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
2949 name includes a portion that differentiates each library version
2950 (e.g.the major part of the version number).
2951 Thus, instead of having a single recipe that loads one version
2952 of a library (e.g. <filename>clutter</filename>), you provide
2953 multiple recipes that result in different versions
2954 of the libraries you want.
2955 As an example, the following two recipes would allow the
2956 two separate versions of the <filename>clutter</filename>
2957 library to co-exist on the same system:
2958 <literallayout class='monospaced'>
2959 clutter-1.6_1.6.20.bb
2960 clutter-1.8_1.8.4.bb
2961 </literallayout>
2962 Additionally, if you have other recipes that depend on a given
2963 library, you need to use the
2964 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2965 variable to create the dependency.
2966 Continuing with the same example, if you want to have a recipe
2967 depend on the 1.8 version of the <filename>clutter</filename>
2968 library, use the following in your recipe:
2969 <literallayout class='monospaced'>
2970 DEPENDS = "clutter-1.8"
2971 </literallayout>
2972 </para>
2973 </section>
2974 </section>
2975
2976 <section id='configuring-the-kernel'>
2977 <title>Configuring the Kernel</title>
2978
2979 <para>
2980 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
2981 file has all the right information in it for the image you are building.
2982 You can use the <filename>menuconfig</filename> tool and configuration fragments to
2983 make sure your <filename>.config</filename> file is just how you need it.
2984 This section describes how to use <filename>menuconfig</filename>, create and use
2985 configuration fragments, and how to interactively tweak your <filename>.config</filename>
2986 file to create the leanest kernel configuration file possible.
2987 </para>
2988
2989 <para>
2990 For more information on kernel configuration, see the
2991 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
2992 section in the Yocto Project Linux Kernel Development Manual.
2993 </para>
2994
2995 <section id='using-menuconfig'>
2996 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
2997
2998 <para>
2999 The easiest way to define kernel configurations is to set them through the
3000 <filename>menuconfig</filename> tool.
3001 This tool provides an interactive method with which
3002 to set kernel configurations.
3003 For general information on <filename>menuconfig</filename>, see
3004 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
3005 </para>
3006
3007 <para>
3008 To use the <filename>menuconfig</filename> tool in the Yocto Project development
3009 environment, you must launch it using BitBake.
3010 Thus, the environment must be set up using the
3011 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3012 or
3013 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
3014 script found in the
3015 <link linkend='build-directory'>Build Directory</link>.
3016 The following commands run <filename>menuconfig</filename> assuming the
3017 <link linkend='source-directory'>Source Directory</link>
3018 top-level folder is <filename>~/poky</filename>:
3019 <literallayout class='monospaced'>
3020 $ cd poky
3021 $ source oe-init-build-env
3022 $ bitbake linux-yocto -c menuconfig
3023 </literallayout>
3024 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
3025 interactively examine and configure all the kernel configuration parameters.
3026 After making your changes, simply exit the tool and save your changes to
3027 create an updated version of the <filename>.config</filename> configuration file.
3028 </para>
3029
3030 <para>
3031 Consider an example that configures the <filename>linux-yocto-3.14</filename>
3032 kernel.
3033 The OpenEmbedded build system recognizes this kernel as
3034 <filename>linux-yocto</filename>.
3035 Thus, the following commands from the shell in which you previously sourced the
3036 environment initialization script cleans the shared state cache and the
3037 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
3038 directory and then runs <filename>menuconfig</filename>:
3039 <literallayout class='monospaced'>
3040 $ bitbake linux-yocto -c menuconfig
3041 </literallayout>
3042 </para>
3043
3044 <para>
3045 Once <filename>menuconfig</filename> launches, use the interface
3046 to navigate through the selections to find the configuration settings in
3047 which you are interested.
3048 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
3049 You can find it at <filename>Processor Type and Features</filename> under
3050 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
3051 After highlighting the selection, use the arrow keys to select or deselect
3052 the setting.
3053 When you are finished with all your selections, exit out and save them.
3054 </para>
3055
3056 <para>
3057 Saving the selections updates the <filename>.config</filename> configuration file.
3058 This is the file that the OpenEmbedded build system uses to configure the
3059 kernel during the build.
3060 You can find and examine this file in the Build Directory in
3061 <filename>tmp/work/</filename>.
3062 The actual <filename>.config</filename> is located in the area where the
3063 specific kernel is built.
3064 For example, if you were building a Linux Yocto kernel based on the
3065 Linux 3.14 kernel and you were building a QEMU image targeted for
3066 <filename>x86</filename> architecture, the
3067 <filename>.config</filename> file would be located here:
3068 <literallayout class='monospaced'>
3069 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
3070 ...656ed30-r1/linux-qemux86-standard-build
3071 </literallayout>
3072 <note>
3073 The previous example directory is artificially split and many of the characters
3074 in the actual filename are omitted in order to make it more readable.
3075 Also, depending on the kernel you are using, the exact pathname
3076 for <filename>linux-yocto-3.14...</filename> might differ.
3077 </note>
3078 </para>
3079
3080 <para>
3081 Within the <filename>.config</filename> file, you can see the kernel settings.
3082 For example, the following entry shows that symmetric multi-processor support
3083 is not set:
3084 <literallayout class='monospaced'>
3085 # CONFIG_SMP is not set
3086 </literallayout>
3087 </para>
3088
3089 <para>
3090 A good method to isolate changed configurations is to use a combination of the
3091 <filename>menuconfig</filename> tool and simple shell commands.
3092 Before changing configurations with <filename>menuconfig</filename>, copy the
3093 existing <filename>.config</filename> and rename it to something else,
3094 use <filename>menuconfig</filename> to make
3095 as many changes as you want and save them, then compare the renamed configuration
3096 file against the newly created file.
3097 You can use the resulting differences as your base to create configuration fragments
3098 to permanently save in your kernel layer.
3099 <note>
3100 Be sure to make a copy of the <filename>.config</filename> and don't just
3101 rename it.
3102 The build system needs an existing <filename>.config</filename>
3103 from which to work.
3104 </note>
3105 </para>
3106 </section>
3107
3108 <section id='creating-config-fragments'>
3109 <title>Creating Configuration Fragments</title>
3110
3111 <para>
3112 Configuration fragments are simply kernel options that appear in a file
3113 placed where the OpenEmbedded build system can find and apply them.
3114 Syntactically, the configuration statement is identical to what would appear
3115 in the <filename>.config</filename> file, which is in the
3116 <link linkend='build-directory'>Build Directory</link> in
3117 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
3118 </para>
3119
3120 <para>
3121 It is simple to create a configuration fragment.
3122 For example, issuing the following from the shell creates a configuration fragment
3123 file named <filename>my_smp.cfg</filename> that enables multi-processor support
3124 within the kernel:
3125 <literallayout class='monospaced'>
3126 $ echo "CONFIG_SMP=y" >> my_smp.cfg
3127 </literallayout>
3128 <note>
3129 All configuration files must use the <filename>.cfg</filename> extension in order
3130 for the OpenEmbedded build system to recognize them as a configuration fragment.
3131 </note>
3132 </para>
3133
3134 <para>
3135 Where do you put your configuration files?
3136 You can place these configuration files in the same area pointed to by
3137 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3138 The OpenEmbedded build system will pick up the configuration and add it to the
3139 kernel's configuration.
3140 For example, suppose you had a set of configuration options in a file called
3141 <filename>myconfig.cfg</filename>.
3142 If you put that file inside a directory named <filename>linux-yocto</filename>
3143 that resides in the same directory as the kernel's append file and then add
3144 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
3145 those configuration options will be picked up and applied when the kernel is built.
3146 <literallayout class='monospaced'>
3147 SRC_URI += "file://myconfig.cfg"
3148 </literallayout>
3149 </para>
3150
3151 <para>
3152 As mentioned earlier, you can group related configurations into multiple files and
3153 name them all in the <filename>SRC_URI</filename> statement as well.
3154 For example, you could group separate configurations specifically for Ethernet and graphics
3155 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
3156 following in your append file:
3157 <literallayout class='monospaced'>
3158 SRC_URI += "file://myconfig.cfg \
3159 file://eth.cfg \
3160 file://gfx.cfg"
3161 </literallayout>
3162 </para>
3163 </section>
3164
3165 <section id='fine-tuning-the-kernel-configuration-file'>
3166 <title>Fine-Tuning the Kernel Configuration File</title>
3167
3168 <para>
3169 You can make sure the <filename>.config</filename> file is as lean or efficient as
3170 possible by reading the output of the kernel configuration fragment audit,
3171 noting any issues, making changes to correct the issues, and then repeating.
3172 </para>
3173
3174 <para>
3175 As part of the kernel build process, the
3176 <filename>kernel_configcheck</filename> task runs.
3177 This task validates the kernel configuration by checking the final
3178 <filename>.config</filename> file against the input files.
3179 During the check, the task produces warning messages for the following
3180 issues:
3181 <itemizedlist>
3182 <listitem><para>Requested options that did not make the final
3183 <filename>.config</filename> file.</para></listitem>
3184 <listitem><para>Configuration items that appear twice in the same
3185 configuration fragment.</para></listitem>
3186 <listitem><para>Configuration items tagged as "required" that were overridden.
3187 </para></listitem>
3188 <listitem><para>A board overrides a non-board specific option.</para></listitem>
3189 <listitem><para>Listed options not valid for the kernel being processed.
3190 In other words, the option does not appear anywhere.</para></listitem>
3191 </itemizedlist>
3192 <note>
3193 The <filename>kernel_configcheck</filename> task can also optionally report
3194 if an option is overridden during processing.
3195 </note>
3196 </para>
3197
3198 <para>
3199 For each output warning, a message points to the file
3200 that contains a list of the options and a pointer to the config
3201 fragment that defines them.
3202 Collectively, the files are the key to streamlining the configuration.
3203 </para>
3204
3205 <para>
3206 To streamline the configuration, do the following:
3207 <orderedlist>
3208 <listitem><para>Start with a full configuration that you know
3209 works - it builds and boots successfully.
3210 This configuration file will be your baseline.</para></listitem>
3211 <listitem><para>Separately run the <filename>configme</filename> and
3212 <filename>kernel_configcheck</filename> tasks.</para></listitem>
3213 <listitem><para>Take the resulting list of files from the
3214 <filename>kernel_configcheck</filename> task warnings and do the following:
3215 <itemizedlist>
3216 <listitem><para>Drop values that are redefined in the fragment but do not
3217 change the final <filename>.config</filename> file.</para></listitem>
3218 <listitem><para>Analyze and potentially drop values from the
3219 <filename>.config</filename> file that override required
3220 configurations.</para></listitem>
3221 <listitem><para>Analyze and potentially remove non-board specific options.
3222 </para></listitem>
3223 <listitem><para>Remove repeated and invalid options.</para></listitem>
3224 </itemizedlist></para></listitem>
3225 <listitem><para>After you have worked through the output of the kernel configuration
3226 audit, you can re-run the <filename>configme</filename>
3227 and <filename>kernel_configcheck</filename> tasks to see the results of your
3228 changes.
3229 If you have more issues, you can deal with them as described in the
3230 previous step.</para></listitem>
3231 </orderedlist>
3232 </para>
3233
3234 <para>
3235 Iteratively working through steps two through four eventually yields
3236 a minimal, streamlined configuration file.
3237 Once you have the best <filename>.config</filename>, you can build the Linux
3238 Yocto kernel.
3239 </para>
3240 </section>
3241 </section>
3242
3243 <section id="patching-the-kernel">
3244 <title>Patching the Kernel</title>
3245
3246 <para>
3247 Patching the kernel involves changing or adding configurations to an existing kernel,
3248 changing or adding recipes to the kernel that are needed to support specific hardware features,
3249 or even altering the source code itself.
3250 <note>
3251 You can use the <filename>yocto-kernel</filename> script
3252 found in the <link linkend='source-directory'>Source Directory</link>
3253 under <filename>scripts</filename> to manage kernel patches and configuration.
3254 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>"
3255 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
3256 more information.</note>
3257 </para>
3258
3259 <para>
3260 This example creates a simple patch by adding some QEMU emulator console
3261 output at boot time through <filename>printk</filename> statements in the kernel's
3262 <filename>calibrate.c</filename> source code file.
3263 Applying the patch and booting the modified image causes the added
3264 messages to appear on the emulator's console.
3265 </para>
3266
3267 <para>
3268 The example assumes a clean build exists for the <filename>qemux86</filename>
3269 machine in a
3270 <link linkend='source-directory'>Source Directory</link>
3271 named <filename>poky</filename>.
3272 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
3273 <filename>build</filename> and is located in <filename>poky</filename> and
3274 the kernel is based on the Linux 3.4 kernel.
3275 For general information on how to configure the most efficient build, see the
3276 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
3277 in the Yocto Project Quick Start.
3278 </para>
3279
3280 <para>
3281 Also, for more information on patching the kernel, see the
3282 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
3283 section in the Yocto Project Linux Kernel Development Manual.
3284 </para>
3285
3286 <section id='create-a-layer-for-your-changes'>
3287 <title>Create a Layer for your Changes</title>
3288
3289 <para>
3290 The first step is to create a layer so you can isolate your
3291 changes.
3292 Rather than use the <filename>yocto-layer</filename> script
3293 to create the layer, this example steps through the process
3294 by hand.
3295 If you want information on the script that creates a general
3296 layer, see the
3297 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3298 section.
3299 </para>
3300
3301 <para>
3302 These two commands create a directory you can use for your
3303 layer:
3304 <literallayout class='monospaced'>
3305 $ cd ~/poky
3306 $ mkdir meta-mylayer
3307 </literallayout>
3308 Creating a directory that follows the Yocto Project layer naming
3309 conventions sets up the layer for your changes.
3310 The layer is where you place your configuration files, append
3311 files, and patch files.
3312 To learn more about creating a layer and filling it with the
3313 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
3314 and Creating Layers</link>" section.
3315 </para>
3316 </section>
3317
3318 <section id='finding-the-kernel-source-code'>
3319 <title>Finding the Kernel Source Code</title>
3320
3321 <para>
3322 Each time you build a kernel image, the kernel source code is fetched
3323 and unpacked into the following directory:
3324 <literallayout class='monospaced'>
3325 ${S}/linux
3326 </literallayout>
3327 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
3328 section and the
3329 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
3330 for more information about where source is kept during a build.
3331 </para>
3332
3333 <para>
3334 For this example, we are going to patch the
3335 <filename>init/calibrate.c</filename> file
3336 by adding some simple console <filename>printk</filename> statements that we can
3337 see when we boot the image using QEMU.
3338 </para>
3339 </section>
3340
3341 <section id='creating-the-patch'>
3342 <title>Creating the Patch</title>
3343
3344 <para>
3345 Two methods exist by which you can create the patch:
3346 <link linkend='using-a-git-workflow'>Git workflow</link> and
3347 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
3348 For kernel patches, the Git workflow is more appropriate.
3349 This section assumes the Git workflow and shows the steps specific to
3350 this example.
3351 <orderedlist>
3352 <listitem><para><emphasis>Change the working directory</emphasis>:
3353 Change to where the kernel source code is before making
3354 your edits to the <filename>calibrate.c</filename> file:
3355 <literallayout class='monospaced'>
3356 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
3357 </literallayout>
3358 Because you are working in an established Git repository,
3359 you must be in this directory in order to commit your changes
3360 and create the patch file.
3361 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
3362 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
3363 represent the version and revision for the
3364 <filename>linux-yocto</filename> recipe.
3365 The <filename>PV</filename> variable includes the Git meta and machine
3366 hashes, which make the directory name longer than you might
3367 expect.
3368 </note></para></listitem>
3369 <listitem><para><emphasis>Edit the source file</emphasis>:
3370 Edit the <filename>init/calibrate.c</filename> file to have the
3371 following changes:
3372 <literallayout class='monospaced'>
3373 void calibrate_delay(void)
3374 {
3375 unsigned long lpj;
3376 static bool printed;
3377 int this_cpu = smp_processor_id();
3378
3379 printk("*************************************\n");
3380 printk("* *\n");
3381 printk("* HELLO YOCTO KERNEL *\n");
3382 printk("* *\n");
3383 printk("*************************************\n");
3384
3385 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
3386 .
3387 .
3388 .
3389 </literallayout></para></listitem>
3390 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
3391 These Git commands display the modified file, stage it, and then
3392 commit the file:
3393 <literallayout class='monospaced'>
3394 $ git status
3395 $ git add init/calibrate.c
3396 $ git commit -m "calibrate: Add printk example"
3397 </literallayout></para></listitem>
3398 <listitem><para><emphasis>Generate the patch file</emphasis>:
3399 This Git command creates the a patch file named
3400 <filename>0001-calibrate-Add-printk-example.patch</filename>
3401 in the current directory.
3402 <literallayout class='monospaced'>
3403 $ git format-patch -1
3404 </literallayout>
3405 </para></listitem>
3406 </orderedlist>
3407 </para>
3408 </section>
3409
3410 <section id='set-up-your-layer-for-the-build'>
3411 <title>Set Up Your Layer for the Build</title>
3412
3413 <para>These steps get your layer set up for the build:
3414 <orderedlist>
3415 <listitem><para><emphasis>Create additional structure</emphasis>:
3416 Create the additional layer structure:
3417 <literallayout class='monospaced'>
3418 $ cd ~/poky/meta-mylayer
3419 $ mkdir conf
3420 $ mkdir recipes-kernel
3421 $ mkdir recipes-kernel/linux
3422 $ mkdir recipes-kernel/linux/linux-yocto
3423 </literallayout>
3424 The <filename>conf</filename> directory holds your configuration files, while the
3425 <filename>recipes-kernel</filename> directory holds your append file and
3426 your patch file.</para></listitem>
3427 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
3428 Move to the <filename>meta-mylayer/conf</filename> directory and create
3429 the <filename>layer.conf</filename> file as follows:
3430 <literallayout class='monospaced'>
3431 # We have a conf and classes directory, add to BBPATH
3432 BBPATH .= ":${LAYERDIR}"
3433
3434 # We have recipes-* directories, add to BBFILES
3435 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
3436 ${LAYERDIR}/recipes-*/*/*.bbappend"
3437
3438 BBFILE_COLLECTIONS += "mylayer"
3439 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
3440 BBFILE_PRIORITY_mylayer = "5"
3441 </literallayout>
3442 Notice <filename>mylayer</filename> as part of the last three
3443 statements.</para></listitem>
3444 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
3445 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
3446 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
3447 <literallayout class='monospaced'>
3448 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3449
3450 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
3451 </literallayout>
3452 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
3453 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
3454 statements enable the OpenEmbedded build system to find the patch file.
3455 For more information on using append files, see the
3456 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3457 section.
3458 </para></listitem>
3459 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
3460 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
3461 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
3462 directory.</para></listitem>
3463 </orderedlist>
3464 </para>
3465 </section>
3466
3467 <section id='set-up-for-the-build'>
3468 <title>Set Up for the Build</title>
3469
3470 <para>
3471 Do the following to make sure the build parameters are set up for the example.
3472 Once you set up these build parameters, they do not have to change unless you
3473 change the target architecture of the machine you are building:
3474 <itemizedlist>
3475 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
3476 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3477 definition within the <filename>local.conf</filename> file in the
3478 <link linkend='build-directory'>Build Directory</link>
3479 specifies the target architecture used when building the Linux kernel.
3480 By default, <filename>MACHINE</filename> is set to
3481 <filename>qemux86</filename>, which specifies a 32-bit
3482 <trademark class='registered'>Intel</trademark> Architecture
3483 target machine suitable for the QEMU emulator.</para></listitem>
3484 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
3485 layer:</emphasis> The
3486 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
3487 variable in the
3488 <filename>bblayers.conf</filename> file found in the
3489 <filename>poky/build/conf</filename> directory needs to have the path to your local
3490 <filename>meta-mylayer</filename> layer.
3491 By default, the <filename>BBLAYERS</filename> variable contains paths to
3492 <filename>meta</filename>, <filename>meta-yocto</filename>, and
3493 <filename>meta-yocto-bsp</filename> in the
3494 <filename>poky</filename> Git repository.
3495 Add the path to your <filename>meta-mylayer</filename> location:
3496 <literallayout class='monospaced'>
3497 BBLAYERS ?= " \
3498 $HOME/poky/meta \
3499 $HOME/poky/meta-yocto \
3500 $HOME/poky/meta-yocto-bsp \
3501 $HOME/poky/meta-mylayer \
3502 "
3503
3504 BBLAYERS_NON_REMOVABLE ?= " \
3505 $HOME/poky/meta \
3506 $HOME/poky/meta-yocto \
3507 "
3508 </literallayout></para></listitem>
3509 </itemizedlist>
3510 </para>
3511 </section>
3512
3513 <section id='build-the-modified-qemu-kernel-image'>
3514 <title>Build the Modified QEMU Kernel Image</title>
3515
3516 <para>
3517 The following steps build your modified kernel image:
3518 <orderedlist>
3519 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
3520 Your environment should be set up since you previously sourced
3521 the
3522 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3523 script.
3524 If it is not, source the script again from <filename>poky</filename>.
3525 <literallayout class='monospaced'>
3526 $ cd ~/poky
3527 $ source &OE_INIT_FILE;
3528 </literallayout>
3529 </para></listitem>
3530 <listitem><para><emphasis>Clean up</emphasis>:
3531 Be sure to clean the shared state out by running the
3532 <filename>cleansstate</filename> BitBake task as follows from your Build Directory:
3533 <literallayout class='monospaced'>
3534 $ bitbake -c cleansstate linux-yocto
3535 </literallayout></para>
3536 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
3537 directory inside the
3538 <link linkend='build-directory'>Build Directory</link>.
3539 Always use the various BitBake clean tasks to clear out previous
3540 build artifacts.
3541 </note></para></listitem>
3542 <listitem><para><emphasis>Build the image</emphasis>:
3543 Next, build the kernel image using this command:
3544 <literallayout class='monospaced'>
3545 $ bitbake -k linux-yocto
3546 </literallayout></para></listitem>
3547 </orderedlist>
3548 </para>
3549 </section>
3550
3551 <section id='boot-the-image-and-verify-your-changes'>
3552 <title>Boot the Image and Verify Your Changes</title>
3553
3554 <para>
3555 These steps boot the image and allow you to see the changes
3556 <orderedlist>
3557 <listitem><para><emphasis>Boot the image</emphasis>:
3558 Boot the modified image in the QEMU emulator
3559 using this command:
3560 <literallayout class='monospaced'>
3561 $ runqemu qemux86
3562 </literallayout></para></listitem>
3563 <listitem><para><emphasis>Verify the changes</emphasis>:
3564 Log into the machine using <filename>root</filename> with no password and then
3565 use the following shell command to scroll through the console's boot output.
3566 <literallayout class='monospaced'>
3567 # dmesg | less
3568 </literallayout>
3569 You should see the results of your <filename>printk</filename> statements
3570 as part of the output.</para></listitem>
3571 </orderedlist>
3572 </para>
3573 </section>
3574 </section>
3575
3576 <section id='making-images-more-secure'>
3577 <title>Making Images More Secure</title>
3578
3579 <para>
3580 The Yocto Project has security flags that you can enable that
3581 help make your build output more secure.
3582 The security flags are in the
3583 <filename>meta/conf/distro/include/security_flags.inc</filename>
3584 file in your
3585 <link linkend='source-directory'>Source Directory</link>
3586 (e.g. <filename>poky</filename>).
3587 </para>
3588
3589 <para>
3590 These GCC/LD flags enable more secure code generation.
3591 By including the <filename>security_flags.inc</filename>
3592 file, you enable flags to the compiler and linker that cause
3593 them to generate more secure code.
3594 <note>
3595 These flags are enabled by default in the
3596 <filename>poky-lsb</filename> distribution.
3597 </note>
3598 Use the following line in your
3599 <filename>local.conf</filename> file
3600 to enable the security compiler and
3601 linker flags to your build:
3602 <literallayout class='monospaced'>
3603 require conf/distro/include/security_flags.inc
3604 </literallayout>
3605 </para>
3606 </section>
3607
3608 <section id='creating-your-own-distribution'>
3609 <title>Creating Your Own Distribution</title>
3610
3611 <para>
3612 When you build an image using the Yocto Project and
3613 do not alter any distribution
3614 <link linkend='metadata'>Metadata</link>, you are creating a
3615 Poky distribution.
3616 If you wish to gain more control over package alternative
3617 selections, compile-time options, and other low-level
3618 configurations, you can create your own distribution.
3619 </para>
3620
3621 <para>
3622 To create your own distribution, the basic steps consist of
3623 creating your own distribution layer, creating your own
3624 distribution configuration file, and then adding any needed
3625 code and Metadata to the layer.
3626 The following steps provide some more detail:
3627 <itemizedlist>
3628 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
3629 Create your distribution layer so that you can keep your
3630 Metadata and code for the distribution separate.
3631 It is strongly recommended that you create and use your own
3632 layer for configuration and code.
3633 Using your own layer as compared to just placing
3634 configurations in a <filename>local.conf</filename>
3635 configuration file makes it easier to reproduce the same
3636 build configuration when using multiple build machines.
3637 See the
3638 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3639 section for information on how to quickly set up a layer.
3640 </para></listitem>
3641 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
3642 The distribution configuration file needs to be created in
3643 the <filename>conf/distro</filename> directory of your
3644 layer.
3645 You need to name it using your distribution name
3646 (e.g. <filename>mydistro.conf</filename>).
3647 <note>
3648 The
3649 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3650 variable in your
3651 <filename>local.conf</filename> file determines the
3652 name of your distribution.
3653 </note></para>
3654 <para>You can split out parts of your configuration file
3655 into include files and then "require" them from within
3656 your distribution configuration file.
3657 Be sure to place the include files in the
3658 <filename>conf/distro/include</filename> directory of
3659 your layer.
3660 A common example usage of include files would be to
3661 separate out the selection of desired version and revisions
3662 for individual recipes.
3663</para>
3664 <para>Your configuration file needs to set the following
3665 required variables:
3666 <literallayout class='monospaced'>
3667 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
3668 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
3669 </literallayout>
3670 These following variables are optional and you typically
3671 set them from the distribution configuration file:
3672 <literallayout class='monospaced'>
3673 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3674 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
3675 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
3676 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
3677 </literallayout>
3678 <tip>
3679 If you want to base your distribution configuration file
3680 on the very basic configuration from OE-Core, you
3681 can use
3682 <filename>conf/distro/defaultsetup.conf</filename> as
3683 a reference and just include variables that differ
3684 as compared to <filename>defaultsetup.conf</filename>.
3685 Alternatively, you can create a distribution
3686 configuration file from scratch using the
3687 <filename>defaultsetup.conf</filename> file
3688 or configuration files from other distributions
3689 such as Poky or Angstrom as references.
3690 </tip></para></listitem>
3691 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
3692 Be sure to define any other variables for which you want to
3693 create a default or enforce as part of the distribution
3694 configuration.
3695 You can include nearly any variable from the
3696 <filename>local.conf</filename> file.
3697 The variables you use are not limited to the list in the
3698 previous bulleted item.</para></listitem>
3699 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
3700 In your <filename>local.conf</filename> file in the
3701 <link linkend='build-directory'>Build Directory</link>,
3702 set your
3703 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3704 variable to point to your distribution's configuration file.
3705 For example, if your distribution's configuration file is
3706 named <filename>mydistro.conf</filename>, then you point
3707 to it as follows:
3708 <literallayout class='monospaced'>
3709 DISTRO = "mydistro"
3710 </literallayout></para></listitem>
3711 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
3712 Use your layer to hold other information needed for the
3713 distribution:
3714 <itemizedlist>
3715 <listitem><para>Add recipes for installing
3716 distro-specific configuration files that are not
3717 already installed by another recipe.
3718 If you have distro-specific configuration files
3719 that are included by an existing recipe, you should
3720 add an append file (<filename>.bbappend</filename>)
3721 for those.
3722 For general information and recommendations
3723 on how to add recipes to your layer, see the
3724 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
3725 and
3726 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
3727 sections.</para></listitem>
3728 <listitem><para>Add any image recipes that are specific
3729 to your distribution.</para></listitem>
3730 <listitem><para>Add a <filename>psplash</filename>
3731 append file for a branded splash screen.
3732 For information on append files, see the
3733 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3734 section.</para></listitem>
3735 <listitem><para>Add any other append files to make
3736 custom changes that are specific to individual
3737 recipes.</para></listitem>
3738 </itemizedlist></para></listitem>
3739 </itemizedlist>
3740 </para>
3741 </section>
3742
3743 <section id='building-a-tiny-system'>
3744 <title>Building a Tiny System</title>
3745
3746 <para>
3747 Very small distributions have some significant advantages such
3748 as requiring less on-die or in-package memory (cheaper), better
3749 performance through efficient cache usage, lower power requirements
3750 due to less memory, faster boot times, and reduced development
3751 overhead.
3752 Some real-world examples where a very small distribution gives
3753 you distinct advantages are digital cameras, medical devices,
3754 and small headless systems.
3755 </para>
3756
3757 <para>
3758 This section presents information that shows you how you can
3759 trim your distribution to even smaller sizes than the
3760 <filename>poky-tiny</filename> distribution, which is around
3761 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
3762 </para>
3763
3764 <section id='tiny-system-overview'>
3765 <title>Overview</title>
3766
3767 <para>
3768 The following list presents the overall steps you need to
3769 consider and perform to create distributions with smaller
3770 root filesystems, achieve faster boot times, maintain your critical
3771 functionality, and avoid initial RAM disks:
3772 <itemizedlist>
3773 <listitem><para>
3774 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
3775 </para></listitem>
3776 <listitem><para>
3777 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
3778 </para></listitem>
3779 <listitem><para>
3780 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
3781 </para></listitem>
3782 <listitem><para>
3783 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
3784 </para></listitem>
3785 <listitem><para>
3786 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
3787 </para></listitem>
3788 <listitem><para>
3789 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
3790 </para></listitem>
3791 <listitem><para>
3792 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
3793 </para></listitem>
3794 </itemizedlist>
3795 </para>
3796 </section>
3797
3798 <section id='goals-and-guiding-principles'>
3799 <title>Goals and Guiding Principles</title>
3800
3801 <para>
3802 Before you can reach your destination, you need to know
3803 where you are going.
3804 Here is an example list that you can use as a guide when
3805 creating very small distributions:
3806 <itemizedlist>
3807 <listitem><para>Determine how much space you need
3808 (e.g. a kernel that is 1 Mbyte or less and
3809 a root filesystem that is 3 Mbytes or less).
3810 </para></listitem>
3811 <listitem><para>Find the areas that are currently
3812 taking 90% of the space and concentrate on reducing
3813 those areas.
3814 </para></listitem>
3815 <listitem><para>Do not create any difficult "hacks"
3816 to achieve your goals.</para></listitem>
3817 <listitem><para>Leverage the device-specific
3818 options.</para></listitem>
3819 <listitem><para>Work in a separate layer so that you
3820 keep changes isolated.
3821 For information on how to create layers, see
3822 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
3823 </para></listitem>
3824 </itemizedlist>
3825 </para>
3826 </section>
3827
3828 <section id='understand-what-gives-your-image-size'>
3829 <title>Understand What Contributes to Your Image Size</title>
3830
3831 <para>
3832 It is easiest to have something to start with when creating
3833 your own distribution.
3834 You can use the Yocto Project out-of-the-box to create the
3835 <filename>poky-tiny</filename> distribution.
3836 Ultimately, you will want to make changes in your own
3837 distribution that are likely modeled after
3838 <filename>poky-tiny</filename>.
3839 <note>
3840 To use <filename>poky-tiny</filename> in your build,
3841 set the
3842 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3843 variable in your
3844 <filename>local.conf</filename> file to "poky-tiny"
3845 as described in the
3846 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
3847 section.
3848 </note>
3849 </para>
3850
3851 <para>
3852 Understanding some memory concepts will help you reduce the
3853 system size.
3854 Memory consists of static, dynamic, and temporary memory.
3855 Static memory is the TEXT (code), DATA (initialized data
3856 in the code), and BSS (uninitialized data) sections.
3857 Dynamic memory represents memory that is allocated at runtime:
3858 stacks, hash tables, and so forth.
3859 Temporary memory is recovered after the boot process.
3860 This memory consists of memory used for decompressing
3861 the kernel and for the <filename>__init__</filename>
3862 functions.
3863 </para>
3864
3865 <para>
3866 To help you see where you currently are with kernel and root
3867 filesystem sizes, you can use two tools found in the
3868 <link linkend='source-directory'>Source Directory</link> in
3869 the <filename>scripts/tiny/</filename> directory:
3870 <itemizedlist>
3871 <listitem><para><filename>ksize.py</filename>: Reports
3872 component sizes for the kernel build objects.
3873 </para></listitem>
3874 <listitem><para><filename>dirsize.py</filename>: Reports
3875 component sizes for the root filesystem.</para></listitem>
3876 </itemizedlist>
3877 This next tool and command help you organize configuration
3878 fragments and view file dependencies in a human-readable form:
3879 <itemizedlist>
3880 <listitem><para><filename>merge_config.sh</filename>:
3881 Helps you manage configuration files and fragments
3882 within the kernel.
3883 With this tool, you can merge individual configuration
3884 fragments together.
3885 The tool allows you to make overrides and warns you
3886 of any missing configuration options.
3887 The tool is ideal for allowing you to iterate on
3888 configurations, create minimal configurations, and
3889 create configuration files for different machines
3890 without having to duplicate your process.</para>
3891 <para>The <filename>merge_config.sh</filename> script is
3892 part of the Linux Yocto kernel Git repositories
3893 (i.e. <filename>linux-yocto-3.14</filename>,
3894 <filename>linux-yocto-3.10</filename>,
3895 <filename>linux-yocto-3.8</filename>, and so forth)
3896 in the
3897 <filename>scripts/kconfig</filename> directory.</para>
3898 <para>For more information on configuration fragments,
3899 see the
3900 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
3901 section of the Yocto Project Linux Kernel Development
3902 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
3903 section, which is in this manual.</para></listitem>
3904 <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
3905 Using the BitBake command with these options brings up
3906 a Dependency Explorer from which you can view file
3907 dependencies.
3908 Understanding these dependencies allows you to make
3909 informed decisions when cutting out various pieces of the
3910 kernel and root filesystem.</para></listitem>
3911 </itemizedlist>
3912 </para>
3913 </section>
3914
3915 <section id='trim-the-root-filesystem'>
3916 <title>Trim the Root Filesystem</title>
3917
3918 <para>
3919 The root filesystem is made up of packages for booting,
3920 libraries, and applications.
3921 To change things, you can configure how the packaging happens,
3922 which changes the way you build them.
3923 You can also tweak the filesystem itself or select a different
3924 filesystem.
3925 </para>
3926
3927 <para>
3928 First, find out what is hogging your root filesystem by running the
3929 <filename>dirsize.py</filename> script from your root directory:
3930 <literallayout class='monospaced'>
3931 $ cd &lt;root-directory-of-image&gt;
3932 $ dirsize.py 100000 > dirsize-100k.log
3933 $ cat dirsize-100k.log
3934 </literallayout>
3935 You can apply a filter to the script to ignore files under
3936 a certain size.
3937 The previous example filters out any files below 100 Kbytes.
3938 The sizes reported by the tool are uncompressed, and thus
3939 will be smaller by a relatively constant factor in a
3940 compressed root filesystem.
3941 When you examine your log file, you can focus on areas of the
3942 root filesystem that take up large amounts of memory.
3943 </para>
3944
3945 <para>
3946 You need to be sure that what you eliminate does not cripple
3947 the functionality you need.
3948 One way to see how packages relate to each other is by using
3949 the Dependency Explorer UI with the BitBake command:
3950 <literallayout class='monospaced'>
3951 $ cd &lt;image-directory&gt;
3952 $ bitbake -u depexp -g &lt;image&gt;
3953 </literallayout>
3954 Use the interface to select potential packages you wish to
3955 eliminate and see their dependency relationships.
3956 </para>
3957
3958 <para>
3959 When deciding how to reduce the size, get rid of packages that
3960 result in minimal impact on the feature set.
3961 For example, you might not need a VGA display.
3962 Or, you might be able to get by with <filename>devtmpfs</filename>
3963 and <filename>mdev</filename> instead of
3964 <filename>udev</filename>.
3965 </para>
3966
3967 <para>
3968 Use your <filename>local.conf</filename> file to make changes.
3969 For example, to eliminate <filename>udev</filename> and
3970 <filename>glib</filename>, set the following in the
3971 local configuration file:
3972 <literallayout class='monospaced'>
3973 VIRTUAL-RUNTIME_dev_manager = ""
3974 </literallayout>
3975 </para>
3976
3977 <para>
3978 Finally, you should consider exactly the type of root
3979 filesystem you need to meet your needs while also reducing
3980 its size.
3981 For example, consider <filename>cramfs</filename>,
3982 <filename>squashfs</filename>, <filename>ubifs</filename>,
3983 <filename>ext2</filename>, or an <filename>initramfs</filename>
3984 using <filename>initramfs</filename>.
3985 Be aware that <filename>ext3</filename> requires a 1 Mbyte
3986 journal.
3987 If you are okay with running read-only, you do not need this
3988 journal.
3989 </para>
3990
3991 <note>
3992 After each round of elimination, you need to rebuild your
3993 system and then use the tools to see the effects of your
3994 reductions.
3995 </note>
3996
3997
3998 </section>
3999
4000 <section id='trim-the-kernel'>
4001 <title>Trim the Kernel</title>
4002
4003 <para>
4004 The kernel is built by including policies for hardware-independent
4005 aspects.
4006 What subsystems do you enable?
4007 For what architecture are you building?
4008 Which drivers do you build by default?
4009 <note>You can modify the kernel source if you want to help
4010 with boot time.
4011 </note>
4012 </para>
4013
4014 <para>
4015 Run the <filename>ksize.py</filename> script from the top-level
4016 Linux build directory to get an idea of what is making up
4017 the kernel:
4018 <literallayout class='monospaced'>
4019 $ cd &lt;top-level-linux-build-directory&gt;
4020 $ ksize.py > ksize.log
4021 $ cat ksize.log
4022 </literallayout>
4023 When you examine the log, you will see how much space is
4024 taken up with the built-in <filename>.o</filename> files for
4025 drivers, networking, core kernel files, filesystem, sound,
4026 and so forth.
4027 The sizes reported by the tool are uncompressed, and thus
4028 will be smaller by a relatively constant factor in a compressed
4029 kernel image.
4030 Look to reduce the areas that are large and taking up around
4031 the "90% rule."
4032 </para>
4033
4034 <para>
4035 To examine, or drill down, into any particular area, use the
4036 <filename>-d</filename> option with the script:
4037 <literallayout class='monospaced'>
4038 $ ksize.py -d > ksize.log
4039 </literallayout>
4040 Using this option breaks out the individual file information
4041 for each area of the kernel (e.g. drivers, networking, and
4042 so forth).
4043 </para>
4044
4045 <para>
4046 Use your log file to see what you can eliminate from the kernel
4047 based on features you can let go.
4048 For example, if you are not going to need sound, you do not
4049 need any drivers that support sound.
4050 </para>
4051
4052 <para>
4053 After figuring out what to eliminate, you need to reconfigure
4054 the kernel to reflect those changes during the next build.
4055 You could run <filename>menuconfig</filename> and make all your
4056 changes at once.
4057 However, that makes it difficult to see the effects of your
4058 individual eliminations and also makes it difficult to replicate
4059 the changes for perhaps another target device.
4060 A better method is to start with no configurations using
4061 <filename>allnoconfig</filename>, create configuration
4062 fragments for individual changes, and then manage the
4063 fragments into a single configuration file using
4064 <filename>merge_config.sh</filename>.
4065 The tool makes it easy for you to iterate using the
4066 configuration change and build cycle.
4067 </para>
4068
4069 <para>
4070 Each time you make configuration changes, you need to rebuild
4071 the kernel and check to see what impact your changes had on
4072 the overall size.
4073 </para>
4074 </section>
4075
4076 <section id='remove-package-management-requirements'>
4077 <title>Remove Package Management Requirements</title>
4078
4079 <para>
4080 Packaging requirements add size to the image.
4081 One way to reduce the size of the image is to remove all the
4082 packaging requirements from the image.
4083 This reduction includes both removing the package manager
4084 and its unique dependencies as well as removing the package
4085 management data itself.
4086 </para>
4087
4088 <para>
4089 To eliminate all the packaging requirements for an image,
4090 be sure that "package-management" is not part of your
4091 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4092 statement for the image.
4093 When you remove this feature, you are removing the package
4094 manager as well as its dependencies from the root filesystem.
4095 </para>
4096 </section>
4097
4098 <section id='look-for-other-ways-to-minimize-size'>
4099 <title>Look for Other Ways to Minimize Size</title>
4100
4101 <para>
4102 Depending on your particular circumstances, other areas that you
4103 can trim likely exist.
4104 The key to finding these areas is through tools and methods
4105 described here combined with experimentation and iteration.
4106 Here are a couple of areas to experiment with:
4107 <itemizedlist>
4108 <listitem><para><filename>eglibc</filename>:
4109 In general, follow this process:
4110 <orderedlist>
4111 <listitem><para>Remove <filename>eglibc</filename>
4112 features from
4113 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4114 that you think you do not need.</para></listitem>
4115 <listitem><para>Build your distribution.
4116 </para></listitem>
4117 <listitem><para>If the build fails due to missing
4118 symbols in a package, determine if you can
4119 reconfigure the package to not need those
4120 features.
4121 For example, change the configuration to not
4122 support wide character support as is done for
4123 <filename>ncurses</filename>.
4124 Or, if support for those characters is needed,
4125 determine what <filename>eglibc</filename>
4126 features provide the support and restore the
4127 configuration.
4128 </para></listitem>
4129 <listitem><para>Rebuild and repeat the process.
4130 </para></listitem>
4131 </orderedlist></para></listitem>
4132 <listitem><para><filename>busybox</filename>:
4133 For BusyBox, use a process similar as described for
4134 <filename>eglibc</filename>.
4135 A difference is you will need to boot the resulting
4136 system to see if you are able to do everything you
4137 expect from the running system.
4138 You need to be sure to integrate configuration fragments
4139 into Busybox because BusyBox handles its own core
4140 features and then allows you to add configuration
4141 fragments on top.
4142 </para></listitem>
4143 </itemizedlist>
4144 </para>
4145 </section>
4146
4147 <section id='iterate-on-the-process'>
4148 <title>Iterate on the Process</title>
4149
4150 <para>
4151 If you have not reached your goals on system size, you need
4152 to iterate on the process.
4153 The process is the same.
4154 Use the tools and see just what is taking up 90% of the root
4155 filesystem and the kernel.
4156 Decide what you can eliminate without limiting your device
4157 beyond what you need.
4158 </para>
4159
4160 <para>
4161 Depending on your system, a good place to look might be
4162 Busybox, which provides a stripped down
4163 version of Unix tools in a single, executable file.
4164 You might be able to drop virtual terminal services or perhaps
4165 ipv6.
4166 </para>
4167 </section>
4168 </section>
4169
4170 <section id='working-with-packages'>
4171 <title>Working with Packages</title>
4172
4173 <para>
4174 This section describes a few tasks that involve packages:
4175 <itemizedlist>
4176 <listitem><para>
4177 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
4178 </para></listitem>
4179 <listitem><para>
4180 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
4181 </para></listitem>
4182 <listitem><para>
4183 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
4184 </para></listitem>
4185 <listitem><para>
4186 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
4187 </para></listitem>
4188 <listitem><para>
4189 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
4190 </para></listitem>
4191 <listitem><para>
4192 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
4193 </para></listitem>
4194 </itemizedlist>
4195 </para>
4196
4197 <section id='excluding-packages-from-an-image'>
4198 <title>Excluding Packages from an Image</title>
4199
4200 <para>
4201 You might find it necessary to prevent specific packages
4202 from being installed into an image.
4203 If so, you can use several variables to direct the build
4204 system to essentially ignore installing recommended packages
4205 or to not install a package at all.
4206 </para>
4207
4208 <para>
4209 The following list introduces variables you can use to
4210 prevent packages from being installed into your image.
4211 Each of these variables only works with IPK and RPM
4212 package types.
4213 Support for Debian packages does not exist.
4214 Also, you can use these variables from your
4215 <filename>local.conf</filename> file or attach them to a
4216 specific image recipe by using a recipe name override.
4217 For more detail on the variables, see the descriptions in the
4218 Yocto Project Reference Manual's glossary chapter.
4219 <itemizedlist>
4220 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
4221 Use this variable to specify "recommended-only"
4222 packages that you do not want installed.
4223 </para></listitem>
4224 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
4225 Use this variable to prevent all "recommended-only"
4226 packages from being installed.
4227 </para></listitem>
4228 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
4229 Use this variable to prevent specific packages from
4230 being installed regardless of whether they are
4231 "recommended-only" or not.
4232 You need to realize that the build process could
4233 fail with an error when you
4234 prevent the installation of a package whose presence
4235 is required by an installed package.
4236 </para></listitem>
4237 </itemizedlist>
4238 </para>
4239 </section>
4240
4241 <section id='incrementing-a-package-revision-number'>
4242 <title>Incrementing a Package Revision Number</title>
4243
4244 <para>
4245 If a committed change results in changing the package output,
4246 then the value of the
4247 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4248 variable needs to be increased (or "bumped").
4249 Increasing <filename>PR</filename> occurs one of two ways:
4250 <itemizedlist>
4251 <listitem><para>Automatically using a Package Revision
4252 Service (PR Service).</para></listitem>
4253 <listitem><para>Manually incrementing the
4254 <filename>PR</filename> variable.</para></listitem>
4255 </itemizedlist>
4256 </para>
4257
4258 <para>
4259 Given that one of the challenges any build system and its
4260 users face is how to maintain a package feed that is compatible
4261 with existing package manager applications such as
4262 RPM, APT, and OPKG, using an automated system is much
4263 preferred over a manual system.
4264 In either system, the main requirement is that version
4265 numbering increases in a linear fashion and that a number of
4266 version components exist that support that linear progression.
4267 </para>
4268
4269 <para>
4270 The following two sections provide information on the PR Service
4271 and on manual <filename>PR</filename> bumping.
4272 </para>
4273
4274 <section id='working-with-a-pr-service'>
4275 <title>Working With a PR Service</title>
4276
4277 <para>
4278 As mentioned, attempting to maintain revision numbers in the
4279 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4280 is error prone, inaccurate, and causes problems for people
4281 submitting recipes.
4282 Conversely, the PR Service automatically generates
4283 increasing numbers, particularly the revision field,
4284 which removes the human element.
4285 <note>
4286 For additional information on using a PR Service, you
4287 can see the
4288 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
4289 wiki page.
4290 </note>
4291 </para>
4292
4293 <para>
4294 The Yocto Project uses variables in order of
4295 decreasing priority to facilitate revision numbering (i.e.
4296 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
4297 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
4298 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4299 for epoch, version, and revision, respectively).
4300 The values are highly dependent on the policies and
4301 procedures of a given distribution and package feed.
4302 </para>
4303
4304 <para>
4305 Because the OpenEmbedded build system uses
4306 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
4307 which are unique to a given build, the build system
4308 knows when to rebuild packages.
4309 All the inputs into a given task are represented by a
4310 signature, which can trigger a rebuild when different.
4311 Thus, the build system itself does not rely on the
4312 <filename>PR</filename> numbers to trigger a rebuild.
4313 The signatures, however, can be used to generate
4314 <filename>PR</filename> values.
4315 </para>
4316
4317 <para>
4318 The PR Service works with both
4319 <filename>OEBasic</filename> and
4320 <filename>OEBasicHash</filename> generators.
4321 The value of <filename>PR</filename> bumps when the
4322 checksum changes and the different generator mechanisms
4323 change signatures under different circumstances.
4324 </para>
4325
4326 <para>
4327 As implemented, the build system includes values from
4328 the PR Service into the <filename>PR</filename> field as
4329 an addition using the form "<filename>.x</filename>" so
4330 <filename>r0</filename> becomes <filename>r0.1</filename>,
4331 <filename>r0.2</filename> and so forth.
4332 This scheme allows existing <filename>PR</filename> values
4333 to be used for whatever reasons, which include manual
4334 <filename>PR</filename> bumps, should it be necessary.
4335 </para>
4336
4337 <para>
4338 By default, the PR Service is not enabled or running.
4339 Thus, the packages generated are just "self consistent".
4340 The build system adds and removes packages and
4341 there are no guarantees about upgrade paths but images
4342 will be consistent and correct with the latest changes.
4343 </para>
4344
4345 <para>
4346 The simplest form for a PR Service is for it to exist
4347 for a single host development system that builds the
4348 package feed (building system).
4349 For this scenario, you can enable a local PR Service by
4350 setting
4351 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
4352 in your <filename>local.conf</filename> file in the
4353 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4354 <literallayout class='monospaced'>
4355 PRSERV_HOST = "localhost:0"
4356 </literallayout>
4357 Once the service is started, packages will automatically
4358 get increasing <filename>PR</filename> values and
4359 BitBake will take care of starting and stopping the server.
4360 </para>
4361
4362 <para>
4363 If you have a more complex setup where multiple host
4364 development systems work against a common, shared package
4365 feed, you have a single PR Service running and it is
4366 connected to each building system.
4367 For this scenario, you need to start the PR Service using
4368 the <filename>bitbake-prserv</filename> command:
4369 <literallayout class='monospaced'>
4370 bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
4371 </literallayout>
4372 In addition to hand-starting the service, you need to
4373 update the <filename>local.conf</filename> file of each
4374 building system as described earlier so each system
4375 points to the server and port.
4376 </para>
4377
4378 <para>
4379 It is also recommended you use build history, which adds
4380 some sanity checks to package versions, in conjunction with
4381 the server that is running the PR Service.
4382 To enable build history, add the following to each building
4383 system's <filename>local.conf</filename> file:
4384 <literallayout class='monospaced'>
4385 # It is recommended to activate "buildhistory" for testing the PR service
4386 INHERIT += "buildhistory"
4387 BUILDHISTORY_COMMIT = "1"
4388 </literallayout>
4389 For information on build history, see the
4390 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
4391 section in the Yocto Project Reference Manual.
4392 </para>
4393
4394 <note>
4395 <para>The OpenEmbedded build system does not maintain
4396 <filename>PR</filename> information as part of the
4397 shared state (sstate) packages.
4398 If you maintain an sstate feed, its expected that either
4399 all your building systems that contribute to the sstate
4400 feed use a shared PR Service, or you do not run a PR
4401 Service on any of your building systems.
4402 Having some systems use a PR Service while others do
4403 not leads to obvious problems.</para>
4404 <para>For more information on shared state, see the
4405 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
4406 section in the Yocto Project Reference Manual.</para>
4407 </note>
4408 </section>
4409
4410 <section id='manually-bumping-pr'>
4411 <title>Manually Bumping PR</title>
4412
4413 <para>
4414 The alternative to setting up a PR Service is to manually
4415 bump the
4416 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4417 variable.
4418 </para>
4419
4420 <para>
4421 If a committed change results in changing the package output,
4422 then the value of the PR variable needs to be increased
4423 (or "bumped") as part of that commit.
4424 For new recipes you should add the <filename>PR</filename>
4425 variable and set its initial value equal to "r0", which is the default.
4426 Even though the default value is "r0", the practice of adding it to a new recipe makes
4427 it harder to forget to bump the variable when you make changes
4428 to the recipe in future.
4429 </para>
4430
4431 <para>
4432 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
4433 you can also use the
4434 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
4435 variable to ensure that
4436 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
4437 <filename>.inc</filename> file itself is changed.
4438 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
4439 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
4440 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
4441 If the <filename>.inc</filename> file is changed then its
4442 <filename>INC_PR</filename> should be incremented.
4443 </para>
4444
4445 <para>
4446 When upgrading the version of a package, assuming the
4447 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
4448 changes, the <filename>PR</filename> variable should be
4449 reset to "r0" (or "$(INC_PR).0" if you are using
4450 <filename>INC_PR</filename>).
4451 </para>
4452
4453 <para>
4454 Usually, version increases occur only to packages.
4455 However, if for some reason <filename>PV</filename> changes but does not
4456 increase, you can increase the
4457 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
4458 variable (Package Epoch).
4459 The <filename>PE</filename> variable defaults to "0".
4460 </para>
4461
4462 <para>
4463 Version numbering strives to follow the
4464 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
4465 Debian Version Field Policy Guidelines</ulink>.
4466 These guidelines define how versions are compared and what "increasing" a version means.
4467 </para>
4468 </section>
4469 </section>
4470
4471 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
4472 <title>Handling a Package Name Alias</title>
4473 <para>
4474 Sometimes a package name you are using might exist under an alias or as a similarly named
4475 package in a different distribution.
4476 The OpenEmbedded build system implements a <filename>distro_check</filename>
4477 task that automatically connects to major distributions
4478 and checks for these situations.
4479 If the package exists under a different name in a different distribution, you get a
4480 <filename>distro_check</filename> mismatch.
4481 You can resolve this problem by defining a per-distro recipe name alias using the
4482 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
4483 variable.
4484 </para>
4485
4486 <para>
4487 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
4488 variable:
4489 <literallayout class='monospaced'>
4490 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
4491 distro2=package_name_alias2 \
4492 distro3=package_name_alias3 \
4493 ..."
4494 </literallayout>
4495 </para>
4496
4497 <para>
4498 If you have more than one distribution alias, separate them with a space.
4499 Note that the build system currently automatically checks the
4500 Fedora, OpenSUSE, Debian, Ubuntu,
4501 and Mandriva distributions for source package recipes without having to specify them
4502 using the <filename>DISTRO_PN_ALIAS</filename> variable.
4503 For example, the following command generates a report that lists the Linux distributions
4504 that include the sources for each of the recipes.
4505 <literallayout class='monospaced'>
4506 $ bitbake world -f -c distro_check
4507 </literallayout>
4508 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
4509 file found in the
4510 <link linkend='source-directory'>Source Directory</link>.
4511 </para>
4512 </section>
4513
4514 <section id='handling-optional-module-packaging'>
4515 <title>Handling Optional Module Packaging</title>
4516
4517 <para>
4518 Many pieces of software split functionality into optional
4519 modules (or plug-ins) and the plug-ins that are built
4520 might depend on configuration options.
4521 To avoid having to duplicate the logic that determines what
4522 modules are available in your recipe or to avoid having
4523 to package each module by hand, the OpenEmbedded build system
4524 provides functionality to handle module packaging dynamically.
4525 </para>
4526
4527 <para>
4528 To handle optional module packaging, you need to do two things:
4529 <itemizedlist>
4530 <listitem><para>Ensure the module packaging is actually
4531 done.</para></listitem>
4532 <listitem><para>Ensure that any dependencies on optional
4533 modules from other recipes are satisfied by your recipe.
4534 </para></listitem>
4535 </itemizedlist>
4536 </para>
4537
4538 <section id='making-sure-the-packaging-is-done'>
4539 <title>Making Sure the Packaging is Done</title>
4540
4541 <para>
4542 To ensure the module packaging actually gets done, you use
4543 the <filename>do_split_packages</filename> function within
4544 the <filename>populate_packages</filename> Python function
4545 in your recipe.
4546 The <filename>do_split_packages</filename> function
4547 searches for a pattern of files or directories under a
4548 specified path and creates a package for each one it finds
4549 by appending to the
4550 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
4551 variable and setting the appropriate values for
4552 <filename>FILES_packagename</filename>,
4553 <filename>RDEPENDS_packagename</filename>,
4554 <filename>DESCRIPTION_packagename</filename>, and so forth.
4555 Here is an example from the <filename>lighttpd</filename>
4556 recipe:
4557 <literallayout class='monospaced'>
4558 python populate_packages_prepend () {
4559 lighttpd_libdir = d.expand('${libdir}')
4560 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
4561 'lighttpd-module-%s', 'Lighttpd module for %s',
4562 extra_depends='')
4563 }
4564 </literallayout>
4565 The previous example specifies a number of things in the
4566 call to <filename>do_split_packages</filename>.
4567 <itemizedlist>
4568 <listitem><para>A directory within the files installed
4569 by your recipe through <filename>do_install</filename>
4570 in which to search.</para></listitem>
4571 <listitem><para>A regular expression used to match module
4572 files in that directory.
4573 In the example, note the parentheses () that mark
4574 the part of the expression from which the module
4575 name should be derived.</para></listitem>
4576 <listitem><para>A pattern to use for the package names.
4577 </para></listitem>
4578 <listitem><para>A description for each package.
4579 </para></listitem>
4580 <listitem><para>An empty string for
4581 <filename>extra_depends</filename>, which disables
4582 the default dependency on the main
4583 <filename>lighttpd</filename> package.
4584 Thus, if a file in <filename>${libdir}</filename>
4585 called <filename>mod_alias.so</filename> is found,
4586 a package called <filename>lighttpd-module-alias</filename>
4587 is created for it and the
4588 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
4589 is set to "Lighttpd module for alias".</para></listitem>
4590 </itemizedlist>
4591 </para>
4592
4593 <para>
4594 Often, packaging modules is as simple as the previous
4595 example.
4596 However, more advanced options exist that you can use
4597 within <filename>do_split_packages</filename> to modify its
4598 behavior.
4599 And, if you need to, you can add more logic by specifying
4600 a hook function that is called for each package.
4601 It is also perfectly acceptable to call
4602 <filename>do_split_packages</filename> multiple times if
4603 you have more than one set of modules to package.
4604 </para>
4605
4606 <para>
4607 For more examples that show how to use
4608 <filename>do_split_packages</filename>, see the
4609 <filename>connman.inc</filename> file in the
4610 <filename>meta/recipes-connectivity/connman/</filename>
4611 directory of the <filename>poky</filename>
4612 <link linkend='yocto-project-repositories'>source repository</link>.
4613 You can also find examples in
4614 <filename>meta/classes/kernel.bbclass</filename>.
4615 </para>
4616
4617 <para>
4618 Following is a reference that shows
4619 <filename>do_split_packages</filename> mandatory and
4620 optional arguments:
4621 <literallayout class='monospaced'>
4622 Mandatory arguments
4623
4624 root
4625 The path in which to search
4626 file_regex
4627 Regular expression to match searched files.
4628 Use parentheses () to mark the part of this
4629 expression that should be used to derive the
4630 module name (to be substituted where %s is
4631 used in other function arguments as noted below)
4632 output_pattern
4633 Pattern to use for the package names. Must
4634 include %s.
4635 description
4636 Description to set for each package. Must
4637 include %s.
4638
4639 Optional arguments
4640
4641 postinst
4642 Postinstall script to use for all packages
4643 (as a string)
4644 recursive
4645 True to perform a recursive search - default
4646 False
4647 hook
4648 A hook function to be called for every match.
4649 The function will be called with the following
4650 arguments (in the order listed):
4651
4652 f
4653 Full path to the file/directory match
4654 pkg
4655 The package name
4656 file_regex
4657 As above
4658 output_pattern
4659 As above
4660 modulename
4661 The module name derived using file_regex
4662
4663 extra_depends
4664 Extra runtime dependencies (RDEPENDS) to be
4665 set for all packages. The default value of None
4666 causes a dependency on the main package
4667 (${PN}) - if you do not want this, pass empty
4668 string '' for this parameter.
4669 aux_files_pattern
4670 Extra item(s) to be added to FILES for each
4671 package. Can be a single string item or a list
4672 of strings for multiple items. Must include %s.
4673 postrm
4674 postrm script to use for all packages (as a
4675 string)
4676 allow_dirs
4677 True to allow directories to be matched -
4678 default False
4679 prepend
4680 If True, prepend created packages to PACKAGES
4681 instead of the default False which appends them
4682 match_path
4683 match file_regex on the whole relative path to
4684 the root rather than just the file name
4685 aux_files_pattern_verbatim
4686 Extra item(s) to be added to FILES for each
4687 package, using the actual derived module name
4688 rather than converting it to something legal
4689 for a package name. Can be a single string item
4690 or a list of strings for multiple items. Must
4691 include %s.
4692 allow_links
4693 True to allow symlinks to be matched - default
4694 False
4695 summary
4696 Summary to set for each package. Must include %s;
4697 defaults to description if not set.
4698 </literallayout>
4699 </para>
4700 </section>
4701
4702 <section id='satisfying-dependencies'>
4703 <title>Satisfying Dependencies</title>
4704
4705 <para>
4706 The second part for handling optional module packaging
4707 is to ensure that any dependencies on optional modules
4708 from other recipes are satisfied by your recipe.
4709 You can be sure these dependencies are satisfied by
4710 using the
4711 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
4712 Here is an example that continues with the
4713 <filename>lighttpd</filename> recipe shown earlier:
4714 <literallayout class='monospaced'>
4715 PACKAGES_DYNAMIC = "lighttpd-module-.*"
4716 </literallayout>
4717 The name specified in the regular expression can of
4718 course be anything.
4719 In this example, it is <filename>lighttpd-module-</filename>
4720 and is specified as the prefix to ensure that any
4721 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
4722 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
4723 on a package name starting with the prefix are satisfied
4724 during build time.
4725 If you are using <filename>do_split_packages</filename>
4726 as described in the previous section, the value you put in
4727 <filename>PACKAGES_DYNAMIC</filename> should correspond to
4728 the name pattern specified in the call to
4729 <filename>do_split_packages</filename>.
4730 </para>
4731 </section>
4732 </section>
4733
4734 <section id='using-runtime-package-management'>
4735 <title>Using Runtime Package Management</title>
4736
4737 <para>
4738 During a build, BitBake always transforms a recipe into one or
4739 more packages.
4740 For example, BitBake takes the <filename>bash</filename> recipe
4741 and currently produces the <filename>bash-dbg</filename>,
4742 <filename>bash-staticdev</filename>,
4743 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
4744 <filename>bash-locale</filename>, and
4745 <filename>bash</filename> packages.
4746 Not all generated packages are included in an image.
4747 </para>
4748
4749 <para>
4750 In several situations, you might need to update, add, remove,
4751 or query the packages on a target device at runtime
4752 (i.e. without having to generate a new image).
4753 Examples of such situations include:
4754 <itemizedlist>
4755 <listitem><para>
4756 You want to provide in-the-field updates to deployed
4757 devices (e.g. security updates).
4758 </para></listitem>
4759 <listitem><para>
4760 You want to have a fast turn-around development cycle
4761 for one or more applications that run on your device.
4762 </para></listitem>
4763 <listitem><para>
4764 You want to temporarily install the "debug" packages
4765 of various applications on your device so that
4766 debugging can be greatly improved by allowing
4767 access to symbols and source debugging.
4768 </para></listitem>
4769 <listitem><para>
4770 You want to deploy a more minimal package selection of
4771 your device but allow in-the-field updates to add a
4772 larger selection for customization.
4773 </para></listitem>
4774 </itemizedlist>
4775 </para>
4776
4777 <para>
4778 In all these situations, you have something similar to a more
4779 traditional Linux distribution in that in-field devices
4780 are able to receive pre-compiled packages from a server for
4781 installation or update.
4782 Being able to install these packages on a running,
4783 in-field device is what is termed "runtime package
4784 management".
4785 </para>
4786
4787 <para>
4788 In order to use runtime package management, you
4789 need a host/server machine that serves up the pre-compiled
4790 packages plus the required metadata.
4791 You also need package manipulation tools on the target.
4792 The build machine is a likely candidate to act as the server.
4793 However, that machine does not necessarily have to be the
4794 package server.
4795 The build machine could push its artifacts to another machine
4796 that acts as the server (e.g. Internet-facing).
4797 </para>
4798
4799 <para>
4800 A simple build that targets just one device produces
4801 more than one package database.
4802 In other words, the packages produced by a build are separated
4803 out into a couple of different package groupings based on
4804 criteria such as the target's CPU architecture, the target
4805 board, or the C library used on the target.
4806 For example, a build targeting the <filename>qemuarm</filename>
4807 device produces the following three package databases:
4808 <filename>all</filename>, <filename>armv5te</filename>, and
4809 <filename>qemuarm</filename>.
4810 If you wanted your <filename>qemuarm</filename> device to be
4811 aware of all the packages that were available to it,
4812 you would need to point it to each of these databases
4813 individually.
4814 In a similar way, a traditional Linux distribution usually is
4815 configured to be aware of a number of software repositories
4816 from which it retrieves packages.
4817 </para>
4818
4819 <para>
4820 Using runtime package management is completely optional and
4821 not required for a successful build or deployment in any
4822 way.
4823 But if you want to make use of runtime package management,
4824 you need to do a couple things above and beyond the basics.
4825 The remainder of this section describes what you need to do.
4826 </para>
4827
4828 <section id='runtime-package-management-build'>
4829 <title>Build Considerations</title>
4830
4831 <para>
4832 This section describes build considerations that you need
4833 to be aware of in order to provide support for runtime
4834 package management.
4835 </para>
4836
4837 <para>
4838 When BitBake generates packages it needs to know
4839 what format or formats to use.
4840 In your configuration, you use the
4841 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
4842 variable to specify the format.
4843 <note>
4844 You can choose to have more than one format but you must
4845 provide at least one.
4846 </note>
4847 </para>
4848
4849 <para>
4850 If you would like your image to start off with a basic
4851 package database of the packages in your current build
4852 as well as have the relevant tools available on the
4853 target for runtime package management, you can include
4854 "package-management" in the
4855 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4856 variable.
4857 Including "package-management" in this
4858 configuration variable ensures that when the image
4859 is assembled for your target, the image includes
4860 the currently-known package databases as well as
4861 the target-specific tools required for runtime
4862 package management to be performed on the target.
4863 However, this is not strictly necessary.
4864 You could start your image off without any databases
4865 but only include the required on-target package
4866 tool(s).
4867 As an example, you could include "opkg" in your
4868 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
4869 variable if you are using the IPK package format.
4870 You can then initialize your target's package database(s)
4871 later once your image is up and running.
4872 </para>
4873
4874 <para>
4875 Whenever you perform any sort of build step that can
4876 potentially generate a package or modify an existing
4877 package, it is always a good idea to re-generate the
4878 package index with:
4879 <literallayout class='monospaced'>
4880 $ bitbake package-index
4881 </literallayout>
4882 Realize that it is not sufficient to simply do the
4883 following:
4884 <literallayout class='monospaced'>
4885 $ bitbake &lt;some-package&gt; package-index
4886 </literallayout>
4887 This is because BitBake does not properly schedule the
4888 <filename>package-index</filename> target fully after any
4889 other target has completed.
4890 Thus, be sure to run the package update step separately.
4891 </para>
4892
4893 <para>
4894 As described below in the
4895 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
4896 section, if you are using IPK as your package format, you
4897 can make use of the
4898 <filename>distro-feed-configs</filename> recipe provided
4899 by <filename>meta-oe</filename> in order to configure your
4900 target to use your IPK databases.
4901 </para>
4902
4903 <para>
4904 When your build is complete, your packages reside in the
4905 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
4906 directory.
4907 For example, if <filename>${TMPDIR}</filename>
4908 is <filename>tmp</filename> and your selected package type
4909 is IPK, then your IPK packages are available in
4910 <filename>tmp/deploy/ipk</filename>.
4911 </para>
4912 </section>
4913
4914 <section id='runtime-package-management-server'>
4915 <title>Host or Server Machine Setup</title>
4916
4917 <para>
4918 Typically, packages are served from a server using
4919 HTTP.
4920 However, other protocols are possible.
4921 If you want to use HTTP, then setup and configure a
4922 web server, such as Apache 2 or lighttpd, on the machine
4923 serving the packages.
4924 </para>
4925
4926 <para>
4927 As previously mentioned, the build machine can act as the
4928 package server.
4929 In the following sections that describe server machine
4930 setups, the build machine is assumed to also be the server.
4931 </para>
4932
4933 <section id='package-server-apache'>
4934 <title>Serving Packages via Apache 2</title>
4935
4936 <para>
4937 This example assumes you are using the Apache 2
4938 server:
4939 <orderedlist>
4940 <listitem><para>
4941 Add the directory to your Apache
4942 configuration, which you can find at
4943 <filename>/etc/httpd/conf/httpd.conf</filename>.
4944 Use commands similar to these on the
4945 development system.
4946 These example commands assume a top-level
4947 <link linkend='source-directory'>Source Directory</link>
4948 named <filename>poky</filename> in your home
4949 directory.
4950 The example also assumes an RPM package type.
4951 If you are using a different package type, such
4952 as IPK, use "ipk" in the pathnames:
4953 <literallayout class='monospaced'>
4954 &lt;VirtualHost *:80&gt;
4955 ....
4956 Alias /rpm ~/poky/build/tmp/deploy/rpm
4957 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
4958 Options +Indexes
4959 &lt;/Directory&gt;
4960 &lt;/VirtualHost&gt;
4961 </literallayout></para></listitem>
4962 <listitem><para>
4963 Reload the Apache configuration as described
4964 in this step.
4965 For all commands, be sure you have root
4966 privileges.
4967 </para>
4968
4969 <para>
4970 If your development system is using Fedora or
4971 CentOS, use the following:
4972 <literallayout class='monospaced'>
4973 # service httpd reload
4974 </literallayout>
4975 For Ubuntu and Debian, use the following:
4976 <literallayout class='monospaced'>
4977 # /etc/init.d/apache2 reload
4978 </literallayout>
4979 For OpenSUSE, use the following:
4980 <literallayout class='monospaced'>
4981 # /etc/init.d/apache2 reload
4982 </literallayout></para></listitem>
4983 <listitem><para>
4984 If you are using Security-Enhanced Linux
4985 (SELinux), you need to label the files as
4986 being accessible through Apache.
4987 Use the following command from the development
4988 host.
4989 This example assumes RPM package types:
4990 <literallayout class='monospaced'>
4991 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
4992 </literallayout></para></listitem>
4993 </orderedlist>
4994 </para>
4995 </section>
4996
4997 <section id='package-server-lighttpd'>
4998 <title>Serving Packages via lighttpd</title>
4999
5000 <para>
5001 If you are using lighttpd, all you need
5002 to do is to provide a link from your
5003 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
5004 directory to lighttpd's document-root.
5005 You can determine the specifics of your lighttpd
5006 installation by looking through its configuration file,
5007 which is usually found at:
5008 <filename>/etc/lighttpd/lighttpd.conf</filename>.
5009 </para>
5010
5011 <para>
5012 For example, if you are using IPK, lighttpd's
5013 document-root is set to
5014 <filename>/var/www/lighttpd</filename>, and you had
5015 packages for a target named "BOARD",
5016 then you might create a link from your build location
5017 to lighttpd's document-root as follows:
5018 <literallayout class='monospaced'>
5019 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
5020 </literallayout>
5021 </para>
5022
5023 <para>
5024 At this point, you need to start the lighttpd server.
5025 The method used to start the server varies by
5026 distribution.
5027 However, one basic method that starts it by hand is:
5028 <literallayout class='monospaced'>
5029 # lighttpd -f /etc/lighttpd/lighttpd.conf
5030 </literallayout>
5031 </para>
5032 </section>
5033 </section>
5034
5035 <section id='runtime-package-management-target'>
5036 <title>Target Setup</title>
5037
5038 <para>
5039 Setting up the target differs depending on the
5040 package management system.
5041 This section provides information for RPM and IPK.
5042 </para>
5043
5044 <section id='runtime-package-management-target-rpm'>
5045 <title>Using RPM</title>
5046
5047 <para>
5048 The application for performing runtime package
5049 management of RPM packages on the target is called
5050 <filename>smart</filename>.
5051 </para>
5052
5053 <para>
5054 On the target machine, you need to inform
5055 <filename>smart</filename> of every package database
5056 you want to use.
5057 As an example, suppose your target device can use the
5058 following three package databases from a server named
5059 <filename>server.name</filename>:
5060 <filename>all</filename>, <filename>i586</filename>,
5061 and <filename>qemux86</filename>.
5062 Given this example, issue the following commands on the
5063 target:
5064 <literallayout class='monospaced'>
5065 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
5066 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
5067 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
5068 </literallayout>
5069 Also from the target machine, fetch the repository
5070 information using this command:
5071 <literallayout class='monospaced'>
5072 # smart update
5073 </literallayout>
5074 You can now use the <filename>smart query</filename>
5075 and <filename>smart install</filename> commands to
5076 find and install packages from the repositories.
5077 </para>
5078 </section>
5079
5080 <section id='runtime-package-management-target-ipk'>
5081 <title>Using IPK</title>
5082
5083 <para>
5084 The application for performing runtime package
5085 management of IPK packages on the target is called
5086 <filename>opkg</filename>.
5087 </para>
5088
5089 <para>
5090 In order to inform <filename>opkg</filename> of the
5091 package databases you want to use, simply create one
5092 or more <filename>*.conf</filename> files in the
5093 <filename>/etc/opkg</filename> directory on the target.
5094 The <filename>opkg</filename> application uses them
5095 to find its available package databases.
5096 As an example, suppose you configured your HTTP server
5097 on your machine named
5098 <filename>www.mysite.com</filename> to serve files
5099 from a <filename>BOARD-dir</filename> directory under
5100 its document-root.
5101 In this case, you might create a configuration
5102 file on the target called
5103 <filename>/etc/opkg/base-feeds.conf</filename> that
5104 contains:
5105 <literallayout class='monospaced'>
5106 src/gz all http://www.mysite.com/BOARD-dir/all
5107 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
5108 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
5109 </literallayout>
5110 </para>
5111
5112 <para>
5113 As a way of making it easier to generate and make
5114 these IPK configuration files available on your
5115 target, simply define
5116 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
5117 to point to your server and the location within the
5118 document-root which contains the databases.
5119 For example: if you are serving your packages over
5120 HTTP, your server's IP address is 192.168.7.1, and
5121 your databases are located in a directory called
5122 <filename>BOARD-dir</filename> underneath your HTTP
5123 server's document-root, you need to set
5124 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
5125 <filename>http://192.168.7.1/BOARD-dir</filename> and
5126 a set of configuration files will be generated for you
5127 in your target to work with this feed.
5128 </para>
5129
5130 <para>
5131 On the target machine, fetch (or refresh) the
5132 repository information using this command:
5133 <literallayout class='monospaced'>
5134 # opkg update
5135 </literallayout>
5136 You can now use the <filename>opkg list</filename> and
5137 <filename>opkg install</filename> commands to find and
5138 install packages from the repositories.
5139 </para>
5140 </section>
5141 </section>
5142 </section>
5143
5144 <section id='testing-packages-with-ptest'>
5145 <title>Testing Packages With ptest</title>
5146
5147 <para>
5148 A Package Test (ptest) runs tests against packages built
5149 by the OpenEmbedded build system on the target machine.
5150 A ptest contains at least two items: the actual test, and
5151 a shell script (<filename>run-ptest</filename>) that starts
5152 the test.
5153 The shell script that starts the test must not contain
5154 the actual test, the script only starts it.
5155 On the other hand, the test can be anything from a simple
5156 shell script that runs a binary and checks the output to
5157 an elaborate system of test binaries and data files.
5158 </para>
5159
5160 <para>
5161 The test generates output in the format used by
5162 Automake:
5163 <literallayout class='monospaced'>
5164 &lt;result&gt;: &lt;testname&gt;
5165 </literallayout>
5166 where the result can be <filename>PASS</filename>,
5167 <filename>FAIL</filename>, or <filename>SKIP</filename>,
5168 and the testname can be any identifying string.
5169 </para>
5170
5171 <note>
5172 A recipe is "ptest-enabled" if it inherits the
5173 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5174 class.
5175 </note>
5176
5177 <section id='adding-ptest-to-your-build'>
5178 <title>Adding ptest to Your Build</title>
5179
5180 <para>
5181 To add package testing to your build, add the
5182 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5183 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
5184 variables to your <filename>local.conf</filename> file,
5185 which is found in the
5186 <link linkend='build-directory'>Build Directory</link>:
5187 <literallayout class='monospaced'>
5188 DISTRO_FEATURES_append = " ptest"
5189 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
5190 </literallayout>
5191 Once your build is complete, the ptest files are installed
5192 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
5193 directory within the image, where
5194 <filename>&lt;package&gt;</filename> is the name of the
5195 package.
5196 </para>
5197 </section>
5198
5199 <section id='running-ptest'>
5200 <title>Running ptest</title>
5201
5202 <para>
5203 The <filename>ptest-runner</filename> package installs a
5204 shell script that loops through all installed ptest test
5205 suites and runs them in sequence.
5206 Consequently, you might want to add this package to
5207 your image.
5208 </para>
5209 </section>
5210
5211 <section id='getting-your-package-ready'>
5212 <title>Getting Your Package Ready</title>
5213
5214 <para>
5215 In order to enable a recipe to run installed ptests
5216 on target hardware,
5217 you need to prepare the recipes that build the packages
5218 you want to test.
5219 Here is what you have to do for each recipe:
5220 <itemizedlist>
5221 <listitem><para><emphasis>Be sure the recipe
5222 inherits the
5223 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5224 class:</emphasis>
5225 Include the following line in each recipe:
5226 <literallayout class='monospaced'>
5227 inherit ptest
5228 </literallayout>
5229 </para></listitem>
5230 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
5231 This script starts your test.
5232 Locate the script where you will refer to it
5233 using
5234 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
5235 Here is an example that starts a test for
5236 <filename>dbus</filename>:
5237 <literallayout class='monospaced'>
5238 #!/bin/sh
5239 cd test
5240 make -k runtest-TESTS
5241 </literallayout>
5242 </para></listitem>
5243 <listitem><para><emphasis>Ensure dependencies are
5244 met:</emphasis>
5245 If the test adds build or runtime dependencies
5246 that normally do not exist for the package
5247 (such as requiring "make" to run the test suite),
5248 use the
5249 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
5250 and
5251 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
5252 variables in your recipe in order for the package
5253 to meet the dependencies.
5254 Here is an example where the package has a runtime
5255 dependency on "make":
5256 <literallayout class='monospaced'>
5257 RDEPENDS_${PN}-ptest += "make"
5258 </literallayout>
5259 </para></listitem>
5260 <listitem><para><emphasis>Add a function to build the
5261 test suite:</emphasis>
5262 Not many packages support cross-compilation of
5263 their test suites.
5264 Consequently, you usually need to add a
5265 cross-compilation function to the package.
5266 </para>
5267 <para>Many packages based on Automake compile and
5268 run the test suite by using a single command
5269 such as <filename>make check</filename>.
5270 However, the native <filename>make check</filename>
5271 builds and runs on the same computer, while
5272 cross-compiling requires that the package is built
5273 on the host but executed on the target.
5274 The built version of Automake that ships with the
5275 Yocto Project includes a patch that separates
5276 building and execution.
5277 Consequently, packages that use the unaltered,
5278 patched version of <filename>make check</filename>
5279 automatically cross-compiles.</para>
5280 <para>However, you still must add a
5281 <filename>do_compile_ptest</filename> function to
5282 build the test suite.
5283 Add a function similar to the following to your
5284 recipe:
5285 <literallayout class='monospaced'>
5286 do_compile_ptest() {
5287 oe_runmake buildtest-TESTS
5288 }
5289 </literallayout>
5290 </para></listitem>
5291 <listitem><para><emphasis>Ensure special configurations
5292 are set:</emphasis>
5293 If the package requires special configurations
5294 prior to compiling the test code, you must
5295 insert a <filename>do_configure_ptest</filename>
5296 function into the recipe.
5297 </para></listitem>
5298 <listitem><para><emphasis>Install the test
5299 suite:</emphasis>
5300 The <filename>ptest</filename> class
5301 automatically copies the file
5302 <filename>run-ptest</filename> to the target and
5303 then runs make <filename>install-ptest</filename>
5304 to run the tests.
5305 If this is not enough, you need to create a
5306 <filename>do_install_ptest</filename> function and
5307 make sure it gets called after the
5308 "make install-ptest" completes.
5309 </para></listitem>
5310 </itemizedlist>
5311 </para>
5312 </section>
5313 </section>
5314 </section>
5315
5316 <section id="building-software-from-an-external-source">
5317 <title>Building Software from an External Source</title>
5318
5319 <para>
5320 By default, the OpenEmbedded build system uses the
5321 <link linkend='build-directory'>Build Directory</link> to
5322 build source code.
5323 The build process involves fetching the source files, unpacking
5324 them, and then patching them if necessary before the build takes
5325 place.
5326 </para>
5327
5328 <para>
5329 Situations exist where you might want to build software from source
5330 files that are external to and thus outside of the
5331 OpenEmbedded build system.
5332 For example, suppose you have a project that includes a new BSP with
5333 a heavily customized kernel.
5334 And, you want to minimize exposing the build system to the
5335 development team so that they can focus on their project and
5336 maintain everyone's workflow as much as possible.
5337 In this case, you want a kernel source directory on the development
5338 machine where the development occurs.
5339 You want the recipe's
5340 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
5341 variable to point to the external directory and use it as is, not
5342 copy it.
5343 </para>
5344
5345 <para>
5346 To build from software that comes from an external source, all you
5347 need to do is inherit the
5348 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
5349 class and then set the
5350 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
5351 variable to point to your external source code.
5352 Here are the statements to put in your
5353 <filename>local.conf</filename> file:
5354 <literallayout class='monospaced'>
5355 INHERIT += "externalsrc"
5356 EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
5357 </literallayout>
5358 </para>
5359
5360 <para>
5361 By default, <filename>externalsrc.bbclass</filename> builds
5362 the source code in a directory separate from the external source
5363 directory as specified by
5364 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
5365 If you need to have the source built in the same directory in
5366 which it resides, or some other nominated directory, you can set
5367 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
5368 to point to that directory:
5369 <literallayout class='monospaced'>
5370 EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
5371 </literallayout>
5372 </para>
5373 </section>
5374
5375 <section id="selecting-an-initialization-manager">
5376 <title>Selecting an Initialization Manager</title>
5377
5378 <para>
5379 By default, the Yocto Project uses SysVinit as the initialization
5380 manager.
5381 However, support also exists for systemd,
5382 which is a full replacement for init with
5383 parallel starting of services, reduced shell overhead and other
5384 features that are used by many distributions.
5385 </para>
5386
5387 <para>
5388 If you want to use SysVinit, you do
5389 not have to do anything.
5390 But, if you want to use systemd, you must
5391 take some steps as described in the following sections.
5392 </para>
5393
5394 <section id='using-systemd-exclusively'>
5395 <title>Using systemd Exclusively</title>
5396
5397 <para>
5398 Set the these variables in your distribution configuration
5399 file as follows:
5400 <literallayout class='monospaced'>
5401 DISTRO_FEATURES_append = " systemd"
5402 VIRTUAL-RUNTIME_init_manager = "systemd"
5403 </literallayout>
5404 You can also prevent the SysVinit
5405 distribution feature from
5406 being automatically enabled as follows:
5407 <literallayout class='monospaced'>
5408 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
5409 </literallayout>
5410 Doing so removes any redundant SysVinit scripts.
5411 </para>
5412
5413 <para>
5414 To remove initscripts from your image altogether,
5415 set this variable also:
5416 <literallayout class='monospaced'>
5417 VIRTUAL-RUNTIME_initscripts = ""
5418 </literallayout>
5419 </para>
5420
5421 <para>
5422 For information on the backfill variable, see
5423 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
5424 </para>
5425 </section>
5426
5427 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
5428 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
5429
5430 <para>
5431 Set the these variables in your distribution configuration
5432 file as follows:
5433 <literallayout class='monospaced'>
5434 DISTRO_FEATURES_append = " systemd"
5435 VIRTUAL-RUNTIME_init_manager = "systemd"
5436 </literallayout>
5437 Doing so causes your main image to use the
5438 <filename>packagegroup-core-boot.bb</filename> recipe and
5439 systemd.
5440 The rescue/minimal image cannot use this package group.
5441 However, it can install SysVinit
5442 and the appropriate packages will have support for both
5443 systemd and SysVinit.
5444 </para>
5445 </section>
5446 </section>
5447
5448 <section id="platdev-appdev-srcrev">
5449 <title>Using an External SCM</title>
5450
5451 <para>
5452 If you're working on a recipe that pulls from an external Source
5453 Code Manager (SCM), it is possible to have the OpenEmbedded build
5454 system notice new recipe changes added to the SCM and then build
5455 the resulting packages that depend on the new recipes by using
5456 the latest versions.
5457 This only works for SCMs from which it is possible to get a
5458 sensible revision number for changes.
5459 Currently, you can do this with Apache Subversion (SVN), Git, and
5460 Bazaar (BZR) repositories.
5461 </para>
5462
5463 <para>
5464 To enable this behavior, the
5465 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
5466 of the recipe needs to reference
5467 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
5468 Here is an example:
5469 <literallayout class='monospaced'>
5470 PV = "1.2.3+git${SRCPV}
5471 </literallayout>
5472 Then, you can add the following to your
5473 <filename>local.conf</filename>:
5474 <literallayout class='monospaced'>
5475 SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
5476 </literallayout>
5477 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
5478 is the name of the recipe for which you want to enable automatic source
5479 revision updating.
5480 </para>
5481
5482 <para>
5483 If you do not want to update your local configuration file, you can
5484 add the following directly to the recipe to finish enabling
5485 the feature:
5486 <literallayout class='monospaced'>
5487 SRCREV = "${AUTOREV}"
5488 </literallayout>
5489 </para>
5490
5491 <para>
5492 The Yocto Project provides a distribution named
5493 <filename>poky-bleeding</filename>, whose configuration
5494 file contains the line:
5495 <literallayout class='monospaced'>
5496 require conf/distro/include/poky-floating-revisions.inc
5497 </literallayout>
5498 This line pulls in the listed include file that contains
5499 numerous lines of exactly that form:
5500 <literallayout class='monospaced'>
5501 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
5502 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
5503 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
5504 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
5505 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
5506 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
5507 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
5508 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
5509 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
5510 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
5511 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
5512 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
5513 SRCREV_pn-screenshot ?= "${AUTOREV}"
5514 SRCREV_pn-libfakekey ?= "${AUTOREV}"
5515 SRCREV_pn-oprofileui ?= "${AUTOREV}"
5516 .
5517 .
5518 .
5519 </literallayout>
5520 These lines allow you to experiment with building a
5521 distribution that tracks the latest development source
5522 for numerous packages.
5523 <note><title>Caution</title>
5524 The <filename>poky-bleeding</filename> distribution
5525 is not tested on a regular basis.
5526 Keep this in mind if you use it.
5527 </note>
5528 </para>
5529 </section>
5530
5531 <section id='creating-a-read-only-root-filesystem'>
5532 <title>Creating a Read-Only Root Filesystem</title>
5533
5534 <para>
5535 Suppose, for security reasons, you need to disable
5536 your target device's root filesystem's write permissions
5537 (i.e. you need a read-only root filesystem).
5538 Or, perhaps you are running the device's operating system
5539 from a read-only storage device.
5540 For either case, you can customize your image for
5541 that behavior.
5542 </para>
5543
5544 <note>
5545 Supporting a read-only root filesystem requires that the system and
5546 applications do not try to write to the root filesystem.
5547 You must configure all parts of the target system to write
5548 elsewhere, or to gracefully fail in the event of attempting to
5549 write to the root filesystem.
5550 </note>
5551
5552 <section id='creating-the-root-filesystem'>
5553 <title>Creating the Root Filesystem</title>
5554
5555 <para>
5556 To create the read-only root filesystem, simply add the
5557 "read-only-rootfs" feature to your image.
5558 Using either of the following statements in your
5559 image recipe or from within the
5560 <filename>local.conf</filename> file found in the
5561 <link linkend='build-directory'>Build Directory</link>
5562 causes the build system to create a read-only root filesystem:
5563 <literallayout class='monospaced'>
5564 IMAGE_FEATURES = "read-only-rootfs"
5565 </literallayout>
5566 or
5567 <literallayout class='monospaced'>
5568 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
5569 </literallayout>
5570 </para>
5571
5572 <para>
5573 For more information on how to use these variables, see the
5574 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
5575 section.
5576 For information on the variables, see
5577 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5578 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
5579 </para>
5580 </section>
5581
5582 <section id='post-installation-scripts'>
5583 <title>Post-Installation Scripts</title>
5584
5585 <para>
5586 It is very important that you make sure all
5587 post-Installation (<filename>pkg_postinst</filename>) scripts
5588 for packages that are installed into the image can be run
5589 at the time when the root filesystem is created during the
5590 build on the host system.
5591 These scripts cannot attempt to run during first-boot on the
5592 target device.
5593 With the "read-only-rootfs" feature enabled,
5594 the build system checks during root filesystem creation to make
5595 sure all post-installation scripts succeed.
5596 If any of these scripts still need to be run after the root
5597 filesystem is created, the build immediately fails.
5598 These build-time checks ensure that the build fails
5599 rather than the target device fails later during its
5600 initial boot operation.
5601 </para>
5602
5603 <para>
5604 Most of the common post-installation scripts generated by the
5605 build system for the out-of-the-box Yocto Project are engineered
5606 so that they can run during root filesystem creation
5607 (e.g. post-installation scripts for caching fonts).
5608 However, if you create and add custom scripts, you need
5609 to be sure they can be run during this file system creation.
5610 </para>
5611
5612 <para>
5613 Here are some common problems that prevent
5614 post-installation scripts from running during root filesystem
5615 creation:
5616 <itemizedlist>
5617 <listitem><para>
5618 <emphasis>Not using $D in front of absolute
5619 paths:</emphasis>
5620 The build system defines
5621 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
5622 when the root filesystem is created.
5623 Furthermore, <filename>$D</filename> is blank when the
5624 script is run on the target device.
5625 This implies two purposes for <filename>$D</filename>:
5626 ensuring paths are valid in both the host and target
5627 environments, and checking to determine which
5628 environment is being used as a method for taking
5629 appropriate actions.
5630 </para></listitem>
5631 <listitem><para>
5632 <emphasis>Attempting to run processes that are
5633 specific to or dependent on the target
5634 architecture:</emphasis>
5635 You can work around these attempts by using native
5636 tools to accomplish the same tasks, or
5637 by alternatively running the processes under QEMU,
5638 which has the <filename>qemu_run_binary</filename>
5639 function.
5640 For more information, see the
5641 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
5642 class.</para></listitem>
5643 </itemizedlist>
5644 </para>
5645 </section>
5646
5647 <section id='areas-with-write-access'>
5648 <title>Areas With Write Access</title>
5649
5650 <para>
5651 With the "read-only-rootfs" feature enabled,
5652 any attempt by the target to write to the root filesystem at
5653 runtime fails.
5654 Consequently, you must make sure that you configure processes
5655 and applications that attempt these types of writes do so
5656 to directories with write access (e.g.
5657 <filename>/tmp</filename> or <filename>/var/run</filename>).
5658 </para>
5659 </section>
5660 </section>
5661
5662 <section id="performing-automated-runtime-testing">
5663 <title>Performing Automated Runtime Testing</title>
5664
5665 <para>
5666 The OpenEmbedded build system makes available a series of automated
5667 tests for images to verify runtime functionality.
5668 You can run these tests on either QEMU or actual target hardware.
5669 Tests are written in Python making use of the
5670 <filename>unittest</filename> module, and the majority of them
5671 run commands on the target system over SSH.
5672 This section describes how you set up the environment to use these
5673 tests, run available tests, and write and add your own tests.
5674 </para>
5675
5676 <section id='enabling-tests'>
5677 <title>Enabling Tests</title>
5678
5679 <para>
5680 Depending on whether you are planning on running tests using
5681 QEMU or on running them on the hardware, you have to take
5682 different steps to enable the tests.
5683 See the following subsections for information on how to
5684 enable both types of tests.
5685 </para>
5686
5687 <section id='qemu-image-enabling-tests'>
5688 <title>Enabling Runtime Tests on QEMU</title>
5689
5690 <para>
5691 In order to run tests, you need to do the following:
5692 <itemizedlist>
5693 <listitem><para><emphasis>Set up to avoid interaction
5694 with <filename>sudo</filename> for networking:</emphasis>
5695 To accomplish this, you must do one of the
5696 following:
5697 <itemizedlist>
5698 <listitem><para>Add
5699 <filename>NOPASSWD</filename> for your user
5700 in <filename>/etc/sudoers</filename> either for
5701 ALL commands or just for
5702 <filename>runqemu-ifup</filename>.
5703 You must provide the full path as that can
5704 change if you are using multiple clones of the
5705 source repository.
5706 <note>
5707 On some distributions, you also need to
5708 comment out "Defaults requiretty" in
5709 <filename>/etc/sudoers</filename>.
5710 </note></para></listitem>
5711 <listitem><para>Manually configure a tap interface
5712 for your system.</para></listitem>
5713 <listitem><para>Run as root the script in
5714 <filename>scripts/runqemu-gen-tapdevs</filename>,
5715 which should generate a list of tap devices.
5716 This is the option typically chosen for
5717 Autobuilder-type environments.
5718 </para></listitem>
5719 </itemizedlist></para></listitem>
5720 <listitem><para><emphasis>Set the
5721 <filename>DISPLAY</filename> variable:</emphasis>
5722 You need to set this variable so that you have an X
5723 server available (e.g. start
5724 <filename>vncserver</filename> for a headless machine).
5725 </para></listitem>
5726 <listitem><para><emphasis>Be sure your host's firewall
5727 accepts incoming connections from
5728 192.168.7.0/24:</emphasis>
5729 Some of the tests (in particular smart tests) start an
5730 HTTP server on a random high number port, which is
5731 used to serve files to the target.
5732 The smart module serves
5733 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
5734 smart channel commands. That means your host's firewall
5735 must accept incoming connections from 192.168.7.0/24,
5736 which is the default IP range used for tap devices
5737 by <filename>runqemu</filename>.</para></listitem>
5738 </itemizedlist>
5739 </para>
5740
5741 <para>
5742 Once you start running the tests, the following happens:
5743 <itemizedlist>
5744 <listitem><para>A copy of the root filesystem is written
5745 to <filename>${WORKDIR}/testimage</filename>.
5746 </para></listitem>
5747 <listitem><para>The image is booted under QEMU using the
5748 standard <filename>runqemu</filename> script.
5749 </para></listitem>
5750 <listitem><para>A default timeout of 500 seconds occurs
5751 to allow for the boot process to reach the login prompt.
5752 You can change the timeout period by setting
5753 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
5754 in the <filename>local.conf</filename> file.
5755 </para></listitem>
5756 <listitem><para>Once the boot process is reached and the
5757 login prompt appears, the tests run.
5758 The full boot log is written to
5759 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
5760 </para></listitem>
5761 <listitem><para>Each test module loads in the order found
5762 in <filename>TEST_SUITES</filename>.
5763 You can find the full output of the commands run over
5764 SSH in
5765 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
5766 </para></listitem>
5767 <listitem><para>If no failures occur, the task running the
5768 tests ends successfully.
5769 You can find the output from the
5770 <filename>unittest</filename> in the task log at
5771 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
5772 </para></listitem>
5773 </itemizedlist>
5774 </para>
5775 </section>
5776
5777 <section id='hardware-image-enabling-tests'>
5778 <title>Enabling Runtime Tests on Hardware</title>
5779
5780 <para>
5781 The OpenEmbedded build system can run tests on real
5782 hardware, and for certain devices it can also deploy
5783 the image to be tested onto the device beforehand.
5784 </para>
5785
5786 <para>
5787 For automated deployment, a "master image" is installed
5788 onto the hardware once as part of setup.
5789 Then, each time tests are to be run, the following
5790 occurs:
5791 <orderedlist>
5792 <listitem><para>The master image is booted into and
5793 used to write the image to be tested to
5794 a second partition.
5795 </para></listitem>
5796 <listitem><para>The device is then rebooted using an
5797 external script that you need to provide.
5798 </para></listitem>
5799 <listitem><para>The device boots into the image to be
5800 tested.
5801 </para></listitem>
5802 </orderedlist>
5803 </para>
5804
5805 <para>
5806 When running tests (independent of whether the image
5807 has been deployed automatically or not), the device is
5808 expected to be connected to a network on a
5809 pre-determined IP address.
5810 You can either use static IP addresses written into
5811 the image, or set the image to use DHCP and have your
5812 DHCP server on the test network assign a known IP address
5813 based on the MAC address of the device.
5814 </para>
5815
5816 <para>
5817 In order to run tests on hardware, you need to set
5818 <filename>TEST_TARGET</filename> to an appropriate value.
5819 For QEMU, you do not have to change anything, the default
5820 value is "QemuTarget".
5821 For running tests on hardware, two options exist:
5822 "SimpleRemoteTarget" and "GummibootTarget".
5823 <itemizedlist>
5824 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
5825 Choose "SimpleRemoteTarget" if you are going to
5826 run tests on a target system that is already
5827 running the image to be tested and is available
5828 on the network.
5829 You can use "SimpleRemoteTarget" in conjunction
5830 with either real hardware or an image running
5831 within a separately started QEMU or any
5832 other virtual machine manager.
5833 </para></listitem>
5834 <listitem><para><emphasis>"GummibootTarget":</emphasis>
5835 Choose "GummibootTarget" if your hardware is
5836 an EFI-based machine with
5837 <filename>gummiboot</filename> as bootloader and
5838 <filename>core-image-testmaster</filename>
5839 (or something similar) is installed.
5840 Also, your hardware under test must be in a
5841 DHCP-enabled network that gives it the same IP
5842 address for each reboot.</para>
5843 <para>If you choose "GummibootTarget", there are
5844 additional requirements and considerations.
5845 See the
5846 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
5847 section, which follows, for more information.
5848 </para></listitem>
5849 </itemizedlist>
5850 </para>
5851 </section>
5852
5853 <section id='selecting-gummiboottarget'>
5854 <title>Selecting GummibootTarget</title>
5855
5856 <para>
5857 If you did not set <filename>TEST_TARGET</filename> to
5858 "GummibootTarget", then you do not need any information
5859 in this section.
5860 You can skip down to the
5861 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
5862 section.
5863 </para>
5864
5865 <para>
5866 If you did set <filename>TEST_TARGET</filename> to
5867 "GummibootTarget", you also need to perform a one-time
5868 setup of your master image by doing the following:
5869 <orderedlist>
5870 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
5871 Be sure that <filename>EFI_PROVIDER</filename>
5872 is as follows:
5873 <literallayout class='monospaced'>
5874 EFI_PROVIDER = "gummiboot"
5875 </literallayout>
5876 </para></listitem>
5877 <listitem><para><emphasis>Build the master image:</emphasis>
5878 Build the <filename>core-image-testmaster</filename>
5879 image.
5880 The <filename>core-image-testmaster</filename>
5881 recipe is provided as an example for a
5882 "master" image and you can customize the image
5883 recipe as you would any other recipe.
5884 </para>
5885 <para>Here are the image recipe requirements:
5886 <itemizedlist>
5887 <listitem><para>Inherits
5888 <filename>core-image</filename>
5889 so that kernel modules are installed.
5890 </para></listitem>
5891 <listitem><para>Installs normal linux utilities
5892 not busybox ones (e.g.
5893 <filename>bash</filename>,
5894 <filename>coreutils</filename>,
5895 <filename>tar</filename>,
5896 <filename>gzip</filename>, and
5897 <filename>kmod</filename>).
5898 </para></listitem>
5899 <listitem><para>Uses a custom
5900 initramfs image with a custom installer.
5901 A normal image that you can install usually
5902 creates a single rootfs partition.
5903 This image uses another installer that
5904 creates a specific partition layout.
5905 Not all Board Support Packages (BSPs)
5906 can use an installer.
5907 For such cases, you need to manually create
5908 the following partition layout on the
5909 target:
5910 <itemizedlist>
5911 <listitem><para>First partition mounted
5912 under <filename>/boot</filename>,
5913 labeled "boot".
5914 </para></listitem>
5915 <listitem><para>The main rootfs
5916 partition where this image gets
5917 installed, which is mounted under
5918 <filename>/</filename>.
5919 </para></listitem>
5920 <listitem><para>Another partition
5921 labeled "testrootfs" where test
5922 images get deployed.
5923 </para></listitem>
5924 </itemizedlist>
5925 </para></listitem>
5926 </itemizedlist>
5927 </para></listitem>
5928 <listitem><para><emphasis>Install image:</emphasis>
5929 Install the image that you just built on the target
5930 system.
5931 </para></listitem>
5932 </orderedlist>
5933 </para>
5934
5935 <para>
5936 The final thing you need to do when setting
5937 <filename>TEST_TARGET</filename> to "GummibootTarget" is
5938 to set up the test image:
5939 <orderedlist>
5940 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
5941 Make sure you have the following statements in
5942 your <filename>local.conf</filename> file:
5943 <literallayout class='monospaced'>
5944 IMAGE_FSTYPES += "tar.gz"
5945 INHERIT += "testimage"
5946 TEST_TARGET = "GummibootTarget"
5947 TEST_TARGET_IP = "192.168.2.3"
5948 </literallayout>
5949 </para></listitem>
5950 <listitem><para><emphasis>Build your test image:</emphasis>
5951 Use BitBake to build the image:
5952 <literallayout class='monospaced'>
5953 $ bitbake core-image-sato
5954 </literallayout>
5955 </para></listitem>
5956 </orderedlist>
5957 </para>
5958
5959 <para>
5960 Here is some additional information regarding running
5961 "GummibootTarget" as your test target:
5962 <itemizedlist>
5963 <listitem><para>
5964 You can use
5965 <filename>TEST_POWERCONTROL_CMD</filename>
5966 together with
5967 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
5968 as a command that runs on the host and does power
5969 cycling.
5970 The test code passes one argument to that command:
5971 off, on or cycle (off then on).
5972 Here is an example that could appear in your
5973 <filename>local.conf</filename> file:
5974 <literallayout class='monospaced'>
5975 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
5976 </literallayout>
5977 In this example, the expect script does the
5978 following:
5979 <literallayout class='monospaced'>
5980 ssh test@10.11.12.1 "pyctl nuc1 &lt;arg&gt;"
5981 </literallayout>
5982 It then runs a Python script that controls power
5983 for a label called <filename>nuc1</filename>.
5984 <note>
5985 You need to customize
5986 <filename>TEST_POWERCONTROL_CMD</filename>
5987 and
5988 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
5989 for your own setup.
5990 The one requirement is that it accepts
5991 "on", "off", and "cycle" as the last argument.
5992 </note>
5993 </para></listitem>
5994 <listitem><para>
5995 When no command is defined, it connects to the
5996 device over SSH and uses the classic reboot command
5997 to reboot the device.
5998 Classic reboot is fine as long as the machine
5999 actually reboots (i.e. the SSH test has not
6000 failed).
6001 It is useful for scenarios where you have a simple
6002 setup, typically with a single board, and where
6003 some manual interaction is okay from time to time.
6004 </para></listitem>
6005 </itemizedlist>
6006 </para>
6007 </section>
6008 </section>
6009
6010 <section id="qemu-image-running-tests">
6011 <title>Running Tests</title>
6012
6013 <para>
6014 You can start the tests automatically or manually:
6015 <itemizedlist>
6016 <listitem><para><emphasis>Automatically running tests:</emphasis>
6017 To run the tests automatically after the
6018 OpenEmbedded build system successfully creates an image,
6019 first set the
6020 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
6021 variable to "1" in your <filename>local.conf</filename>
6022 file in the
6023 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6024 <literallayout class='monospaced'>
6025 TEST_IMAGE = "1"
6026 </literallayout>
6027 Next, build your image.
6028 If the image successfully builds, the tests will be
6029 run:
6030 <literallayout class='monospaced'>
6031 bitbake core-image-sato
6032 </literallayout></para></listitem>
6033 <listitem><para><emphasis>Manually running tests:</emphasis>
6034 To manually run the tests, first globally inherit the
6035 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
6036 class by editing your <filename>local.conf</filename>
6037 file:
6038 <literallayout class='monospaced'>
6039 INHERIT += "testimage"
6040 </literallayout>
6041 Next, use BitBake to run the tests:
6042 <literallayout class='monospaced'>
6043 bitbake -c testimage &lt;image&gt;
6044 </literallayout></para></listitem>
6045 </itemizedlist>
6046 </para>
6047
6048 <para>
6049 All test files reside in
6050 <filename>meta/lib/oeqa/runtime</filename> in the
6051 <link linkend='source-directory'>Source Directory</link>.
6052 A test name maps directly to a Python module.
6053 Each test module may contain a number of individual tests.
6054 Tests are usually grouped together by the area
6055 tested (e.g tests for systemd reside in
6056 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
6057 </para>
6058
6059 <para>
6060 You can add tests to any layer provided you place them in the
6061 proper area and you extend
6062 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6063 in the <filename>local.conf</filename> file as normal.
6064 Be sure that tests reside in
6065 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
6066 <note>
6067 Be sure that module names do not collide with module names
6068 used in the default set of test modules in
6069 <filename>meta/lib/oeqa/runtime</filename>.
6070 </note>
6071 </para>
6072
6073 <para>
6074 You can change the set of tests run by appending or overriding
6075 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
6076 variable in <filename>local.conf</filename>.
6077 Each name in <filename>TEST_SUITES</filename> represents a
6078 required test for the image.
6079 Test modules named within <filename>TEST_SUITES</filename>
6080 cannot be skipped even if a test is not suitable for an image
6081 (e.g. running the RPM tests on an image without
6082 <filename>rpm</filename>).
6083 Appending "auto" to <filename>TEST_SUITES</filename> causes the
6084 build system to try to run all tests that are suitable for the
6085 image (i.e. each test module may elect to skip itself).
6086 </para>
6087
6088 <para>
6089 The order you list tests in <filename>TEST_SUITES</filename>
6090 is important and influences test dependencies.
6091 Consequently, tests that depend on other tests should be added
6092 after the test on which they depend.
6093 For example, since the <filename>ssh</filename> test
6094 depends on the
6095 <filename>ping</filename> test, "ssh" needs to come after
6096 "ping" in the list.
6097 The test class provides no re-ordering or dependency handling.
6098 <note>
6099 Each module can have multiple classes with multiple test
6100 methods.
6101 And, Python <filename>unittest</filename> rules apply.
6102 </note>
6103 </para>
6104
6105 <para>
6106 Here are some things to keep in mind when running tests:
6107 <itemizedlist>
6108 <listitem><para>The default tests for the image are defined
6109 as:
6110 <literallayout class='monospaced'>
6111 DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
6112 </literallayout></para></listitem>
6113 <listitem><para>Add your own test to the list of the
6114 by using the following:
6115 <literallayout class='monospaced'>
6116 TEST_SUITES_append = " mytest"
6117 </literallayout></para></listitem>
6118 <listitem><para>Run a specific list of tests as follows:
6119 <literallayout class='monospaced'>
6120 TEST_SUITES = "test1 test2 test3"
6121 </literallayout>
6122 Remember, order is important.
6123 Be sure to place a test that is dependent on another test
6124 later in the order.</para></listitem>
6125 </itemizedlist>
6126 </para>
6127 </section>
6128
6129 <section id="exporting-tests">
6130 <title>Exporting Tests</title>
6131
6132 <para>
6133 You can export tests so that they can run independently of
6134 the build system.
6135 Exporting tests is required if you want to be able to hand
6136 the test execution off to a scheduler.
6137 You can only export tests that are defined in
6138 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
6139 </para>
6140
6141 <para>
6142 If you image is already built, make sure the following are set
6143 in your <filename>local.conf</filename> file.
6144 Be sure to provide the IP address you need:
6145 <literallayout class='monospaced'>
6146 TEST_EXPORT_ONLY = "1"
6147 TEST_TARGET = "simpleremote"
6148 TEST_TARGET_IP = "192.168.7.2"
6149 TEST_SERVER_IP = "192.168.7.1"
6150 </literallayout>
6151 You can then export the tests with the following:
6152 <literallayout class='monospaced'>
6153 $ bitbake core-image-sato -c testimage
6154 </literallayout>
6155 Exporting the tests places them in the
6156 <link linkend='build-directory'>Build Directory</link> in
6157 <filename>tmp/testimage/core-image-sato</filename>, which
6158 is controlled by the
6159 <filename>TEST_EXPORT_DIR</filename> variable.
6160 </para>
6161
6162 <para>
6163 The exported data (i.e. <filename>testdata.json</filename>)
6164 contains paths to the Build Directory.
6165 Thus, the contents of the directory can be moved
6166 to another machine as long as you update some paths in the
6167 JSON.
6168 Usually you only care about the
6169 ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests
6170 are enabled).
6171 Consequently, running the tests on other machine
6172 means that you have to move the contents and call
6173 <filename>runexported</filename> with "--deploy-dir PATH:
6174 ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json
6175 runexported.py accepts other arguments as well, see --help.
6176 </para>
6177
6178 <para>
6179 You can now run the tests outside of the build environment:
6180 <literallayout class='monospaced'>
6181 $ cd tmp/testimage/core-image-sato
6182 $ ./runexported.py testdata.json
6183 </literallayout>
6184 <note>
6185 This "export" feature does not deploy or boot the target
6186 image.
6187 Your target (be it a Qemu or hardware one)
6188 has to already be up and running when you call
6189 <filename>runexported.py</filename>
6190 </note>
6191 </para>
6192 </section>
6193
6194 <section id="qemu-image-writing-new-tests">
6195 <title>Writing New Tests</title>
6196
6197 <para>
6198 As mentioned previously, all new test files need to be in the
6199 proper place for the build system to find them.
6200 New tests for additional functionality outside of the core
6201 should be added to the layer that adds the functionality, in
6202 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
6203 long as
6204 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6205 is extended in the layer's
6206 <filename>layer.conf</filename> file as normal).
6207 Just remember that filenames need to map directly to test
6208 (module) names and that you do not use module names that
6209 collide with existing core tests.
6210 </para>
6211
6212 <para>
6213 To create a new test, start by copying an existing module
6214 (e.g. <filename>syslog.py</filename> or
6215 <filename>gcc.py</filename> are good ones to use).
6216 Test modules can use code from
6217 <filename>meta/lib/oeqa/utils</filename>, which are helper
6218 classes.
6219 </para>
6220
6221 <note>
6222 Structure shell commands such that you rely on them and they
6223 return a single code for success.
6224 Be aware that sometimes you will need to parse the output.
6225 See the <filename>df.py</filename> and
6226 <filename>date.py</filename> modules for examples.
6227 </note>
6228
6229 <para>
6230 You will notice that all test classes inherit
6231 <filename>oeRuntimeTest</filename>, which is found in
6232 <filename>meta/lib/oetest.py</filename>.
6233 This base class offers some helper attributes, which are
6234 described in the following sections:
6235 </para>
6236
6237 <section id='qemu-image-writing-tests-class-methods'>
6238 <title>Class Methods</title>
6239
6240 <para>
6241 Class methods are as follows:
6242 <itemizedlist>
6243 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
6244 Returns "True" if <filename>pkg</filename> is in the
6245 installed package list of the image, which is based
6246 on the manifest file that is generated during the
6247 <filename>do.rootfs</filename> task.
6248 </para></listitem>
6249 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
6250 Returns "True" if the feature is in
6251 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6252 or
6253 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
6254 </para></listitem>
6255 </itemizedlist>
6256 </para>
6257 </section>
6258
6259 <section id='qemu-image-writing-tests-class-attributes'>
6260 <title>Class Attributes</title>
6261
6262 <para>
6263 Class attributes are as follows:
6264 <itemizedlist>
6265 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
6266 Equals "ps -ef" if <filename>procps</filename> is
6267 installed in the image.
6268 Otherwise, <filename>pscmd</filename> equals
6269 "ps" (busybox).
6270 </para></listitem>
6271 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
6272 The called text context, which gives access to the
6273 following attributes:
6274 <itemizedlist>
6275 <listitem><para><emphasis><filename>d</filename>:</emphasis>
6276 The BitBake datastore, which allows you to
6277 use stuff such as
6278 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
6279 </para></listitem>
6280 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
6281 Used internally.
6282 The tests do not need these.
6283 </para></listitem>
6284 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
6285 The absolute path to
6286 <filename>meta/lib/oeqa/runtime/files</filename>,
6287 which contains helper files for tests meant
6288 for copying on the target such as small
6289 files written in C for compilation.
6290 </para></listitem>
6291 <listitem><para><emphasis><filename>target</filename>:</emphasis>
6292 The target controller object used to deploy
6293 and start an image on a particular target
6294 (e.g. QemuTarget, SimpleRemote, and
6295 GummibootTarget).
6296 Tests usually use the following:
6297 <itemizedlist>
6298 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
6299 The target's IP address.
6300 </para></listitem>
6301 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
6302 The host's IP address, which is
6303 usually used by the "smart" test
6304 suite.
6305 </para></listitem>
6306 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
6307 The single, most used method.
6308 This command is a wrapper for:
6309 <filename>ssh root@host "cmd"</filename>.
6310 The command returns a tuple:
6311 (status, output), which are what
6312 their names imply - the return code
6313 of 'cmd' and whatever output
6314 it produces.
6315 The optional timeout argument
6316 represents the number of seconds the
6317 test should wait for 'cmd' to
6318 return.
6319 If the argument is "None", the
6320 test uses the default instance's
6321 timeout period, which is 300
6322 seconds.
6323 If the argument is "0", the test
6324 runs until the command returns.
6325 </para></listitem>
6326 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
6327 <filename>scp localpath root@ip:remotepath</filename>.
6328 </para></listitem>
6329 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
6330 <filename>scp root@host:remotepath localpath</filename>.
6331 </para></listitem>
6332 </itemizedlist></para></listitem>
6333 </itemizedlist></para></listitem>
6334 </itemizedlist>
6335 </para>
6336 </section>
6337
6338 <section id='qemu-image-writing-tests-instance-attributes'>
6339 <title>Instance Attributes</title>
6340
6341 <para>
6342 A single instance attribute exists, which is
6343 <filename>target</filename>.
6344 The <filename>target</filename> instance attribute is
6345 identical to the class attribute of the same name, which
6346 is described in the previous section.
6347 This attribute exists as both an instance and class
6348 attribute so tests can use
6349 <filename>self.target.run(cmd)</filename> in instance
6350 methods instead of
6351 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
6352 </para>
6353 </section>
6354 </section>
6355 </section>
6356
6357 <section id="platdev-gdb-remotedebug">
6358 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
6359
6360 <para>
6361 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
6362 It also allows you to perform post-mortem style analysis of program crashes.
6363 GDB is available as a package within the Yocto Project and is
6364 installed in SDK images by default.
6365 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
6366 in the Yocto Project Reference Manual for a description of these images.
6367 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
6368 </para>
6369
6370 <tip>
6371 For best results, install DBG (<filename>-dbg</filename>) packages
6372 for the applications you are going to debug.
6373 Doing so makes extra debug symbols available that give you more
6374 meaningful output.
6375 </tip>
6376
6377 <para>
6378 Sometimes, due to memory or disk space constraints, it is not possible
6379 to use GDB directly on the remote target to debug applications.
6380 These constraints arise because GDB needs to load the debugging information and the
6381 binaries of the process being debugged.
6382 Additionally, GDB needs to perform many computations to locate information such as function
6383 names, variable names and values, stack traces and so forth - even before starting the
6384 debugging process.
6385 These extra computations place more load on the target system and can alter the
6386 characteristics of the program being debugged.
6387 </para>
6388
6389 <para>
6390 To help get past the previously mentioned constraints, you can use Gdbserver.
6391 Gdbserver runs on the remote target and does not load any debugging information
6392 from the debugged process.
6393 Instead, a GDB instance processes the debugging information that is run on a
6394 remote computer - the host GDB.
6395 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
6396 program, as well as read or write memory regions of that debugged program.
6397 All the debugging information loaded and processed as well
6398 as all the heavy debugging is done by the host GDB.
6399 Offloading these processes gives the Gdbserver running on the target a chance to remain
6400 small and fast.
6401 </para>
6402
6403 <para>
6404 Because the host GDB is responsible for loading the debugging information and
6405 for doing the necessary processing to make actual debugging happen, the
6406 user has to make sure the host can access the unstripped binaries complete
6407 with their debugging information and also be sure the target is compiled with no optimizations.
6408 The host GDB must also have local access to all the libraries used by the
6409 debugged program.
6410 Because Gdbserver does not need any local debugging information, the binaries on
6411 the remote target can remain stripped.
6412 However, the binaries must also be compiled without optimization
6413 so they match the host's binaries.
6414 </para>
6415
6416 <para>
6417 To remain consistent with GDB documentation and terminology, the binary being debugged
6418 on the remote target machine is referred to as the "inferior" binary.
6419 For documentation on GDB see the
6420 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
6421 </para>
6422
6423 <para>
6424 The remainder of this section describes the steps you need to take
6425 to debug using the GNU project debugger.
6426 </para>
6427
6428 <section id='platdev-gdb-remotedebug-setup'>
6429 <title>Set Up the Cross-Development Debugging Environment</title>
6430
6431 <para>
6432 Before you can initiate a remote debugging session, you need
6433 to be sure you have set up the cross-development environment,
6434 toolchain, and sysroot.
6435 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
6436 chapter of the Yocto Project Application Developer's Guide
6437 describes this process.
6438 Be sure you have read that chapter and have set up
6439 your environment.
6440 </para>
6441 </section>
6442
6443 <section id="platdev-gdb-remotedebug-launch-gdbserver">
6444 <title>Launch Gdbserver on the Target</title>
6445
6446 <para>
6447 Make sure Gdbserver is installed on the target.
6448 If it is not, install the package
6449 <filename>gdbserver</filename>, which needs the
6450 <filename>libthread-db1</filename> package.
6451 </para>
6452
6453 <para>
6454 Here is an example that when entered from the host
6455 connects to the target and launches Gdbserver in order to
6456 "debug" a binary named <filename>helloworld</filename>:
6457 <literallayout class='monospaced'>
6458 $ gdbserver localhost:2345 /usr/bin/helloworld
6459 </literallayout>
6460 Gdbserver should now be listening on port 2345 for debugging
6461 commands coming from a remote GDB process that is running on
6462 the host computer.
6463 Communication between Gdbserver and the host GDB are done
6464 using TCP.
6465 To use other communication protocols, please refer to the
6466 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
6467 </para>
6468 </section>
6469
6470 <section id="platdev-gdb-remotedebug-launch-gdb">
6471 <title>Launch GDB on the Host Computer</title>
6472
6473 <para>
6474 Running GDB on the host computer takes a number of stages, which
6475 this section describes.
6476 </para>
6477
6478 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
6479 <title>Build the Cross-GDB Package</title>
6480 <para>
6481 A suitable GDB cross-binary is required that runs on your
6482 host computer but also knows about the the ABI of the
6483 remote target.
6484 You can get this binary from the
6485 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
6486 Here is an example where the toolchain has been installed
6487 in the default directory
6488 <filename>/opt/poky/&DISTRO;</filename>:
6489 <literallayout class='monospaced'>
6490 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
6491 </literallayout>
6492 where <filename>arm</filename> is the target architecture
6493 and <filename>linux-gnueabi</filename> is the target ABI.
6494 </para>
6495
6496 <para>
6497 Alternatively, you can use BitBake to build the
6498 <filename>gdb-cross</filename> binary.
6499 Here is an example:
6500 <literallayout class='monospaced'>
6501 $ bitbake gdb-cross
6502 </literallayout>
6503 Once the binary is built, you can find it here:
6504 <literallayout class='monospaced'>
6505 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
6506 </literallayout>
6507 </para>
6508 </section>
6509
6510 <section id='create-the-gdb-initialization-file'>
6511 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
6512
6513 <para>
6514 Aside from the GDB cross-binary, you also need a GDB
6515 initialization file in the same top directory in which
6516 your binary resides.
6517 When you start GDB on your host development system, GDB
6518 finds this initialization file and executes all the
6519 commands within.
6520 For information on the <filename>.gdbinit</filename>, see
6521 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
6522 which is maintained by
6523 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
6524 </para>
6525
6526 <para>
6527 You need to add a statement in the
6528 <filename>.gdbinit</filename> file that points to your
6529 root filesystem.
6530 Here is an example that points to the root filesystem for
6531 an ARM-based target device:
6532 <literallayout class='monospaced'>
6533 set sysroot /home/jzhang/sysroot_arm
6534 </literallayout>
6535 </para>
6536 </section>
6537
6538 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
6539 <title>Launch the Host GDB</title>
6540
6541 <para>
6542 Before launching the host GDB, you need to be sure
6543 you have sourced the cross-debugging environment script,
6544 which if you installed the root filesystem in the default
6545 location is at <filename>/opt/poky/&DISTRO;</filename>
6546 and begins with the string "environment-setup".
6547 For more information, see the
6548 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
6549 section in the Yocto Project Application Developer's
6550 Guide.
6551 </para>
6552
6553 <para>
6554 Finally, switch to the directory where the binary resides
6555 and run the <filename>cross-gdb</filename> binary.
6556 Provide the binary file you are going to debug.
6557 For example, the following command continues with the
6558 example used in the previous section by loading
6559 the <filename>helloworld</filename> binary as well as the
6560 debugging information:
6561 <literallayout class='monospaced'>
6562 $ arm-poky-linux-gnuabi-gdb helloworld
6563 </literallayout>
6564 The commands in your <filename>.gdbinit</filename> execute
6565 and the GDB prompt appears.
6566 </para>
6567 </section>
6568 </section>
6569
6570 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
6571 <title>Connect to the Remote GDB Server</title>
6572
6573 <para>
6574 From the target, you need to connect to the remote GDB
6575 server that is running on the host.
6576 You need to specify the remote host and port.
6577 Here is the command continuing with the example:
6578 <literallayout class='monospaced'>
6579 target remote 192.168.7.2:2345
6580 </literallayout>
6581 </para>
6582 </section>
6583
6584 <section id="platdev-gdb-remotedebug-launch-gdb-using">
6585 <title>Use the Debugger</title>
6586
6587 <para>
6588 You can now proceed with debugging as normal - as if you were debugging
6589 on the local machine.
6590 For example, to instruct GDB to break in the "main" function and then
6591 continue with execution of the inferior binary use the following commands
6592 from within GDB:
6593 <literallayout class='monospaced'>
6594 (gdb) break main
6595 (gdb) continue
6596 </literallayout>
6597 </para>
6598
6599 <para>
6600 For more information about using GDB, see the project's online documentation at
6601 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
6602 </para>
6603 </section>
6604 </section>
6605
6606 <section id="examining-builds-using-toaster">
6607 <title>Examining Builds Using the Toaster API</title>
6608
6609 <para>
6610 Toaster is an Application Programming Interface (API) and
6611 web-based interface to the OpenEmbedded build system, which uses
6612 BitBake.
6613 Both interfaces are based on a Representational State Transfer
6614 (REST) API that queries for and returns build information using
6615 <filename>GET</filename> and <filename>JSON</filename>.
6616 These types of search operations retrieve sets of objects from
6617 a datastore used to collect build information.
6618 The results contain all the data for the objects being returned.
6619 You can order the results of the search by key and the search
6620 parameters are consistent for all object types.
6621 </para>
6622
6623 <para>
6624 Using the interfaces you can do the following:
6625 <itemizedlist>
6626 <listitem><para>See information about the tasks executed
6627 and reused during the build.</para></listitem>
6628 <listitem><para>See what is built (recipes and
6629 packages) and what packages were installed into the final
6630 image.</para></listitem>
6631 <listitem><para>See performance-related information such
6632 as build time, CPU usage, and disk I/O.</para></listitem>
6633 <listitem><para>Examine error, warning and trace messages
6634 to aid in debugging.</para></listitem>
6635 </itemizedlist>
6636 </para>
6637
6638 <note>
6639 <para>This release of Toaster provides you with information
6640 about a BitBake run.
6641 The tool does not allow you to configure and launch a build.
6642 However, future development includes plans to integrate the
6643 configuration and build launching capabilities of
6644 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
6645 </para>
6646 <para>For more information on using Hob to build an image,
6647 see the
6648 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
6649 section.</para>
6650 </note>
6651
6652 <para>
6653 The remainder of this section describes what you need to have in
6654 place to use Toaster, how to start it, use it, and stop it.
6655 For additional information on installing and running Toaster, see the
6656 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
6657 section of the "Toaster" wiki page.
6658 For complete information on the API and its search operation
6659 URI, parameters, and responses, see the
6660 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
6661 Wiki page.
6662 </para>
6663
6664 <section id='starting-toaster'>
6665 <title>Starting Toaster</title>
6666
6667 <para>
6668 Getting set up to use and start Toaster is simple.
6669 First, be sure you have met the following requirements:
6670 <itemizedlist>
6671 <listitem><para>You have set up your
6672 <link linkend='source-directory'>Source Directory</link>
6673 by cloning the upstream <filename>poky</filename>
6674 repository.
6675 See the
6676 <link linkend='local-yp-release'>Yocto Project Release</link>
6677 item for information on how to set up the Source
6678 Directory.</para></listitem>
6679 <listitem><para>Be sure your build machine has
6680 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
6681 version 1.5 installed.</para></listitem>
6682 <listitem><para>Make sure that port 8000 and 8200 are
6683 free (i.e. they have no servers on them).
6684 </para></listitem>
6685 </itemizedlist>
6686 </para>
6687
6688 <para>
6689 Once you have met the requirements, follow these steps to
6690 start Toaster running in the background of your shell:
6691 <orderedlist>
6692 <listitem><para><emphasis>Set up your build environment:</emphasis>
6693 Source a build environment script (i.e.
6694 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
6695 or
6696 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
6697 </para></listitem>
6698 <listitem><para><emphasis>Start Toaster:</emphasis>
6699 Start the Toaster service using this
6700 command from within your
6701 <link linkend='build-directory'>Build Directory</link>:
6702 <literallayout class='monospaced'>
6703 $ source toaster start
6704 </literallayout></para></listitem>
6705 <note>
6706 The Toaster must be started and running in order
6707 for it to collect data.
6708 </note>
6709 </orderedlist>
6710 </para>
6711
6712 <para>
6713 When Toaster starts, it creates some additional files in your
6714 Build Directory.
6715 Deleting these files will cause you to lose data or interrupt
6716 Toaster:
6717 <itemizedlist>
6718 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
6719 Toaster's database file.</para></listitem>
6720 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
6721 The log file of the web server.</para></listitem>
6722 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
6723 The log file of the user interface component.
6724 </para></listitem>
6725 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
6726 The PID of the web server.</para></listitem>
6727 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
6728 The PID of the DSI data bridge.</para></listitem>
6729 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
6730 The BitBake server's log file.</para></listitem>
6731 </itemizedlist>
6732 </para>
6733 </section>
6734
6735 <section id='using-toaster'>
6736 <title>Using Toaster</title>
6737
6738 <para>
6739 Once Toaster is running, it logs information for any BitBake
6740 run from your Build Directory.
6741 This logging is automatic.
6742 All you need to do is access and use the information.
6743 </para>
6744
6745 <para>
6746 You access the information one of two ways:
6747 <itemizedlist>
6748 <listitem><para>Open a Browser and enter
6749 <filename>http://localhost:8000</filename>
6750 for the URL.
6751 </para></listitem>
6752 <listitem><para>Use the <filename>xdg-open</filename>
6753 tool from the shell and pass it the same URL.
6754 </para></listitem>
6755 </itemizedlist>
6756 Either method opens the home page for the Toaster interface.
6757 </para>
6758
6759 <note><title>Notes</title>
6760 <para>
6761 For information on how to delete information from the Toaster
6762 database, see the
6763 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
6764 wiki page.
6765 </para>
6766
6767 <para>
6768 For information on how to set up an instance of Toaster on
6769 a remote host, see the
6770 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink>
6771 wiki page.
6772 </para>
6773 </note>
6774 </section>
6775
6776 <section id='examining-toaster-data'>
6777 <title>Examining Toaster Data</title>
6778
6779 <para>
6780 The Toaster database is persistent regardless of whether you
6781 start or stop the service.
6782 </para>
6783
6784 <para>
6785 Toaster's interface shows you a list of builds
6786 (successful and unsuccessful) for which it has data.
6787 You can click on any build to see related information.
6788 This information includes configuration details, information
6789 about tasks, all recipes and packages built and their
6790 dependencies, packages and their directory structure as
6791 installed in your final image,
6792 execution time, CPU usage and disk I/O per task.
6793 </para>
6794
6795 <para>
6796 For details on the interface, see the
6797 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
6798 </para>
6799 </section>
6800
6801 <section id='stopping-toaster'>
6802 <title>Stopping Toaster</title>
6803
6804 <para>
6805 Stop the Toaster service with the following command
6806 from with the
6807 <link linkend='build-directory'>Build Directory</link>:
6808 <literallayout class='monospaced'>
6809 $ source toaster stop
6810 </literallayout>
6811 The service stops but the Toaster database remains persistent.
6812 </para>
6813 </section>
6814 </section>
6815
6816 <section id="platdev-oprofile">
6817 <title>Profiling with OProfile</title>
6818
6819 <para>
6820 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
6821 statistical profiler well suited for finding performance
6822 bottlenecks in both user-space software and in the kernel.
6823 This profiler provides answers to questions like "Which functions does my application spend
6824 the most time in when doing X?"
6825 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
6826 applications on target hardware straight forward.
6827 <note>
6828 For more information on how to set up and run OProfile, see the
6829 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
6830 section in the Yocto Project Profiling and Tracing Manual.
6831 </note>
6832 </para>
6833
6834 <para>
6835 To use OProfile, you need an image that has OProfile installed.
6836 The easiest way to do this is with "tools-profile" in the
6837 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
6838 You also need debugging symbols to be available on the system where the analysis
6839 takes place.
6840 You can gain access to the symbols by using "dbg-pkgs" in the
6841 <filename>IMAGE_FEATURES</filename> variable or by
6842 installing the appropriate DBG (<filename>-dbg</filename>) packages.
6843 </para>
6844
6845 <para>
6846 For successful call graph analysis, the binaries must preserve the frame
6847 pointer register and should also be compiled with the
6848 <filename>-fno-omit-framepointer</filename> flag.
6849 You can achieve this by setting the
6850 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
6851 variable with the following options:
6852 <literallayout class='monospaced'>
6853 -fexpensive-optimizations
6854 -fno-omit-framepointer
6855 -frename-registers
6856 -O2
6857 </literallayout>
6858 You can also achieve it by setting the
6859 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
6860 variable to "1" in the <filename>local.conf</filename> configuration file.
6861 If you use the <filename>DEBUG_BUILD</filename> variable,
6862 you also add extra debugging information that can make the debug
6863 packages large.
6864 </para>
6865
6866 <section id="platdev-oprofile-target">
6867 <title>Profiling on the Target</title>
6868
6869 <para>
6870 Using OProfile, you can perform all the profiling work on the target device.
6871 A simple OProfile session might look like the following:
6872 </para>
6873
6874 <para>
6875 <literallayout class='monospaced'>
6876 # opcontrol --reset
6877 # opcontrol --start --separate=lib --no-vmlinux -c 5
6878 .
6879 .
6880 [do whatever is being profiled]
6881 .
6882 .
6883 # opcontrol --stop
6884 $ opreport -cl
6885 </literallayout>
6886 </para>
6887
6888 <para>
6889 In this example, the <filename>reset</filename> command clears any previously profiled data.
6890 The next command starts OProfile.
6891 The options used when starting the profiler separate dynamic library data
6892 within applications, disable kernel profiling, and enable callgraphing up to
6893 five levels deep.
6894 <note>
6895 To profile the kernel, you would specify the
6896 <filename>--vmlinux=/path/to/vmlinux</filename> option.
6897 The <filename>vmlinux</filename> file is usually in the source directory in the
6898 <filename>/boot/</filename> directory and must match the running kernel.
6899 </note>
6900 </para>
6901
6902 <para>
6903 After you perform your profiling tasks, the next command stops the profiler.
6904 After that, you can view results with the <filename>opreport</filename> command with options
6905 to see the separate library symbols and callgraph information.
6906 </para>
6907
6908 <para>
6909 Callgraphing logs information about time spent in functions and about a function's
6910 calling function (parent) and called functions (children).
6911 The higher the callgraphing depth, the more accurate the results.
6912 However, higher depths also increase the logging overhead.
6913 Consequently, you should take care when setting the callgraphing depth.
6914 <note>
6915 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
6916 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
6917 with <filename>gcc</filename>.
6918 </note>
6919 </para>
6920
6921 <para>
6922 For more information on using OProfile, see the OProfile
6923 online documentation at
6924 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
6925 </para>
6926 </section>
6927
6928 <section id="platdev-oprofile-oprofileui">
6929 <title>Using OProfileUI</title>
6930
6931 <para>
6932 A graphical user interface for OProfile is also available.
6933 You can download and build this interface from the Yocto Project at
6934 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
6935 If the "tools-profile" image feature is selected, all necessary binaries
6936 are installed onto the target device for OProfileUI interaction.
6937 For a list of image features that ship with the Yocto Project,
6938 see the
6939 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
6940 section in the Yocto Project Reference Manual.
6941 </para>
6942
6943 <para>
6944 Even though the source directory usually includes all needed patches on the target device, you
6945 might find you need other OProfile patches for recent OProfileUI features.
6946 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
6947 OProfileUI README</ulink> for the most recent information.
6948 </para>
6949
6950 <section id="platdev-oprofile-oprofileui-online">
6951 <title>Online Mode</title>
6952
6953 <para>
6954 Using OProfile in online mode assumes a working network connection with the target
6955 hardware.
6956 With this connection, you just need to run "oprofile-server" on the device.
6957 By default, OProfile listens on port 4224.
6958 <note>
6959 You can change the port using the <filename>--port</filename> command-line
6960 option.
6961 </note>
6962 </para>
6963
6964 <para>
6965 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
6966 straight forward.
6967 You access key functionality through the buttons on the toolbar, which
6968 are duplicated in the menus.
6969 Here are the buttons:
6970 <itemizedlist>
6971 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
6972 You can also supply the IP address or hostname.</para></listitem>
6973 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
6974 </para></listitem>
6975 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
6976 </para></listitem>
6977 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
6978 downloads the data to the local host.
6979 Stopping the profiler generates the profile and displays it in the viewer.
6980 </para></listitem>
6981 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
6982 target and generates the profile, which appears in the viewer.</para></listitem>
6983 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
6984 Resetting the data removes sample information collected from previous
6985 sampling runs.
6986 Be sure you reset the data if you do not want to include old sample information.
6987 </para></listitem>
6988 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
6989 target to another directory for later examination.</para></listitem>
6990 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
6991 </para></listitem>
6992 </itemizedlist>
6993 </para>
6994
6995 <para>
6996 The client downloads the complete profile archive from
6997 the target to the host for processing.
6998 This archive is a directory that contains the sample data, the object files,
6999 and the debug information for the object files.
7000 The archive is then converted using the <filename>oparchconv</filename> script, which is
7001 included in this distribution.
7002 The script uses <filename>opimport</filename> to convert the archive from
7003 the target to something that can be processed on the host.
7004 </para>
7005
7006 <para>
7007 Downloaded archives reside in the
7008 <link linkend='build-directory'>Build Directory</link> in
7009 <filename>tmp</filename> and are cleared up when they are no longer in use.
7010 </para>
7011
7012 <para>
7013 If you wish to perform kernel profiling, you need to be sure
7014 a <filename>vmlinux</filename> file that matches the running kernel is available.
7015 In the source directory, that file is usually located in
7016 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
7017 <filename>KERNEL-version</filename> is the version of the kernel.
7018 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
7019 packages for each kernel it builds.
7020 Thus, it should just be a question of making sure a matching package is
7021 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
7022 The files are automatically installed into development and profiling images
7023 alongside OProfile.
7024 A configuration option exists within the OProfileUI settings page that you can use to
7025 enter the location of the <filename>vmlinux</filename> file.
7026 </para>
7027
7028 <para>
7029 Waiting for debug symbols to transfer from the device can be slow, and it
7030 is not always necessary to actually have them on the device for OProfile use.
7031 All that is needed is a copy of the filesystem with the debug symbols present
7032 on the viewer system.
7033 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
7034 section covers how to create such a directory within
7035 the source directory and how to use the OProfileUI Settings
7036 Dialog to specify the location.
7037 If you specify the directory, it will be used when the file checksums
7038 match those on the system you are profiling.
7039 </para>
7040 </section>
7041
7042 <section id="platdev-oprofile-oprofileui-offline">
7043 <title>Offline Mode</title>
7044
7045 <para>
7046 If network access to the target is unavailable, you can generate
7047 an archive for processing in <filename>oprofile-viewer</filename> as follows:
7048 <literallayout class='monospaced'>
7049 # opcontrol --reset
7050 # opcontrol --start --separate=lib --no-vmlinux -c 5
7051 .
7052 .
7053 [do whatever is being profiled]
7054 .
7055 .
7056 # opcontrol --stop
7057 # oparchive -o my_archive
7058 </literallayout>
7059 </para>
7060
7061 <para>
7062 In the above example, <filename>my_archive</filename> is the name of the
7063 archive directory where you would like the profile archive to be kept.
7064 After the directory is created, you can copy it to another host and load it
7065 using <filename>oprofile-viewer</filename> open functionality.
7066 If necessary, the archive is converted.
7067 </para>
7068 </section>
7069 </section>
7070 </section>
7071
7072 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
7073 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
7074
7075 <para>
7076 One of the concerns for a development organization using open source
7077 software is how to maintain compliance with various open source
7078 licensing during the lifecycle of the product.
7079 While this section does not provide legal advice or
7080 comprehensively cover all scenarios, it does
7081 present methods that you can use to
7082 assist you in meeting the compliance requirements during a software
7083 release.
7084 </para>
7085
7086 <para>
7087 With hundreds of different open source licenses that the Yocto
7088 Project tracks, it is difficult to know the requirements of each
7089 and every license.
7090 However, the requirements of the major FLOSS licenses can begin
7091 to be covered by
7092 assuming that three main areas of concern exist:
7093 <itemizedlist>
7094 <listitem><para>Source code must be provided.</para></listitem>
7095 <listitem><para>License text for the software must be
7096 provided.</para></listitem>
7097 <listitem><para>Compilation scripts and modifications to the
7098 source code must be provided.
7099 </para></listitem>
7100 </itemizedlist>
7101 There are other requirements beyond the scope of these
7102 three and the methods described in this section
7103 (e.g. the mechanism through which source code is distributed).
7104 </para>
7105
7106 <para>
7107 As different organizations have different methods of complying with
7108 open source licensing, this section is not meant to imply that
7109 there is only one single way to meet your compliance obligations,
7110 but rather to describe one method of achieving compliance.
7111 The remainder of this section describes methods supported to meet the
7112 previously mentioned three requirements.
7113 Once you take steps to meet these requirements,
7114 and prior to releasing images, sources, and the build system,
7115 you should audit all artifacts to ensure completeness.
7116 <note>
7117 The Yocto Project generates a license manifest during
7118 image creation that is located
7119 in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
7120 to assist with any audits.
7121 </note>
7122 </para>
7123
7124 <section id='providing-the-source-code'>
7125 <title>Providing the Source Code</title>
7126
7127 <para>
7128 Compliance activities should begin before you generate the
7129 final image.
7130 The first thing you should look at is the requirement that
7131 tops the list for most compliance groups - providing
7132 the source.
7133 The Yocto Project has a few ways of meeting this
7134 requirement.
7135 </para>
7136
7137 <para>
7138 One of the easiest ways to meet this requirement is
7139 to provide the entire
7140 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
7141 used by the build.
7142 This method, however, has a few issues.
7143 The most obvious is the size of the directory since it includes
7144 all sources used in the build and not just the source used in
7145 the released image.
7146 It will include toolchain source, and other artifacts, which
7147 you would not generally release.
7148 However, the more serious issue for most companies is accidental
7149 release of proprietary software.
7150 The Yocto Project provides an
7151 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
7152 class to help avoid some of these concerns.
7153 </para>
7154
7155 <para>
7156 Before you employ <filename>DL_DIR</filename> or the
7157 archiver class, you need to decide how you choose to
7158 provide source.
7159 The source archiver class can generate tarballs and SRPMs
7160 and can create them with various levels of compliance in mind.
7161 </para>
7162
7163 <para>
7164 One way of doing this (but certainly not the only way) is to
7165 release just the source as a tarball.
7166 You can do this by adding the following to the
7167 <filename>local.conf</filename> file found in the
7168 <link linkend='build-directory'>Build Directory</link>:
7169 <literallayout class='monospaced'>
7170 INHERIT += "archiver"
7171 ARCHIVER_MODE[src] = "original"
7172 </literallayout>
7173 During the creation of your image, the source from all
7174 recipes that deploy packages to the image is placed within
7175 subdirectories of
7176 <filename>DEPLOY_DIR/sources</filename> based on the
7177 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
7178 for each recipe.
7179 Releasing the entire directory enables you to comply with
7180 requirements concerning providing the unmodified source.
7181 It is important to note that the size of the directory can
7182 get large.
7183 </para>
7184
7185 <para>
7186 A way to help mitigate the size issue is to only release
7187 tarballs for licenses that require the release of
7188 source.
7189 Let us assume you are only concerned with GPL code as
7190 identified with the following:
7191 <literallayout class='monospaced'>
7192 $ cd poky/build/tmp/deploy/sources
7193 $ mkdir ~/gpl_source_release
7194 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
7195 </literallayout>
7196 At this point, you could create a tarball from the
7197 <filename>gpl_source_release</filename> directory and
7198 provide that to the end user.
7199 This method would be a step toward achieving compliance
7200 with section 3a of GPLv2 and with section 6 of GPLv3.
7201 </para>
7202 </section>
7203
7204 <section id='providing-license-text'>
7205 <title>Providing License Text</title>
7206
7207 <para>
7208 One requirement that is often overlooked is inclusion
7209 of license text.
7210 This requirement also needs to be dealt with prior to
7211 generating the final image.
7212 Some licenses require the license text to accompany
7213 the binary.
7214 You can achieve this by adding the following to your
7215 <filename>local.conf</filename> file:
7216 <literallayout class='monospaced'>
7217 COPY_LIC_MANIFEST = "1"
7218 COPY_LIC_DIRS = "1"
7219 </literallayout>
7220 Adding these statements to the configuration file ensures
7221 that the licenses collected during package generation
7222 are included on your image.
7223 As the source archiver has already archived the original
7224 unmodified source that contains the license files,
7225 you would have already met the requirements for inclusion
7226 of the license information with source as defined by the GPL
7227 and other open source licenses.
7228 </para>
7229 </section>
7230
7231 <section id='providing-compilation-scripts-and-source-code-modifications'>
7232 <title>Providing Compilation Scripts and Source Code Modifications</title>
7233
7234 <para>
7235 At this point, we have addressed all we need to address
7236 prior to generating the image.
7237 The next two requirements are addressed during the final
7238 packaging of the release.
7239 </para>
7240
7241 <para>
7242 By releasing the version of the OpenEmbedded build system
7243 and the layers used during the build, you will be providing both
7244 compilation scripts and the source code modifications in one
7245 step.
7246 </para>
7247
7248 <para>
7249 If the deployment team has a
7250 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
7251 and a distro layer, and those those layers are used to patch,
7252 compile, package, or modify (in any way) any open source
7253 software included in your released images, you
7254 might be required to to release those layers under section 3 of
7255 GPLv2 or section 1 of GPLv3.
7256 One way of doing that is with a clean
7257 checkout of the version of the Yocto Project and layers used
7258 during your build.
7259 Here is an example:
7260 <literallayout class='monospaced'>
7261 # We built using the &DISTRO_NAME; branch of the poky repo
7262 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
7263 $ cd poky
7264 # We built using the release_branch for our layers
7265 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
7266 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
7267 # clean up the .git repos
7268 $ find . -name ".git" -type d -exec rm -rf {} \;
7269 </literallayout>
7270 One thing a development organization might want to consider
7271 for end-user convenience is to modify
7272 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
7273 ensure that when the end user utilizes the released build
7274 system to build an image, the development organization's
7275 layers are included in the <filename>bblayers.conf</filename>
7276 file automatically:
7277 <literallayout class='monospaced'>
7278 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
7279 # changes incompatibly
7280 LCONF_VERSION = "6"
7281
7282 BBPATH = "${TOPDIR}"
7283 BBFILES ?= ""
7284
7285 BBLAYERS ?= " \
7286 ##OEROOT##/meta \
7287 ##OEROOT##/meta-yocto \
7288 ##OEROOT##/meta-yocto-bsp \
7289 ##OEROOT##/meta-mylayer \
7290 "
7291
7292 BBLAYERS_NON_REMOVABLE ?= " \
7293 ##OEROOT##/meta \
7294 ##OEROOT##/meta-yocto \
7295 "
7296 </literallayout>
7297 Creating and providing an archive of the
7298 <link linkend='metadata'>Metadata</link> layers
7299 (recipes, configuration files, and so forth)
7300 enables you to meet your
7301 requirements to include the scripts to control compilation
7302 as well as any modifications to the original source.
7303 </para>
7304 </section>
7305 </section>
7306
7307 <section id='using-the-error-reporting-tool'>
7308 <title>Using the Error Reporting Tool</title>
7309
7310 <para>
7311 The error reporting tool allows you to
7312 submit errors encountered during builds to a central database.
7313 Outside of the build environment, you can use a web interface to
7314 browse errors, view statistics, and query for errors.
7315 The tool works using a client-server system where the client
7316 portion is integrated with the installed Yocto Project
7317 <link linkend='source-directory'>Source Directory</link>
7318 (e.g. <filename>poky</filename>).
7319 The server receives the information collected and saves it in a
7320 database.
7321 </para>
7322
7323 <para>
7324 A live instance of the error reporting server exists at
7325 <ulink url='http://errors.yoctoproject.org'></ulink>.
7326 This server exists so that when you want to get help with
7327 build failures, you can submit all of the information on the
7328 failure easily and then point to the URL in your bug report
7329 or send an email to the mailing list.
7330 <note>
7331 If you send error reports to this server, the reports become
7332 publicly visible.
7333 </note>
7334 </para>
7335
7336 <section id='enabling-and-using-the-tool'>
7337 <title>Enabling and Using the Tool</title>
7338
7339 <para>
7340 By default, the error reporting tool is disabled.
7341 You can enable it by inheriting the
7342 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
7343 class by adding the following statement to the end of
7344 your <filename>local.conf</filename> file in your
7345 <link linkend='build-directory'>Build Directory</link>.
7346 <literallayout class='monospaced'>
7347 INHERIT += "report-error"
7348 </literallayout>
7349 </para>
7350
7351 <para>
7352 By default, the error reporting feature stores information in
7353 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
7354 However, you can specify a directory to use by adding the following
7355 to your <filename>local.conf</filename> file:
7356 <literallayout class='monospaced'>
7357 ERR_REPORT_DIR = "path"
7358 </literallayout>
7359 Enabling error reporting causes the build process to collect
7360 the errors and store them in a file as previously described.
7361 When the build system encounters an error, it includes a command
7362 as part of the console output.
7363 You can run the command to send the error file to the server.
7364 For example, the following command sends the errors to an upstream
7365 server:
7366 <literallayout class='monospaced'>
7367 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
7368 </literallayout>
7369 In the above example, the <filename>server</filename> parameter is
7370 optional.
7371 By default, the errors are sent to a database used by the entire
7372 community.
7373 If you specify a particular server, you can send them to a different
7374 database.
7375 </para>
7376
7377 <para>
7378 When sending the error file, you receive a link that corresponds
7379 to your entry in the database.
7380 For example, here is a typical link:
7381 <literallayout class='monospaced'>
7382 http://localhost:8000/Errors/Search/1/158
7383 </literallayout>
7384 Following the link takes you to a web interface where you can
7385 browse, query the errors, and view statistics.
7386 </para>
7387 </section>
7388
7389 <section id='disabling-the-tool'>
7390 <title>Disabling the Tool</title>
7391
7392 <para>
7393 To disable the error reporting feature, simply remove or comment
7394 out the following statement from the end of your
7395 <filename>local.conf</filename> file in your
7396 <link linkend='build-directory'>Build Directory</link>.
7397 <literallayout class='monospaced'>
7398 INHERIT += "report-error"
7399 </literallayout>
7400 </para>
7401 </section>
7402
7403 <section id='setting-up-your-own-error-reporting-server'>
7404 <title>Setting Up Your Own Error Reporting Server</title>
7405
7406 <para>
7407 If you want to set up your own error reporting server, you
7408 can obtain the code from the Git repository at
7409 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
7410 Instructions on how to set it up are in the README document.
7411 </para>
7412 </section>
7413 </section>
7414</chapter>
7415
7416<!--
7417vim: expandtab tw=80 ts=4
7418-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 03:46:09 +0000