summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
committerAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
commit067445c1487c1a73e0ee8a9ae3e82d446406ab57 (patch)
treed47aa232ce1c82cf47aa348f20902937e073239a /documentation/dev-manual/dev-manual-common-tasks.xml
downloadyocto-docs-daisy.tar.gz
initial commit for Enea Linux 4.0daisy
Migrated from the internal git server on the daisy-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml8501
1 files changed, 8501 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..0d16dbe
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,8501 @@
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='understanding-recipe-syntax'>
1287 <title>Understanding Recipe Syntax</title>
1288
1289 <para>
1290 Understanding recipe file syntax is important for
1291 writing recipes.
1292 The following list overviews the basic items that make up a
1293 BitBake recipe file.
1294 For more complete BitBake syntax descriptions, see the
1295 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
1296 chapter of the BitBake User Manual.
1297 <itemizedlist>
1298 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1299 Variable assignments allow a value to be assigned to a
1300 variable.
1301 The assignment can be static text or might include
1302 the contents of other variables.
1303 In addition to the assignment, appending and prepending
1304 operations are also supported.</para>
1305 <para>The following example shows some of the ways
1306 you can use variables in recipes:
1307 <literallayout class='monospaced'>
1308 S = "${WORKDIR}/postfix-${PV}"
1309 CFLAGS += "-DNO_ASM"
1310 SRC_URI_append = " file://fixup.patch"
1311 </literallayout>
1312 </para></listitem>
1313 <listitem><para><emphasis>Functions:</emphasis>
1314 Functions provide a series of actions to be performed.
1315 You usually use functions to override the default
1316 implementation of a task function or to compliment
1317 a default function (i.e. append or prepend to an
1318 existing function).
1319 Standard functions use <filename>sh</filename> shell
1320 syntax, although access to OpenEmbedded variables and
1321 internal methods are also available.</para>
1322 <para>The following is an example function from the
1323 <filename>sed</filename> recipe:
1324 <literallayout class='monospaced'>
1325 do_install () {
1326 autotools_do_install
1327 install -d ${D}${base_bindir}
1328 mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN}
1329 }
1330 </literallayout>
1331 It is also possible to implement new functions that
1332 are called between existing tasks as long as the
1333 new functions are not replacing or complimenting the
1334 default functions.
1335 You can implement functions in Python
1336 instead of shell.
1337 Both of these options are not seen in the majority of
1338 recipes.</para></listitem>
1339 <listitem><para><emphasis>Keywords:</emphasis>
1340 BitBake recipes use only a few keywords.
1341 You use keywords to include common
1342 functions (<filename>inherit</filename>), load parts
1343 of a recipe from other files
1344 (<filename>include</filename> and
1345 <filename>require</filename>) and export variables
1346 to the environment (<filename>export</filename>).</para>
1347 <para>The following example shows the use of some of
1348 these keywords:
1349 <literallayout class='monospaced'>
1350 export POSTCONF = "${STAGING_BINDIR}/postconf"
1351 inherit autoconf
1352 require otherfile.inc
1353 </literallayout>
1354 </para></listitem>
1355 <listitem><para><emphasis>Comments:</emphasis>
1356 Any lines that begin with the hash character
1357 (<filename>#</filename>) are treated as comment lines
1358 and are ignored:
1359 <literallayout class='monospaced'>
1360 # This is a comment
1361 </literallayout>
1362 </para></listitem>
1363 </itemizedlist>
1364 </para>
1365
1366 <para>
1367 This next list summarizes the most important and most commonly
1368 used parts of the recipe syntax.
1369 For more information on these parts of the syntax, you can
1370 reference the
1371 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1372 chapter in the BitBake User Manual.
1373 <itemizedlist>
1374 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1375 Use the backward slash (<filename>\</filename>)
1376 character to split a statement over multiple lines.
1377 Place the slash character at the end of the line that
1378 is to be continued on the next line:
1379 <literallayout class='monospaced'>
1380 VAR = "A really long \
1381 line"
1382 </literallayout>
1383 <note>
1384 You cannot have any characters including spaces
1385 or tabs after the slash character.
1386 </note>
1387 </para></listitem>
1388 <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1389 Use the <filename>${&lt;varname&gt;}</filename> syntax to
1390 access the contents of a variable:
1391 <literallayout class='monospaced'>
1392 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1393 </literallayout>
1394 </para></listitem>
1395 <listitem><para><emphasis>Quote All Assignments: <filename>"&lt;value&gt;"</filename></emphasis> -
1396 Use double quotes around the value in all variable
1397 assignments.
1398 <literallayout class='monospaced'>
1399 VAR1 = "${OTHERVAR}"
1400 VAR2 = "The version is ${PV}"
1401 </literallayout>
1402 </para></listitem>
1403 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1404 Conditional assignment is used to assign a value to
1405 a variable, but only when the variable is currently
1406 unset.
1407 Use the question mark followed by the equal sign
1408 (<filename>?=</filename>) to make a "soft" assignment
1409 used for conditional assignment.
1410 Typically, "soft" assignments are used in the
1411 <filename>local.conf</filename> file for variables
1412 that are allowed to come through from the external
1413 environment.
1414 </para>
1415 <para>Here is an example where
1416 <filename>VAR1</filename> is set to "New value" if
1417 it is currently empty.
1418 However, if <filename>VAR1</filename> has already been
1419 set, it remains unchanged:
1420 <literallayout class='monospaced'>
1421 VAR1 ?= "New value"
1422 </literallayout>
1423 In this next example, <filename>VAR1</filename>
1424 is left with the value "Original value":
1425 <literallayout class='monospaced'>
1426 VAR1 = "Original value"
1427 VAR1 ?= "New value"
1428 </literallayout>
1429 </para></listitem>
1430 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1431 Use the plus character followed by the equals sign
1432 (<filename>+=</filename>) to append values to existing
1433 variables.
1434 <note>
1435 This operator adds a space between the existing
1436 content of the variable and the new content.
1437 </note></para>
1438 <para>Here is an example:
1439 <literallayout class='monospaced'>
1440 SRC_URI += "file://fix-makefile.patch"
1441 </literallayout>
1442 </para></listitem>
1443 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1444 Use the equals sign followed by the plus character
1445 (<filename>=+</filename>) to prepend values to existing
1446 variables.
1447 <note>
1448 This operator adds a space between the new content
1449 and the existing content of the variable.
1450 </note></para>
1451 <para>Here is an example:
1452 <literallayout class='monospaced'>
1453 VAR =+ "Starts"
1454 </literallayout>
1455 </para></listitem>
1456 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1457 Use the <filename>_append</filename> operator to
1458 append values to existing variables.
1459 This operator does not add any additional space.
1460 Also, the operator is applied after all the
1461 <filename>+=</filename>, and
1462 <filename>=+</filename> operators have been applied and
1463 after all <filename>=</filename> assignments have
1464 occurred.
1465 </para>
1466 <para>The following example shows the space being
1467 explicitly added to the start to ensure the appended
1468 value is not merged with the existing value:
1469 <literallayout class='monospaced'>
1470 SRC_URI_append = " file://fix-makefile.patch"
1471 </literallayout>
1472 You can also use the <filename>_append</filename>
1473 operator with overrides, which results in the actions
1474 only being performed for the specified target or
1475 machine:
1476 <literallayout class='monospaced'>
1477 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1478 </literallayout>
1479 </para></listitem>
1480 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1481 Use the <filename>_prepend</filename> operator to
1482 prepend values to existing variables.
1483 This operator does not add any additional space.
1484 This operator does not add any additional space.
1485 Also, the operator is applied after all the
1486 <filename>+=</filename>, and
1487 <filename>=+</filename> operators have been applied and
1488 after all <filename>=</filename> assignments have
1489 occurred.
1490 </para>
1491 <para>The following example shows the space being
1492 explicitly added to the end to ensure the prepended
1493 value is not merged with the existing value:
1494 <literallayout class='monospaced'>
1495 CFLAGS_prepend = "-I${S}/myincludes "
1496 </literallayout>
1497 You can also use the <filename>_prepend</filename>
1498 operator with overrides, which results in the actions
1499 only being performed for the specified target or
1500 machine:
1501 <literallayout class='monospaced'>
1502 CFLAGS_prepend_sh4 = " file://fix-makefile.patch"
1503 </literallayout>
1504 </para></listitem>
1505 <listitem><para><emphasis>Overrides:</emphasis> -
1506 You can use overrides to set a value conditionally,
1507 typically on how the recipe is being built.
1508 For example, to set the
1509 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1510 variable's value to "standard/base" for any target
1511 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1512 except for qemuarm where it should be set to
1513 "standard/arm-versatile-926ejs", you would do the
1514 following:
1515 <literallayout class='monospaced'>
1516 KBRANCH = "standard/base"
1517 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1518 </literallayout>
1519 Overrides are also used to separate alternate values
1520 of a variable in other situations.
1521 For example, when setting variables such as
1522 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1523 and
1524 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
1525 that are specific to individual packages produced by
1526 a recipe, you should always use an override that
1527 specifies the name of the package.
1528 </para></listitem>
1529 <listitem><para><emphasis>Indentation:</emphasis>
1530 Use spaces for indentation rather than than tabs.
1531 For shell functions, both currently work.
1532 However, it is a policy decision of the Yocto Project
1533 to use tabs in shell functions.
1534 Realize that some layers have a policy to use spaces
1535 for all indentation.
1536 </para></listitem>
1537 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@&lt;python_code&gt;}</filename></emphasis> -
1538 For more advanced processing, it is possible to use
1539 Python code during variable assignments (e.g.
1540 search and replacement on a variable).</para>
1541 <para>You indicate Python code using the
1542 <filename>${@&lt;python_code&gt;}</filename>
1543 syntax for the variable assignment:
1544 <literallayout class='monospaced'>
1545 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1546 </literallayout>
1547 </para></listitem>
1548 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1549 Write shell functions as if you were writing a shell
1550 script when you describe a list of actions to take.
1551 You should ensure that your script works with a generic
1552 <filename>sh</filename> and that it does not require
1553 any <filename>bash</filename> or other shell-specific
1554 functionality.
1555 The same considerations apply to various system
1556 utilities (e.g. <filename>sed</filename>,
1557 <filename>grep</filename>, <filename>awk</filename>,
1558 and so forth) that you might wish to use.
1559 If in doubt, you should check with multiple
1560 implementations - including those from BusyBox.
1561 </para></listitem>
1562 </itemizedlist>
1563 </para>
1564 </section>
1565
1566 <section id='new-recipe-running-a-build-on-the-recipe'>
1567 <title>Running a Build on the Recipe</title>
1568
1569 <para>
1570 Creating a new recipe is usually an iterative process that
1571 requires using BitBake to process the recipe multiple times in
1572 order to progressively discover and add information to the
1573 recipe.
1574 </para>
1575
1576 <para>
1577 Assuming you have sourced a build environment setup script (i.e.
1578 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1579 or
1580 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1581 and you are in the
1582 <link linkend='build-directory'>Build Directory</link>,
1583 use BitBake to process your recipe.
1584 All you need to provide is the
1585 <filename>&lt;basename&gt;</filename> of the recipe as described
1586 in the previous section:
1587 <literallayout class='monospaced'>
1588 $ bitbake &lt;basename&gt;
1589 </literallayout>
1590
1591 </para>
1592
1593 <para>
1594 During the build, the OpenEmbedded build system creates a
1595 temporary work directory for the recipe
1596 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1597 where it keeps extracted source files, log files, intermediate
1598 compilation and packaging files, and so forth.
1599 </para>
1600
1601 <para>
1602 The temporary work directory is constructed as follows and
1603 depends on several factors:
1604 <literallayout class='monospaced'>
1605 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1606 </literallayout>
1607 As an example, assume a Source Directory top-level folder named
1608 <filename>poky</filename>, a default Build Directory at
1609 <filename>poky/build</filename>, and a
1610 <filename>qemux86-poky-linux</filename> machine target system.
1611 Furthermore, suppose your recipe is named
1612 <filename>foo_1.3.0-r0.bb</filename>.
1613 In this case, the work directory the build system uses to
1614 build the package would be as follows:
1615 <literallayout class='monospaced'>
1616 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1617 </literallayout>
1618 Inside this directory you can find sub-directories such as
1619 <filename>image</filename>, <filename>packages-split</filename>,
1620 and <filename>temp</filename>.
1621 After the build, you can examine these to determine how well
1622 the build went.
1623 <note>
1624 You can find log files for each task in the recipe's
1625 <filename>temp</filename> directory (e.g.
1626 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1627 Log files are named <filename>log.&lt;taskname&gt;</filename>
1628 (e.g. <filename>log.do_configure</filename>,
1629 <filename>log.do_fetch</filename>, and
1630 <filename>log.do_compile</filename>).
1631 </note>
1632 </para>
1633
1634 <para>
1635 You can find more information about the build process in the
1636 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1637 chapter of the Yocto Project Reference Manual.
1638 </para>
1639
1640 <para>
1641 You can also reference the following variables in the
1642 Yocto Project Reference Manual's glossary for more information:
1643 <itemizedlist>
1644 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1645 The top-level build output directory</listitem>
1646 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1647 The target system identifier</listitem>
1648 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1649 The recipe name</listitem>
1650 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1651 The epoch - (if
1652 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1653 is not specified, which is usually the case for most
1654 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1655 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1656 The recipe version</listitem>
1657 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1658 The recipe revision</listitem>
1659 </itemizedlist>
1660 </para>
1661 </section>
1662
1663 <section id='new-recipe-fetching-code'>
1664 <title>Fetching Code</title>
1665
1666 <para>
1667 The first thing your recipe must do is specify how to fetch
1668 the source files.
1669 Fetching is controlled mainly through the
1670 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1671 variable.
1672 Your recipe must have a <filename>SRC_URI</filename> variable
1673 that points to where the source is located.
1674 For a graphical representation of source locations, see the
1675 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1676 section in the Yocto Project Reference Manual.
1677 </para>
1678
1679 <para>
1680 The
1681 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1682 task uses the prefix of each entry in the
1683 <filename>SRC_URI</filename> variable value to determine what
1684 fetcher to use to get your source files.
1685 It is the <filename>SRC_URI</filename> variable that triggers
1686 the fetcher.
1687 The
1688 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1689 task uses the variable after source is fetched to apply
1690 patches.
1691 The OpenEmbedded build system uses
1692 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1693 for scanning directory locations for local files in
1694 <filename>SRC_URI</filename>.
1695 </para>
1696
1697 <para>
1698 The <filename>SRC_URI</filename> variable in your recipe must
1699 define each unique location for your source files.
1700 It is good practice to not hard-code pathnames in an URL used
1701 in <filename>SRC_URI</filename>.
1702 Rather than hard-code these paths, use
1703 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1704 which causes the fetch process to use the version specified in
1705 the recipe filename.
1706 Specifying the version in this manner means that upgrading the
1707 recipe to a future version is as simple as renaming the recipe
1708 to match the new version.
1709 </para>
1710
1711 <para>
1712 Here is a simple example from the
1713 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
1714 recipe where the source comes from a single tarball.
1715 Notice the use of the
1716 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1717 variable:
1718 <literallayout class='monospaced'>
1719 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1720 </literallayout>
1721 </para>
1722
1723 <para>
1724 Files mentioned in <filename>SRC_URI</filename> whose names end
1725 in a typical archive extension (e.g. <filename>.tar</filename>,
1726 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1727 <filename>.zip</filename>, and so forth), are automatically
1728 extracted during the
1729 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1730 task.
1731 For another example that specifies these types of files, see
1732 the
1733 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1734 section.
1735 </para>
1736
1737 <para>
1738 Another way of specifying source is from an SCM.
1739 For Git repositories, you must specify
1740 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1741 and you should specify
1742 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1743 to include the revision with
1744 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1745 Here is an example from the recipe
1746 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1747 <literallayout class='monospaced'>
1748 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1749
1750 PR = "r6"
1751 PV = "1.0.5+git${SRCPV}"
1752
1753 SRC_URI = "git://git.kernel.dk/blktrace.git \
1754 file://ldflags.patch"
1755 </literallayout>
1756 </para>
1757
1758 <para>
1759 If your <filename>SRC_URI</filename> statement includes
1760 URLs pointing to individual files fetched from a remote server
1761 other than a version control system, BitBake attempts to
1762 verify the files against checksums defined in your recipe to
1763 ensure they have not been tampered with or otherwise modified
1764 since the recipe was written.
1765 Two checksums are used:
1766 <filename>SRC_URI[md5sum]</filename> and
1767 <filename>SRC_URI[sha256sum]</filename>.
1768 </para>
1769
1770 <para>
1771 If your <filename>SRC_URI</filename> variable points to
1772 more than a single URL (excluding SCM URLs), you need to
1773 provide the <filename>md5</filename> and
1774 <filename>sha256</filename> checksums for each URL.
1775 For these cases, you provide a name for each URL as part of
1776 the <filename>SRC_URI</filename> and then reference that name
1777 in the subsequent checksum statements.
1778 Here is an example:
1779 <literallayout class='monospaced'>
1780 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1781 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1782
1783 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1784 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1785
1786 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1787 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1788 </literallayout>
1789 </para>
1790
1791 <para>
1792 To find these checksums, you can comment the statements out
1793 and then attempt to build the software.
1794 The build will produce an error for each missing checksum
1795 and as part of the error message provide the correct checksum
1796 string.
1797 Once you have the correct checksums, simply copy them into your
1798 recipe for a subsequent build.
1799 </para>
1800
1801 <para>
1802 This final example is a bit more complicated and is from the
1803 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1804 recipe.
1805 The example's <filename>SRC_URI</filename> statement identifies
1806 multiple files as the source files for the recipe: a tarball, a
1807 patch file, a desktop file, and an icon.
1808 <literallayout class='monospaced'>
1809 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1810 file://xwc.patch \
1811 file://rxvt.desktop \
1812 file://rxvt.png"
1813 </literallayout>
1814 </para>
1815
1816 <para>
1817 When you specify local files using the
1818 <filename>file://</filename> URI protocol, the build system
1819 fetches files from the local machine.
1820 The path is relative to the
1821 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1822 variable and searches specific directories in a certain order:
1823 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1824 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1825 and <filename>files</filename>.
1826 The directories are assumed to be subdirectories of the
1827 directory in which the recipe or append file resides.
1828 For another example that specifies these types of files, see the
1829 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1830 section.
1831 </para>
1832
1833 <para>
1834 The previous example also specifies a patch file.
1835 Patch files are files whose names end in
1836 <filename>.patch</filename> or <filename>.diff</filename>.
1837 The build system automatically applies patches as described
1838 in the
1839 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1840 </para>
1841 </section>
1842
1843 <section id='new-recipe-unpacking-code'>
1844 <title>Unpacking Code</title>
1845
1846 <para>
1847 During the build, the
1848 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1849 task unpacks the source with
1850 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1851 pointing to where it is unpacked.
1852 </para>
1853
1854 <para>
1855 If you are fetching your source files from an upstream source
1856 archived tarball and the tarball's internal structure matches
1857 the common convention of a top-level subdirectory named
1858 <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>,
1859 then you do not need to set <filename>S</filename>.
1860 However, if <filename>SRC_URI</filename> specifies to fetch
1861 source from an archive that does not use this convention,
1862 or from an SCM like Git or Subversion, your recipe needs to
1863 define <filename>S</filename>.
1864 </para>
1865
1866 <para>
1867 If processing your recipe using BitBake successfully unpacks
1868 the source files, you need to be sure that the directory
1869 pointed to by <filename>${S}</filename> matches the structure
1870 of the source.
1871 </para>
1872 </section>
1873
1874 <section id='new-recipe-patching-code'>
1875 <title>Patching Code</title>
1876
1877 <para>
1878 Sometimes it is necessary to patch code after it has been
1879 fetched.
1880 Any files mentioned in <filename>SRC_URI</filename> whose
1881 names end in <filename>.patch</filename> or
1882 <filename>.diff</filename> are treated as patches.
1883 The
1884 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1885 task automatically applies these patches.
1886 </para>
1887
1888 <para>
1889 The build system should be able to apply patches with the "-p1"
1890 option (i.e. one directory level in the path will be stripped
1891 off).
1892 If your patch needs to have more directory levels stripped off,
1893 specify the number of levels using the "striplevel" option in
1894 the <filename>SRC_URI</filename> entry for the patch.
1895 Alternatively, if your patch needs to be applied in a specific
1896 subdirectory that is not specified in the patch file, use the
1897 "patchdir" option in the entry.
1898 </para>
1899
1900 <para>
1901 As with all local files referenced in
1902 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1903 using <filename>file://</filename>, you should place
1904 patch files in a directory next to the recipe either
1905 named the same as the base name of the recipe
1906 (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
1907 or "files".
1908 </para>
1909 </section>
1910
1911 <section id='new-recipe-licensing'>
1912 <title>Licensing</title>
1913
1914 <para>
1915 Your recipe needs to have both the
1916 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1917 and
1918 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1919 variables:
1920 <itemizedlist>
1921 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1922 This variable specifies the license for the software.
1923 If you do not know the license under which the software
1924 you are building is distributed, you should go to the
1925 source code and look for that information.
1926 Typical files containing this information include
1927 <filename>COPYING</filename>,
1928 <filename>LICENSE</filename>, and
1929 <filename>README</filename> files.
1930 You could also find the information near the top of
1931 a source file.
1932 For example, given a piece of software licensed under
1933 the GNU General Public License version 2, you would
1934 set <filename>LICENSE</filename> as follows:
1935 <literallayout class='monospaced'>
1936 LICENSE = "GPLv2"
1937 </literallayout></para>
1938 <para>The licenses you specify within
1939 <filename>LICENSE</filename> can have any name as long
1940 as you do not use spaces, since spaces are used as
1941 separators between license names.
1942 For standard licenses, use the names of the files in
1943 <filename>meta/files/common-licenses/</filename>
1944 or the <filename>SPDXLICENSEMAP</filename> flag names
1945 defined in <filename>meta/conf/licenses.conf</filename>.
1946 </para></listitem>
1947 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1948 The OpenEmbedded build system uses this variable to
1949 make sure the license text has not changed.
1950 If it has, the build produces an error and it affords
1951 you the chance to figure it out and correct the problem.
1952 </para>
1953 <para>You need to specify all applicable licensing
1954 files for the software.
1955 At the end of the configuration step, the build process
1956 will compare the checksums of the files to be sure
1957 the text has not changed.
1958 Any differences result in an error with the message
1959 containing the current checksum.
1960 For more explanation and examples of how to set the
1961 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1962 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1963 section in the Yocto Project Reference Manual.</para>
1964 <para>To determine the correct checksum string, you
1965 can list the appropriate files in the
1966 <filename>LIC_FILES_CHKSUM</filename> variable with
1967 incorrect md5 strings, attempt to build the software,
1968 and then note the resulting error messages that will
1969 report the correct md5 strings.
1970 Here is an example that assumes the software has a
1971 <filename>COPYING</filename> file:
1972 <literallayout class='monospaced'>
1973 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
1974 </literallayout>
1975 When you try to build the software, the build system
1976 will produce an error and give you the correct string
1977 that you can substitute into the recipe file for a
1978 subsequent build.
1979 </para></listitem>
1980 </itemizedlist>
1981 </para>
1982
1983<!--
1984
1985 <para>
1986 For trying this out I created a new recipe named
1987 <filename>htop_1.0.2.bb</filename> and put it in
1988 <filename>poky/meta/recipes-extended/htop</filename>.
1989 There are two license type statements in my very simple
1990 recipe:
1991 <literallayout class='monospaced'>
1992 LICENSE = ""
1993
1994 LIC_FILES_CHKSUM = ""
1995
1996 SRC_URI[md5sum] = ""
1997 SRC_URI[sha256sum] = ""
1998 </literallayout>
1999 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
2000 Next, you delete or comment out the two <filename>SRC_URI</filename>
2001 lines at the end and then attempt to build the software with
2002 <filename>bitbake htop</filename>.
2003 Doing so causes BitBake to report some errors and and give
2004 you the actual strings you need for the last two
2005 <filename>SRC_URI</filename> lines.
2006 Prior to this, you have to dig around in the home page of the
2007 source for <filename>htop</filename> and determine that the
2008 software is released under GPLv2.
2009 You can provide that in the <filename>LICENSE</filename>
2010 statement.
2011 Now you edit your recipe to have those two strings for
2012 the <filename>SRC_URI</filename> statements:
2013 <literallayout class='monospaced'>
2014 LICENSE = "GPLv2"
2015
2016 LIC_FILES_CHKSUM = ""
2017
2018 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
2019 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
2020 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
2021 </literallayout>
2022 At this point, you can build the software again using the
2023 <filename>bitbake htop</filename> command.
2024 There is just a set of errors now associated with the
2025 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
2026 </para>
2027-->
2028
2029 </section>
2030
2031 <section id='new-recipe-configuring-the-recipe'>
2032 <title>Configuring the Recipe</title>
2033
2034 <para>
2035 Most software provides some means of setting build-time
2036 configuration options before compilation.
2037 Typically, setting these options is accomplished by running a
2038 configure script with some options, or by modifying a build
2039 configuration file.
2040 </para>
2041
2042 <para>
2043 A major part of build-time configuration is about checking for
2044 build-time dependencies and possibly enabling optional
2045 functionality as a result.
2046 You need to specify any build-time dependencies for the
2047 software you are building in your recipe's
2048 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2049 value, in terms of other recipes that satisfy those
2050 dependencies.
2051 You can often find build-time or runtime
2052 dependencies described in the software's documentation.
2053 </para>
2054
2055 <para>
2056 The following list provides configuration items of note based
2057 on how your software is built:
2058 <itemizedlist>
2059 <listitem><para><emphasis>Autotools:</emphasis>
2060 If your source files have a
2061 <filename>configure.ac</filename> file, then your
2062 software is built using Autotools.
2063 If this is the case, you just need to worry about
2064 tweaking the configuration.</para>
2065 <para>When using Autotools, your recipe needs to inherit
2066 the
2067 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2068 class and your recipe does not have to contain a
2069 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2070 task.
2071 However, you might still want to make some adjustments.
2072 For example, you can set
2073 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
2074 to pass any needed configure options that are specific
2075 to the recipe.</para></listitem>
2076 <listitem><para><emphasis>CMake:</emphasis>
2077 If your source files have a
2078 <filename>CMakeLists.txt</filename> file, then your
2079 software is built using CMake.
2080 If this is the case, you just need to worry about
2081 tweaking the configuration.</para>
2082 <para>When you use CMake, your recipe needs to inherit
2083 the
2084 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2085 class and your recipe does not have to contain a
2086 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2087 task.
2088 You can make some adjustments by setting
2089 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
2090 to pass any needed configure options that are specific
2091 to the recipe.</para></listitem>
2092 <listitem><para><emphasis>Other:</emphasis>
2093 If your source files do not have a
2094 <filename>configure.ac</filename> or
2095 <filename>CMakeLists.txt</filename> file, then your
2096 software is built using some method other than Autotools
2097 or CMake.
2098 If this is the case, you normally need to provide a
2099 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2100 task in your recipe
2101 unless, of course, there is nothing to configure.
2102 </para>
2103 <para>Even if your software is not being built by
2104 Autotools or CMake, you still might not need to deal
2105 with any configuration issues.
2106 You need to determine if configuration is even a required step.
2107 You might need to modify a Makefile or some configuration file
2108 used for the build to specify necessary build options.
2109 Or, perhaps you might need to run a provided, custom
2110 configure script with the appropriate options.</para>
2111 <para>For the case involving a custom configure
2112 script, you would run
2113 <filename>./configure --help</filename> and look for
2114 the options you need to set.</para></listitem>
2115 </itemizedlist>
2116 </para>
2117
2118 <para>
2119 Once configuration succeeds, it is always good practice to
2120 look at the <filename>log.do_configure</filename> file to
2121 ensure that the appropriate options have been enabled and no
2122 additional build-time dependencies need to be added to
2123 <filename>DEPENDS</filename>.
2124 For example, if the configure script reports that it found
2125 something not mentioned in <filename>DEPENDS</filename>, or
2126 that it did not find something that it needed for some
2127 desired optional functionality, then you would need to add
2128 those to <filename>DEPENDS</filename>.
2129 Looking at the log might also reveal items being checked for
2130 and/or enabled that you do not want, or items not being found
2131 that are in <filename>DEPENDS</filename>, in which case
2132 you would need to look at passing extra options to the
2133 configure script as needed.
2134 For reference information on configure options specific to the
2135 software you are building, you can consult the output of the
2136 <filename>./configure --help</filename> command within
2137 <filename>${S}</filename> or consult the software's upstream
2138 documentation.
2139 </para>
2140 </section>
2141
2142 <section id='new-recipe-compilation'>
2143 <title>Compilation</title>
2144
2145 <para>
2146 During a build, the <filename>do_compile</filename> task
2147 happens after source is fetched, unpacked, and configured.
2148 If the recipe passes through <filename>do_compile</filename>
2149 successfully, nothing needs to be done.
2150 </para>
2151
2152 <para>
2153 However, if the compile step fails, you need to diagnose the
2154 failure.
2155 Here are some common issues that cause failures:
2156 <itemizedlist>
2157 <listitem><para><emphasis>Parallel build failures:</emphasis>
2158 These failures manifest themselves as intermittent
2159 errors, or errors reporting that a file or directory
2160 that should be created by some other part of the build
2161 process could not be found.
2162 This type of failure can occur even if, upon inspection,
2163 the file or directory does exist after the build has
2164 failed, because that part of the build process happened
2165 in the wrong order.</para>
2166 <para>To fix the problem, you need to either satisfy
2167 the missing dependency in the Makefile or whatever
2168 script produced the Makefile, or (as a workaround)
2169 set
2170 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
2171 to an empty string:
2172 <literallayout class='monospaced'>
2173 PARALLEL_MAKE = ""
2174 </literallayout></para></listitem>
2175 <listitem><para><emphasis>Improper host path usage:</emphasis>
2176 This failure applies to recipes building for the target
2177 or <filename>nativesdk</filename> only.
2178 The failure occurs when the compilation process uses
2179 improper headers, libraries, or other files from the
2180 host system when cross-compiling for the target.
2181 </para>
2182 <para>To fix the problem, examine the
2183 <filename>log.do_compile</filename> file to identify
2184 the host paths being used (e.g.
2185 <filename>/usr/include</filename>,
2186 <filename>/usr/lib</filename>, and so forth) and then
2187 either add configure options, apply a patch, or do both.
2188 </para></listitem>
2189 <listitem><para><emphasis>Failure to find required
2190 libraries/headers:</emphasis>
2191 If a build-time dependency is missing because it has
2192 not been declared in
2193 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2194 or because the dependency exists but the path used by
2195 the build process to find the file is incorrect and the
2196 configure step did not detect it, the compilation
2197 process could fail.
2198 For either of these failures, the compilation process
2199 notes that files could not be found.
2200 In these cases, you need to go back and add additional
2201 options to the configure script as well as possibly
2202 add additional build-time dependencies to
2203 <filename>DEPENDS</filename>.</para>
2204 <para>Occasionally, it is necessary to apply a patch
2205 to the source to ensure the correct paths are used.
2206 If you need to specify paths to find files staged
2207 into the sysroot from other recipes, use the variables
2208 that the OpenEmbedded build system provides
2209 (e.g.
2210 <filename>STAGING_BINDIR</filename>,
2211 <filename>STAGING_INCDIR</filename>,
2212 <filename>STAGING_DATADIR</filename>, and so forth).
2213<!--
2214 (e.g.
2215 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
2216 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
2217 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
2218 and so forth).
2219-->
2220 </para></listitem>
2221 </itemizedlist>
2222 </para>
2223 </section>
2224
2225 <section id='new-recipe-installing'>
2226 <title>Installing</title>
2227
2228 <para>
2229 During <filename>do_install</filename>, the task copies the
2230 built files along with their hierarchy to locations that
2231 would mirror their locations on the target device.
2232 The installation process copies files from the
2233 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
2234 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
2235 and
2236 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
2237 directories to the
2238 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
2239 directory to create the structure as it should appear on the
2240 target system.
2241 </para>
2242
2243 <para>
2244 How your software is built affects what you must do to be
2245 sure your software is installed correctly.
2246 The following list describes what you must do for installation
2247 depending on the type of build system used by the software
2248 being built:
2249 <itemizedlist>
2250 <listitem><para><emphasis>Autotools and CMake:</emphasis>
2251 If the software your recipe is building uses Autotools
2252 or CMake, the OpenEmbedded build
2253 system understands how to install the software.
2254 Consequently, you do not have to have a
2255 <filename>do_install</filename> task as part of your
2256 recipe.
2257 You just need to make sure the install portion of the
2258 build completes with no issues.
2259 However, if you wish to install additional files not
2260 already being installed by
2261 <filename>make install</filename>, you should do this
2262 using a <filename>do_install_append</filename> function
2263 using the install command as described in
2264 <emphasis>Manual</emphasis> later in this list.
2265 </para></listitem>
2266 <listitem><para><emphasis>Other (using
2267 <filename>make install</filename>):</emphasis>
2268 You need to define a
2269 <filename>do_install</filename> function in your
2270 recipe.
2271 The function should call
2272 <filename>oe_runmake install</filename> and will likely
2273 need to pass in the destination directory as well.
2274 How you pass that path is dependent on how the
2275 <filename>Makefile</filename> being run is written
2276 (e.g. <filename>DESTDIR=${D}</filename>,
2277 <filename>PREFIX=${D}</filename>,
2278 <filename>INSTALLROOT=${D}</filename>, and so forth).
2279 </para>
2280 <para>For an example recipe using
2281 <filename>make install</filename>, see the
2282 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
2283 section.</para></listitem>
2284 <listitem><para><emphasis>Manual:</emphasis>
2285 You need to define a
2286 <filename>do_install</filename> function in your
2287 recipe.
2288 The function must first use
2289 <filename>install -d</filename> to create the
2290 directories under
2291 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
2292 Once the directories exist, your function can use
2293 <filename>install</filename> to manually install the
2294 built software into the directories.</para>
2295 <para>You can find more information on
2296 <filename>install</filename> at
2297 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
2298 </para></listitem>
2299 </itemizedlist>
2300 </para>
2301
2302 <para>
2303 For the scenarios that do not use Autotools or
2304 CMake, you need to track the installation
2305 and diagnose and fix any issues until everything installs
2306 correctly.
2307 You need to look in the default location of
2308 <filename>${D}</filename>, which is
2309 <filename>${WORKDIR}/image</filename>, to be sure your
2310 files have been installed correctly.
2311 </para>
2312
2313 <note>
2314 During the installation process, you might need to modify
2315 some of the installed files to suit the target layout.
2316 For example, you might need to replace hard-coded paths in an
2317 initscript with values of variables provided by the build
2318 system, such as replacing <filename>/usr/bin/</filename> with
2319 <filename>${bindir}</filename>.
2320 If you do perform such modifications during
2321 <filename>do_install</filename>, be sure to modify the
2322 destination file after copying rather than before copying.
2323 Modifying after copying ensures that the build system can
2324 re-execute <filename>do_install</filename> if needed.
2325 </note>
2326
2327 <note>
2328 <filename>oe_runmake install</filename>, which can be run
2329 directly or can be run indirectly by the
2330 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2331 and
2332 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2333 classes, runs <filename>make install</filename> in parallel.
2334 Sometimes, a Makefile can have missing dependencies between
2335 targets that can result in race conditions.
2336 If you experience intermittent failures during
2337 <filename>do_install</filename>, you might be able to work
2338 around them by disabling parallel Makefile installs
2339 by adding the following to the recipe:
2340 <literallayout class='monospaced'>
2341 PARALLEL_MAKEINST = ""
2342 </literallayout>
2343 See
2344 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2345 for additional information.
2346 </note>
2347 </section>
2348
2349 <section id='new-recipe-enabling-system-services'>
2350 <title>Enabling System Services</title>
2351
2352 <para>
2353 If you want to install a service, which is a process that
2354 usually starts on boot and runs in the background, then
2355 you must include some additional definitions in your recipe.
2356 </para>
2357
2358 <para>
2359 If you are adding services and the service initialization
2360 script or the service file itself is not installed, you must
2361 provide for that installation in your recipe using a
2362 <filename>do_install_append</filename> function.
2363 If your recipe already has a <filename>do_install</filename>
2364 function, update the function near its end rather than
2365 adding an additional <filename>do_install_append</filename>
2366 function.
2367 </para>
2368
2369 <para>
2370 When you create the installation for your services, you need
2371 to accomplish what is normally done by
2372 <filename>make install</filename>.
2373 In other words, make sure your installation arranges the output
2374 similar to how it is arranged on the target system.
2375 </para>
2376
2377 <para>
2378 The OpenEmbedded build system provides support for starting
2379 services two different ways:
2380 <itemizedlist>
2381 <listitem><para><emphasis>SysVinit:</emphasis>
2382 SysVinit is a system and service manager that
2383 manages the init system used to control the very basic
2384 functions of your system.
2385 The init program is the first program
2386 started by the Linux kernel when the system boots.
2387 Init then controls the startup, running and shutdown
2388 of all other programs.</para>
2389 <para>To enable a service using SysVinit, your recipe
2390 needs to inherit the
2391 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2392 class.
2393 The class helps facilitate safely installing the
2394 package on the target.</para>
2395 <para>You will need to set the
2396 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2397 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2398 and
2399 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2400 variables within your recipe.</para></listitem>
2401 <listitem><para><emphasis>systemd:</emphasis>
2402 System Management Daemon (systemd) was designed to
2403 replace SysVinit and to provide
2404 enhanced management of services.
2405 For more information on systemd, see the systemd
2406 homepage at
2407 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2408 </para>
2409 <para>To enable a service using systemd, your recipe
2410 needs to inherit the
2411 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2412 class.
2413 See the <filename>systemd.class</filename> file
2414 located in your
2415 <link linkend='source-directory'>Source Directory</link>.
2416 section for more information.
2417 </para></listitem>
2418 </itemizedlist>
2419 </para>
2420 </section>
2421
2422 <section id='new-recipe-packaging'>
2423 <title>Packaging</title>
2424
2425 <para>
2426 Successful packaging is a combination of automated processes
2427 performed by the OpenEmbedded build system and some
2428 specific steps you need to take.
2429 The following list describes the process:
2430 <itemizedlist>
2431 <listitem><para><emphasis>Splitting Files</emphasis>:
2432 The <filename>do_package</filename> task splits the
2433 files produced by the recipe into logical components.
2434 Even software that produces a single binary might
2435 still have debug symbols, documentation, and other
2436 logical components that should be split out.
2437 The <filename>do_package</filename> task ensures
2438 that files are split up and packaged correctly.
2439 </para></listitem>
2440 <listitem><para><emphasis>Running QA Checks</emphasis>:
2441 The <filename>insane</filename> class adds a step to
2442 the package generation process so that output quality
2443 assurance checks are generated by the OpenEmbedded
2444 build system.
2445 This step performs a range of checks to be sure the
2446 build's output is free of common problems that show
2447 up during runtime.
2448 For information on these checks, see the
2449 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2450 class and the
2451 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
2452 chapter in the Yocto Project Reference Manual.
2453 </para></listitem>
2454 <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
2455 After you build your software, you need to be sure
2456 your packages are correct.
2457 Examine the
2458 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2459 directory and make sure files are where you expect
2460 them to be.
2461 If you discover problems, you can set
2462 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2463 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2464 <filename>do_install(_append)</filename>, and so forth as
2465 needed.
2466 </para></listitem>
2467 <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
2468 If you need to split an application into several
2469 packages, see the
2470 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2471 section for an example.
2472 </para></listitem>
2473 <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
2474 For an example showing how to install a
2475 post-installation script, see the
2476 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2477 section.
2478 </para></listitem>
2479 <listitem><para><emphasis>Marking Package Architecture</emphasis>:
2480 Depending on what your recipe is building and how it
2481 is configured, it might be important to mark the
2482 packages produced as being specific to a particular
2483 machine, or to mark them as not being specific to
2484 a particular machine or architecture at all.
2485 By default, packages produced for the target are
2486 marked as being specific to the architecture of the
2487 target machine because that is usually the desired
2488 result.
2489 However, if the recipe configures the software to be
2490 built specific to the target machine (e.g. the
2491 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2492 value is passed into the configure script or a patch
2493 is applied only for a particular machine), then you
2494 should mark the packages produced as being
2495 machine-specific by adding the following to the
2496 recipe:
2497 <literallayout class='monospaced'>
2498 PACKAGE_ARCH = "${MACHINE_ARCH}"
2499 </literallayout>
2500 On the other hand, if the recipe produces packages
2501 that do not contain anything specific to the target
2502 machine or architecture at all (e.g. recipes
2503 that simply package script files or configuration
2504 files), you should use the
2505 <ulink url='&YOCTO_DOCS_REF_URL;#allarch'><filename>allarch</filename></ulink>
2506 class to do this for you by adding this to your
2507 recipe:
2508 <literallayout class='monospaced'>
2509 inherit allarch
2510 </literallayout>
2511 Ensuring that the package architecture is correct is
2512 not critical while you are doing the first few builds
2513 of your recipe.
2514 However, it is important in order to
2515 to ensure that your recipe rebuilds (or does not
2516 rebuild) appropriately in response to changes in
2517 configuration, and to ensure that you get the
2518 appropriate packages installed on the target machine,
2519 particularly if you run separate builds for more
2520 than one target machine.
2521 </para></listitem>
2522 </itemizedlist>
2523 </para>
2524 </section>
2525
2526 <section id='properly-versioning-pre-release-recipes'>
2527 <title>Properly Versioning Pre-Release Recipes</title>
2528
2529 <para>
2530 Sometimes the name of a recipe can lead to versioning
2531 problems when the recipe is upgraded to a final release.
2532 For example, consider the
2533 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2534 the list of example recipes in the
2535 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2536 section.
2537 This recipe is at a release candidate stage (i.e.
2538 "rc1").
2539 When the recipe is released, the recipe filename becomes
2540 <filename>irssi_0.8.16.bb</filename>.
2541 The version change from <filename>0.8.16-rc1</filename>
2542 to <filename>0.8.16</filename> is seen as a decrease by the
2543 build system and package managers, so the resulting packages
2544 will not correctly trigger an upgrade.
2545 </para>
2546
2547 <para>
2548 In order to ensure the versions compare properly, the
2549 recommended convention is to set
2550 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2551 within the recipe to
2552 "&lt;previous version&gt;+&lt;current version&gt;".
2553 You can use an additional variable so that you can use the
2554 current version elsewhere.
2555 Here is an example:
2556 <literallayout class='monospaced'>
2557 REALPV = "0.8.16-rc1"
2558 PV = "0.8.15+${REALPV}"
2559 </literallayout>
2560 </para>
2561 </section>
2562
2563 <section id='new-recipe-post-installation-scripts'>
2564 <title>Post-Installation Scripts</title>
2565
2566 <para>
2567 Post-installation scripts run immediately after installing
2568 a package on the target, or during image creation when a
2569 package is included in an image.
2570 To add a post-installation script to a package, add a
2571 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2572 the recipe file (<filename>.bb</filename>) and replace
2573 <filename>PACKAGENAME</filename> with the name of the package
2574 you want to attach to the <filename>postinst</filename>
2575 script.
2576 To apply the post-installation script to the main package
2577 for the recipe, which is usually what is required, specify
2578 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2579 in place of <filename>PACKAGENAME</filename>.
2580 </para>
2581
2582 <para>
2583 A post-installation function has the following structure:
2584 <literallayout class='monospaced'>
2585 pkg_postinst_PACKAGENAME () {
2586 #!/bin/sh -e
2587 # Commands to carry out
2588 }
2589 </literallayout>
2590 </para>
2591
2592 <para>
2593 The script defined in the post-installation function is
2594 called when the root filesystem is created.
2595 If the script succeeds, the package is marked as installed.
2596 If the script fails, the package is marked as unpacked and
2597 the script is executed when the image boots again.
2598 </para>
2599
2600 <para>
2601 Sometimes it is necessary for the execution of a
2602 post-installation script to be delayed until the first boot.
2603 For example, the script might need to be executed on the
2604 device itself.
2605 To delay script execution until boot time, use the following
2606 structure in the post-installation script:
2607 <literallayout class='monospaced'>
2608 pkg_postinst_PACKAGENAME () {
2609 #!/bin/sh -e
2610 if [ x"$D" = "x" ]; then
2611 # Actions to carry out on the device go here
2612 else
2613 exit 1
2614 fi
2615 }
2616 </literallayout>
2617 </para>
2618
2619 <para>
2620 The previous example delays execution until the image boots
2621 again because the environment variable <filename>D</filename>
2622 points to the directory containing the image when
2623 the root filesystem is created at build time but is unset
2624 when executed on the first boot.
2625 </para>
2626
2627 <note>
2628 Equivalent support for pre-install, pre-uninstall, and
2629 post-uninstall scripts exist by way of
2630 <filename>pkg_preinst</filename>,
2631 <filename>pkg_prerm</filename>, and
2632 <filename>pkg_postrm</filename>, respectively.
2633 These scrips work in exactly the same way as does
2634 <filename>pkg_postinst</filename> with the exception that they
2635 run at different times.
2636 Also, because of when they run, they are not applicable to
2637 being run at image creation time like
2638 <filename>pkg_postinst</filename>.
2639 </note>
2640 </section>
2641
2642 <section id='new-recipe-testing'>
2643 <title>Testing</title>
2644
2645 <para>
2646 The final step for completing your recipe is to be sure that
2647 the software you built runs correctly.
2648 To accomplish runtime testing, add the build's output
2649 packages to your image and test them on the target.
2650 </para>
2651
2652 <para>
2653 For information on how to customize your image by adding
2654 specific packages, see the
2655 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2656 section.
2657 </para>
2658 </section>
2659
2660 <section id='new-recipe-testing-examples'>
2661 <title>Examples</title>
2662
2663 <para>
2664 To help summarize how to write a recipe, this section provides
2665 some examples given various scenarios:
2666 <itemizedlist>
2667 <listitem><para>Recipes that use local files</para></listitem>
2668 <listitem><para>Using an Autotooled package</para></listitem>
2669 <listitem><para>Using a Makefile-based package</para></listitem>
2670 <listitem><para>Splitting an application into multiple packages</para></listitem>
2671 </itemizedlist>
2672 </para>
2673
2674 <section id='new-recipe-single-c-file-package-hello-world'>
2675 <title>Single .c File Package (Hello World!)</title>
2676
2677 <para>
2678 Building an application from a single file that is stored
2679 locally (e.g. under <filename>files/</filename>) requires
2680 a recipe that has the file listed in the
2681 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2682 variable.
2683 Additionally, you need to manually write the
2684 <filename>do_compile</filename> and
2685 <filename>do_install</filename> tasks.
2686 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2687 variable defines the directory containing the source code,
2688 which is set to
2689 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2690 in this case - the directory BitBake uses for the build.
2691 <literallayout class='monospaced'>
2692 SUMMARY = "Simple helloworld application"
2693 SECTION = "examples"
2694 LICENSE = "MIT"
2695 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2696
2697 SRC_URI = "file://helloworld.c"
2698
2699 S = "${WORKDIR}"
2700
2701 do_compile() {
2702 ${CC} helloworld.c -o helloworld
2703 }
2704
2705 do_install() {
2706 install -d ${D}${bindir}
2707 install -m 0755 helloworld ${D}${bindir}
2708 }
2709 </literallayout>
2710 </para>
2711
2712 <para>
2713 By default, the <filename>helloworld</filename>,
2714 <filename>helloworld-dbg</filename>, and
2715 <filename>helloworld-dev</filename> packages are built.
2716 For information on how to customize the packaging process,
2717 see the
2718 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2719 section.
2720 </para>
2721 </section>
2722
2723 <section id='new-recipe-autotooled-package'>
2724 <title>Autotooled Package</title>
2725 <para>
2726 Applications that use Autotools such as <filename>autoconf</filename> and
2727 <filename>automake</filename> require a recipe that has a source archive listed in
2728 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2729 also inherit the
2730 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2731 class, which contains the definitions of all the steps
2732 needed to build an Autotool-based application.
2733 The result of the build is automatically packaged.
2734 And, if the application uses NLS for localization, packages with local information are
2735 generated (one package per language).
2736 Following is one example: (<filename>hello_2.3.bb</filename>)
2737 <literallayout class='monospaced'>
2738 SUMMARY = "GNU Helloworld application"
2739 SECTION = "examples"
2740 LICENSE = "GPLv2+"
2741 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2742
2743 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2744
2745 inherit autotools gettext
2746 </literallayout>
2747 </para>
2748
2749 <para>
2750 The variable
2751 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2752 is used to track source license changes as described in the
2753 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2754 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2755 </para>
2756 </section>
2757
2758 <section id='new-recipe-makefile-based-package'>
2759 <title>Makefile-Based Package</title>
2760
2761 <para>
2762 Applications that use GNU <filename>make</filename> also require a recipe that has
2763 the source archive listed in
2764 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2765 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2766 starts the <filename>make</filename> command to compile the application.
2767 If you need additional <filename>make</filename> options, you should store them in the
2768 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2769 variable.
2770 BitBake passes these options into the <filename>make</filename> GNU invocation.
2771 Note that a <filename>do_install</filename> task is still required.
2772 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2773 </para>
2774
2775 <para>
2776 Some applications might require extra parameters to be passed to the compiler.
2777 For example, the application might need an additional header path.
2778 You can accomplish this by adding to the
2779 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2780 The following example shows this:
2781 <literallayout class='monospaced'>
2782 CFLAGS_prepend = "-I ${S}/include "
2783 </literallayout>
2784 </para>
2785
2786 <para>
2787 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2788 <literallayout class='monospaced'>
2789 SUMMARY = "Tools for managing memory technology devices."
2790 SECTION = "base"
2791 DEPENDS = "zlib lzo e2fsprogs util-linux"
2792 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2793 LICENSE = "GPLv2+"
2794 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2795 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2796
2797 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2798 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2799
2800 S = "${WORKDIR}/git/"
2801
2802 PR = "r1"
2803
2804 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2805 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2806
2807 do_install () {
2808 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2809 INCLUDEDIR=${includedir}
2810 install -d ${D}${includedir}/mtd/
2811 for f in ${S}/include/mtd/*.h; do
2812 install -m 0644 $f ${D}${includedir}/mtd/
2813 done
2814 }
2815
2816 PARALLEL_MAKE = ""
2817
2818 BBCLASSEXTEND = "native"
2819 </literallayout>
2820 </para>
2821 </section>
2822
2823 <section id='splitting-an-application-into-multiple-packages'>
2824 <title>Splitting an Application into Multiple Packages</title>
2825
2826 <para>
2827 You can use the variables
2828 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2829 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2830 to split an application into multiple packages.
2831 </para>
2832
2833 <para>
2834 Following is an example that uses the <filename>libxpm</filename> recipe.
2835 By default, this recipe generates a single package that contains the library along
2836 with a few binaries.
2837 You can modify the recipe to split the binaries into separate packages:
2838 <literallayout class='monospaced'>
2839 require xorg-lib-common.inc
2840
2841 SUMMARY = "X11 Pixmap library"
2842 LICENSE = "X-BSD"
2843 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2844 DEPENDS += "libxext libsm libxt"
2845 PR = "r3"
2846 PE = "1"
2847
2848 XORG_PN = "libXpm"
2849
2850 PACKAGES =+ "sxpm cxpm"
2851 FILES_cxpm = "${bindir}/cxpm"
2852 FILES_sxpm = "${bindir}/sxpm"
2853 </literallayout>
2854 </para>
2855
2856 <para>
2857 In the previous example, we want to ship the <filename>sxpm</filename>
2858 and <filename>cxpm</filename> binaries in separate packages.
2859 Since <filename>bindir</filename> would be packaged into the main
2860 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2861 package by default, we prepend the <filename>PACKAGES</filename>
2862 variable so additional package names are added to the start of list.
2863 This results in the extra <filename>FILES_*</filename>
2864 variables then containing information that define which files and
2865 directories go into which packages.
2866 Files included by earlier packages are skipped by latter packages.
2867 Thus, the main <filename>PN</filename> package
2868 does not include the above listed files.
2869 </para>
2870 </section>
2871 </section>
2872 </section>
2873
2874 <section id="platdev-newmachine">
2875 <title>Adding a New Machine</title>
2876
2877 <para>
2878 Adding a new machine to the Yocto Project is a straight forward
2879 process.
2880 This section describes how to add machines that are similar
2881 to those that the Yocto Project already supports.
2882 <note>
2883 Although well within the capabilities of the Yocto Project,
2884 adding a totally new architecture might require
2885 changes to <filename>gcc/eglibc</filename> and to the site
2886 information, which is beyond the scope of this manual.
2887 </note>
2888 </para>
2889
2890 <para>
2891 For a complete example that shows how to add a new machine,
2892 see the
2893 "<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>"
2894 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
2895 </para>
2896
2897 <section id="platdev-newmachine-conffile">
2898 <title>Adding the Machine Configuration File</title>
2899
2900 <para>
2901 To add a new machine, you need to add a new machine
2902 configuration file to the layer's
2903 <filename>conf/machine</filename> directory.
2904 This configuration file provides details about the device
2905 you are adding.
2906 </para>
2907
2908 <para>
2909 The OpenEmbedded build system uses the root name of the
2910 machine configuration file to reference the new machine.
2911 For example, given a machine configuration file named
2912 <filename>crownbay.conf</filename>, the build system
2913 recognizes the machine as "crownbay".
2914 </para>
2915
2916 <para>
2917 The most important variables you must set in your machine
2918 configuration file are as follows:
2919 <itemizedlist>
2920 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
2921 (e.g. "arm")</para></listitem>
2922 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
2923 (see below)</para></listitem>
2924 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
2925 (e.g. "apm screen wifi")</para></listitem>
2926 </itemizedlist>
2927 </para>
2928
2929 <para>
2930 You might also need these variables:
2931 <itemizedlist>
2932 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
2933 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
2934 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
2935 (e.g. "zImage")</para></listitem>
2936 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
2937 (e.g. "tar.gz jffs2")</para></listitem>
2938 </itemizedlist>
2939 </para>
2940
2941 <para>
2942 You can find full details on these variables in the reference
2943 section.
2944 You can leverage existing machine <filename>.conf</filename>
2945 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
2946 </para>
2947 </section>
2948
2949 <section id="platdev-newmachine-kernel">
2950 <title>Adding a Kernel for the Machine</title>
2951
2952 <para>
2953 The OpenEmbedded build system needs to be able to build a kernel
2954 for the machine.
2955 You need to either create a new kernel recipe for this machine,
2956 or extend an existing kernel recipe.
2957 You can find several kernel recipe examples in the
2958 Source Directory at
2959 <filename>meta/recipes-kernel/linux</filename>
2960 that you can use as references.
2961 </para>
2962
2963 <para>
2964 If you are creating a new kernel recipe, normal recipe-writing
2965 rules apply for setting up a
2966 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2967 Thus, you need to specify any necessary patches and set
2968 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2969 to point at the source code.
2970 You need to create a <filename>do_configure</filename> task that
2971 configures the unpacked kernel with a
2972 <filename>defconfig</filename> file.
2973 You can do this by using a <filename>make defconfig</filename>
2974 command or, more commonly, by copying in a suitable
2975 <filename>defconfig</filename> file and then running
2976 <filename>make oldconfig</filename>.
2977 By making use of <filename>inherit kernel</filename> and
2978 potentially some of the <filename>linux-*.inc</filename> files,
2979 most other functionality is centralized and the defaults of the
2980 class normally work well.
2981 </para>
2982
2983 <para>
2984 If you are extending an existing kernel recipe, it is usually
2985 a matter of adding a suitable <filename>defconfig</filename>
2986 file.
2987 The file needs to be added into a location similar to
2988 <filename>defconfig</filename> files used for other machines
2989 in a given kernel recipe.
2990 A possible way to do this is by listing the file in the
2991 <filename>SRC_URI</filename> and adding the machine to the
2992 expression in
2993 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
2994 <literallayout class='monospaced'>
2995 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2996 </literallayout>
2997 </para>
2998 </section>
2999
3000 <section id="platdev-newmachine-formfactor">
3001 <title>Adding a Formfactor Configuration File</title>
3002
3003 <para>
3004 A formfactor configuration file provides information about the
3005 target hardware for which the image is being built and information that
3006 the build system cannot obtain from other sources such as the kernel.
3007 Some examples of information contained in a formfactor configuration file include
3008 framebuffer orientation, whether or not the system has a keyboard,
3009 the positioning of the keyboard in relation to the screen, and
3010 the screen resolution.
3011 </para>
3012
3013 <para>
3014 The build system uses reasonable defaults in most cases.
3015 However, if customization is
3016 necessary, you need to create a <filename>machconfig</filename> file
3017 in the <filename>meta/recipes-bsp/formfactor/files</filename>
3018 directory.
3019 This directory contains directories for specific machines such as
3020 <filename>qemuarm</filename> and <filename>qemux86</filename>.
3021 For information about the settings available and the defaults, see the
3022 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
3023 same area.
3024 </para>
3025
3026 <para>
3027 Following is an example for "qemuarm" machine:
3028 <literallayout class='monospaced'>
3029 HAVE_TOUCHSCREEN=1
3030 HAVE_KEYBOARD=1
3031
3032 DISPLAY_CAN_ROTATE=0
3033 DISPLAY_ORIENTATION=0
3034 #DISPLAY_WIDTH_PIXELS=640
3035 #DISPLAY_HEIGHT_PIXELS=480
3036 #DISPLAY_BPP=16
3037 DISPLAY_DPI=150
3038 DISPLAY_SUBPIXEL_ORDER=vrgb
3039 </literallayout>
3040 </para>
3041 </section>
3042 </section>
3043
3044 <section id="platdev-working-with-libraries">
3045 <title>Working With Libraries</title>
3046
3047 <para>
3048 Libraries are an integral part of your system.
3049 This section describes some common practices you might find
3050 helpful when working with libraries to build your system:
3051 <itemizedlist>
3052 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
3053 </para></listitem>
3054 <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>
3055 </para></listitem>
3056 <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>
3057 </para></listitem>
3058 </itemizedlist>
3059 </para>
3060
3061 <section id='including-static-library-files'>
3062 <title>Including Static Library Files</title>
3063
3064 <para>
3065 If you are building a library and the library offers static linking, you can control
3066 which static library files (<filename>*.a</filename> files) get included in the
3067 built library.
3068 </para>
3069
3070 <para>
3071 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
3072 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
3073 variables in the
3074 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
3075 by the <filename>do_install</filename> task are packaged.
3076 By default, the <filename>PACKAGES</filename> variable contains
3077 <filename>${PN}-staticdev</filename>, which includes all static library files.
3078 <note>
3079 Some previously released versions of the Yocto Project
3080 defined the static library files through
3081 <filename>${PN}-dev</filename>.
3082 </note>
3083 Following, is part of the BitBake configuration file.
3084 You can see where the static library files are defined:
3085 <literallayout class='monospaced'>
3086 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
3087 PACKAGES_DYNAMIC = "${PN}-locale-*"
3088 FILES = ""
3089
3090 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
3091 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
3092 ${base_bindir}/* ${base_sbindir}/* \
3093 ${base_libdir}/*${SOLIBS} \
3094 ${datadir}/${BPN} ${libdir}/${BPN}/* \
3095 ${datadir}/pixmaps ${datadir}/applications \
3096 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
3097 ${libdir}/bonobo/servers"
3098
3099 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
3100 ${datadir}/gnome/help"
3101 SECTION_${PN}-doc = "doc"
3102
3103 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
3104 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
3105 ${datadir}/aclocal ${base_libdir}/*.o"
3106 SECTION_${PN}-dev = "devel"
3107 ALLOW_EMPTY_${PN}-dev = "1"
3108 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
3109
3110 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
3111 SECTION_${PN}-staticdev = "devel"
3112 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
3113 </literallayout>
3114 </para>
3115 </section>
3116
3117 <section id="combining-multiple-versions-library-files-into-one-image">
3118 <title>Combining Multiple Versions of Library Files into One Image</title>
3119
3120 <para>
3121 The build system offers the ability to build libraries with different
3122 target optimizations or architecture formats and combine these together
3123 into one system image.
3124 You can link different binaries in the image
3125 against the different libraries as needed for specific use cases.
3126 This feature is called "Multilib."
3127 </para>
3128
3129 <para>
3130 An example would be where you have most of a system compiled in 32-bit
3131 mode using 32-bit libraries, but you have something large, like a database
3132 engine, that needs to be a 64-bit application and uses 64-bit libraries.
3133 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
3134 </para>
3135
3136 <para>
3137 While the Multilib feature is most commonly used for 32 and 64-bit differences,
3138 the approach the build system uses facilitates different target optimizations.
3139 You could compile some binaries to use one set of libraries and other binaries
3140 to use other different sets of libraries.
3141 The libraries could differ in architecture, compiler options, or other
3142 optimizations.
3143 </para>
3144
3145 <para>
3146 This section overviews the Multilib process only.
3147 For more details on how to implement Multilib, see the
3148 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
3149 page.
3150 </para>
3151
3152 <para>
3153 Aside from this wiki page, several examples exist in the
3154 <filename>meta-skeleton</filename> layer found in the
3155 <link linkend='source-directory'>Source Directory</link>:
3156 <itemizedlist>
3157 <listitem><para><filename>conf/multilib-example.conf</filename>
3158 configuration file</para></listitem>
3159 <listitem><para><filename>conf/multilib-example2.conf</filename>
3160 configuration file</para></listitem>
3161 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
3162 recipe</para></listitem>
3163 </itemizedlist>
3164 </para>
3165
3166 <section id='preparing-to-use-multilib'>
3167 <title>Preparing to Use Multilib</title>
3168
3169 <para>
3170 User-specific requirements drive the Multilib feature.
3171 Consequently, there is no one "out-of-the-box" configuration that likely
3172 exists to meet your needs.
3173 </para>
3174
3175 <para>
3176 In order to enable Multilib, you first need to ensure your recipe is
3177 extended to support multiple libraries.
3178 Many standard recipes are already extended and support multiple libraries.
3179 You can check in the <filename>meta/conf/multilib.conf</filename>
3180 configuration file in the
3181 <link linkend='source-directory'>Source Directory</link> to see how this is
3182 done using the
3183 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
3184 variable.
3185 Eventually, all recipes will be covered and this list will
3186 not be needed.
3187 </para>
3188
3189 <para>
3190 For the most part, the Multilib class extension works automatically to
3191 extend the package name from <filename>${PN}</filename> to
3192 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
3193 is the particular multilib (e.g. "lib32-" or "lib64-").
3194 Standard variables such as
3195 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
3196 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
3197 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
3198 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
3199 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
3200 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
3201 If you are extending any manual code in the recipe, you can use the
3202 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
3203 correctly.
3204 This automatic extension code resides in <filename>multilib.bbclass</filename>.
3205 </para>
3206 </section>
3207
3208 <section id='using-multilib'>
3209 <title>Using Multilib</title>
3210
3211 <para>
3212 After you have set up the recipes, you need to define the actual
3213 combination of multiple libraries you want to build.
3214 You accomplish this through your <filename>local.conf</filename>
3215 configuration file in the
3216 <link linkend='build-directory'>Build Directory</link>.
3217 An example configuration would be as follows:
3218 <literallayout class='monospaced'>
3219 MACHINE = "qemux86-64"
3220 require conf/multilib.conf
3221 MULTILIBS = "multilib:lib32"
3222 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
3223 IMAGE_INSTALL = "lib32-connman"
3224 </literallayout>
3225 This example enables an
3226 additional library named <filename>lib32</filename> alongside the
3227 normal target packages.
3228 When combining these "lib32" alternatives, the example uses "x86" for tuning.
3229 For information on this particular tuning, see
3230 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
3231 </para>
3232
3233 <para>
3234 The example then includes <filename>lib32-connman</filename>
3235 in all the images, which illustrates one method of including a
3236 multiple library dependency.
3237 You can use a normal image build to include this dependency,
3238 for example:
3239 <literallayout class='monospaced'>
3240 $ bitbake core-image-sato
3241 </literallayout>
3242 You can also build Multilib packages specifically with a command like this:
3243 <literallayout class='monospaced'>
3244 $ bitbake lib32-connman
3245 </literallayout>
3246 </para>
3247 </section>
3248
3249 <section id='additional-implementation-details'>
3250 <title>Additional Implementation Details</title>
3251
3252 <para>
3253 Different packaging systems have different levels of native Multilib
3254 support.
3255 For the RPM Package Management System, the following implementation details
3256 exist:
3257 <itemizedlist>
3258 <listitem><para>A unique architecture is defined for the Multilib packages,
3259 along with creating a unique deploy folder under
3260 <filename>tmp/deploy/rpm</filename> in the
3261 <link linkend='build-directory'>Build Directory</link>.
3262 For example, consider <filename>lib32</filename> in a
3263 <filename>qemux86-64</filename> image.
3264 The possible architectures in the system are "all", "qemux86_64",
3265 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
3266 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
3267 <filename>${PN}</filename> during RPM packaging.
3268 The naming for a normal RPM package and a Multilib RPM package in a
3269 <filename>qemux86-64</filename> system resolves to something similar to
3270 <filename>bash-4.1-r2.x86_64.rpm</filename> and
3271 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
3272 </para></listitem>
3273 <listitem><para>When installing a Multilib image, the RPM backend first
3274 installs the base image and then installs the Multilib libraries.
3275 </para></listitem>
3276 <listitem><para>The build system relies on RPM to resolve the identical files in the
3277 two (or more) Multilib packages.</para></listitem>
3278 </itemizedlist>
3279 </para>
3280
3281 <para>
3282 For the IPK Package Management System, the following implementation details exist:
3283 <itemizedlist>
3284 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
3285 <filename>${PN}</filename> during IPK packaging.
3286 The naming for a normal RPM package and a Multilib IPK package in a
3287 <filename>qemux86-64</filename> system resolves to something like
3288 <filename>bash_4.1-r2.x86_64.ipk</filename> and
3289 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
3290 </para></listitem>
3291 <listitem><para>The IPK deploy folder is not modified with
3292 <filename>${MLPREFIX}</filename> because packages with and without
3293 the Multilib feature can exist in the same folder due to the
3294 <filename>${PN}</filename> differences.</para></listitem>
3295 <listitem><para>IPK defines a sanity check for Multilib installation
3296 using certain rules for file comparison, overridden, etc.
3297 </para></listitem>
3298 </itemizedlist>
3299 </para>
3300 </section>
3301 </section>
3302
3303 <section id='installing-multiple-versions-of-the-same-library'>
3304 <title>Installing Multiple Versions of the Same Library</title>
3305
3306 <para>
3307 Situations can exist where you need to install and use
3308 multiple versions of the same library on the same system
3309 at the same time.
3310 These situations almost always exist when a library API
3311 changes and you have multiple pieces of software that
3312 depend on the separate versions of the library.
3313 To accommodate these situations, you can install multiple
3314 versions of the same library in parallel on the same system.
3315 </para>
3316
3317 <para>
3318 The process is straight forward as long as the libraries use
3319 proper versioning.
3320 With properly versioned libraries, all you need to do to
3321 individually specify the libraries is create separate,
3322 appropriately named recipes where the
3323 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
3324 name includes a portion that differentiates each library version
3325 (e.g.the major part of the version number).
3326 Thus, instead of having a single recipe that loads one version
3327 of a library (e.g. <filename>clutter</filename>), you provide
3328 multiple recipes that result in different versions
3329 of the libraries you want.
3330 As an example, the following two recipes would allow the
3331 two separate versions of the <filename>clutter</filename>
3332 library to co-exist on the same system:
3333 <literallayout class='monospaced'>
3334 clutter-1.6_1.6.20.bb
3335 clutter-1.8_1.8.4.bb
3336 </literallayout>
3337 Additionally, if you have other recipes that depend on a given
3338 library, you need to use the
3339 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
3340 variable to create the dependency.
3341 Continuing with the same example, if you want to have a recipe
3342 depend on the 1.8 version of the <filename>clutter</filename>
3343 library, use the following in your recipe:
3344 <literallayout class='monospaced'>
3345 DEPENDS = "clutter-1.8"
3346 </literallayout>
3347 </para>
3348 </section>
3349 </section>
3350
3351 <section id='configuring-the-kernel'>
3352 <title>Configuring the Kernel</title>
3353
3354 <para>
3355 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
3356 file has all the right information in it for the image you are building.
3357 You can use the <filename>menuconfig</filename> tool and configuration fragments to
3358 make sure your <filename>.config</filename> file is just how you need it.
3359 This section describes how to use <filename>menuconfig</filename>, create and use
3360 configuration fragments, and how to interactively tweak your <filename>.config</filename>
3361 file to create the leanest kernel configuration file possible.
3362 </para>
3363
3364 <para>
3365 For more information on kernel configuration, see the
3366 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
3367 section in the Yocto Project Linux Kernel Development Manual.
3368 </para>
3369
3370 <section id='using-menuconfig'>
3371 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
3372
3373 <para>
3374 The easiest way to define kernel configurations is to set them through the
3375 <filename>menuconfig</filename> tool.
3376 This tool provides an interactive method with which
3377 to set kernel configurations.
3378 For general information on <filename>menuconfig</filename>, see
3379 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
3380 </para>
3381
3382 <para>
3383 To use the <filename>menuconfig</filename> tool in the Yocto Project development
3384 environment, you must launch it using BitBake.
3385 Thus, the environment must be set up using the
3386 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3387 or
3388 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
3389 script found in the
3390 <link linkend='build-directory'>Build Directory</link>.
3391 The following commands run <filename>menuconfig</filename> assuming the
3392 <link linkend='source-directory'>Source Directory</link>
3393 top-level folder is <filename>~/poky</filename>:
3394 <literallayout class='monospaced'>
3395 $ cd poky
3396 $ source oe-init-build-env
3397 $ bitbake linux-yocto -c menuconfig
3398 </literallayout>
3399 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
3400 interactively examine and configure all the kernel configuration parameters.
3401 After making your changes, simply exit the tool and save your changes to
3402 create an updated version of the <filename>.config</filename> configuration file.
3403 </para>
3404
3405 <para>
3406 Consider an example that configures the <filename>linux-yocto-3.14</filename>
3407 kernel.
3408 The OpenEmbedded build system recognizes this kernel as
3409 <filename>linux-yocto</filename>.
3410 Thus, the following commands from the shell in which you previously sourced the
3411 environment initialization script cleans the shared state cache and the
3412 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
3413 directory and then runs <filename>menuconfig</filename>:
3414 <literallayout class='monospaced'>
3415 $ bitbake linux-yocto -c menuconfig
3416 </literallayout>
3417 </para>
3418
3419 <para>
3420 Once <filename>menuconfig</filename> launches, use the interface
3421 to navigate through the selections to find the configuration settings in
3422 which you are interested.
3423 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
3424 You can find it at <filename>Processor Type and Features</filename> under
3425 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
3426 After highlighting the selection, use the arrow keys to select or deselect
3427 the setting.
3428 When you are finished with all your selections, exit out and save them.
3429 </para>
3430
3431 <para>
3432 Saving the selections updates the <filename>.config</filename> configuration file.
3433 This is the file that the OpenEmbedded build system uses to configure the
3434 kernel during the build.
3435 You can find and examine this file in the Build Directory in
3436 <filename>tmp/work/</filename>.
3437 The actual <filename>.config</filename> is located in the area where the
3438 specific kernel is built.
3439 For example, if you were building a Linux Yocto kernel based on the
3440 Linux 3.14 kernel and you were building a QEMU image targeted for
3441 <filename>x86</filename> architecture, the
3442 <filename>.config</filename> file would be located here:
3443 <literallayout class='monospaced'>
3444 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
3445 ...656ed30-r1/linux-qemux86-standard-build
3446 </literallayout>
3447 <note>
3448 The previous example directory is artificially split and many of the characters
3449 in the actual filename are omitted in order to make it more readable.
3450 Also, depending on the kernel you are using, the exact pathname
3451 for <filename>linux-yocto-3.14...</filename> might differ.
3452 </note>
3453 </para>
3454
3455 <para>
3456 Within the <filename>.config</filename> file, you can see the kernel settings.
3457 For example, the following entry shows that symmetric multi-processor support
3458 is not set:
3459 <literallayout class='monospaced'>
3460 # CONFIG_SMP is not set
3461 </literallayout>
3462 </para>
3463
3464 <para>
3465 A good method to isolate changed configurations is to use a combination of the
3466 <filename>menuconfig</filename> tool and simple shell commands.
3467 Before changing configurations with <filename>menuconfig</filename>, copy the
3468 existing <filename>.config</filename> and rename it to something else,
3469 use <filename>menuconfig</filename> to make
3470 as many changes as you want and save them, then compare the renamed configuration
3471 file against the newly created file.
3472 You can use the resulting differences as your base to create configuration fragments
3473 to permanently save in your kernel layer.
3474 <note>
3475 Be sure to make a copy of the <filename>.config</filename> and don't just
3476 rename it.
3477 The build system needs an existing <filename>.config</filename>
3478 from which to work.
3479 </note>
3480 </para>
3481 </section>
3482
3483 <section id='creating-config-fragments'>
3484 <title>Creating Configuration Fragments</title>
3485
3486 <para>
3487 Configuration fragments are simply kernel options that appear in a file
3488 placed where the OpenEmbedded build system can find and apply them.
3489 Syntactically, the configuration statement is identical to what would appear
3490 in the <filename>.config</filename> file, which is in the
3491 <link linkend='build-directory'>Build Directory</link> in
3492 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
3493 </para>
3494
3495 <para>
3496 It is simple to create a configuration fragment.
3497 For example, issuing the following from the shell creates a configuration fragment
3498 file named <filename>my_smp.cfg</filename> that enables multi-processor support
3499 within the kernel:
3500 <literallayout class='monospaced'>
3501 $ echo "CONFIG_SMP=y" >> my_smp.cfg
3502 </literallayout>
3503 <note>
3504 All configuration files must use the <filename>.cfg</filename> extension in order
3505 for the OpenEmbedded build system to recognize them as a configuration fragment.
3506 </note>
3507 </para>
3508
3509 <para>
3510 Where do you put your configuration files?
3511 You can place these configuration files in the same area pointed to by
3512 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3513 The OpenEmbedded build system will pick up the configuration and add it to the
3514 kernel's configuration.
3515 For example, suppose you had a set of configuration options in a file called
3516 <filename>myconfig.cfg</filename>.
3517 If you put that file inside a directory named <filename>linux-yocto</filename>
3518 that resides in the same directory as the kernel's append file and then add
3519 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
3520 those configuration options will be picked up and applied when the kernel is built.
3521 <literallayout class='monospaced'>
3522 SRC_URI += "file://myconfig.cfg"
3523 </literallayout>
3524 </para>
3525
3526 <para>
3527 As mentioned earlier, you can group related configurations into multiple files and
3528 name them all in the <filename>SRC_URI</filename> statement as well.
3529 For example, you could group separate configurations specifically for Ethernet and graphics
3530 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
3531 following in your append file:
3532 <literallayout class='monospaced'>
3533 SRC_URI += "file://myconfig.cfg \
3534 file://eth.cfg \
3535 file://gfx.cfg"
3536 </literallayout>
3537 </para>
3538 </section>
3539
3540 <section id='fine-tuning-the-kernel-configuration-file'>
3541 <title>Fine-Tuning the Kernel Configuration File</title>
3542
3543 <para>
3544 You can make sure the <filename>.config</filename> file is as lean or efficient as
3545 possible by reading the output of the kernel configuration fragment audit,
3546 noting any issues, making changes to correct the issues, and then repeating.
3547 </para>
3548
3549 <para>
3550 As part of the kernel build process, the
3551 <filename>do_kernel_configcheck</filename> task runs.
3552 This task validates the kernel configuration by checking the final
3553 <filename>.config</filename> file against the input files.
3554 During the check, the task produces warning messages for the following
3555 issues:
3556 <itemizedlist>
3557 <listitem><para>Requested options that did not make the final
3558 <filename>.config</filename> file.</para></listitem>
3559 <listitem><para>Configuration items that appear twice in the same
3560 configuration fragment.</para></listitem>
3561 <listitem><para>Configuration items tagged as "required" that were overridden.
3562 </para></listitem>
3563 <listitem><para>A board overrides a non-board specific option.</para></listitem>
3564 <listitem><para>Listed options not valid for the kernel being processed.
3565 In other words, the option does not appear anywhere.</para></listitem>
3566 </itemizedlist>
3567 <note>
3568 The <filename>do_kernel_configcheck</filename> task can
3569 also optionally report if an option is overridden during
3570 processing.
3571 </note>
3572 </para>
3573
3574 <para>
3575 For each output warning, a message points to the file
3576 that contains a list of the options and a pointer to the config
3577 fragment that defines them.
3578 Collectively, the files are the key to streamlining the configuration.
3579 </para>
3580
3581 <para>
3582 To streamline the configuration, do the following:
3583 <orderedlist>
3584 <listitem><para>Start with a full configuration that you
3585 know works - it builds and boots successfully.
3586 This configuration file will be your baseline.
3587 </para></listitem>
3588 <listitem><para>Separately run the
3589 <filename>do_configme</filename> and
3590 <filename>do_kernel_configcheck</filename> tasks.
3591 </para></listitem>
3592 <listitem><para>Take the resulting list of files from the
3593 <filename>do_kernel_configcheck</filename> task
3594 warnings and do the following:
3595 <itemizedlist>
3596 <listitem><para>
3597 Drop values that are redefined in the fragment
3598 but do not change the final
3599 <filename>.config</filename> file.
3600 </para></listitem>
3601 <listitem><para>
3602 Analyze and potentially drop values from the
3603 <filename>.config</filename> file that override
3604 required configurations.
3605 </para></listitem>
3606 <listitem><para>
3607 Analyze and potentially remove non-board
3608 specific options.
3609 </para></listitem>
3610 <listitem><para>
3611 Remove repeated and invalid options.
3612 </para></listitem>
3613 </itemizedlist></para></listitem>
3614 <listitem><para>
3615 After you have worked through the output of the kernel
3616 configuration audit, you can re-run the
3617 <filename>do_configme</filename> and
3618 <filename>do_kernel_configcheck</filename> tasks to
3619 see the results of your changes.
3620 If you have more issues, you can deal with them as
3621 described in the previous step.
3622 </para></listitem>
3623 </orderedlist>
3624 </para>
3625
3626 <para>
3627 Iteratively working through steps two through four eventually yields
3628 a minimal, streamlined configuration file.
3629 Once you have the best <filename>.config</filename>, you can build the Linux
3630 Yocto kernel.
3631 </para>
3632 </section>
3633 </section>
3634
3635 <section id="patching-the-kernel">
3636 <title>Patching the Kernel</title>
3637
3638 <para>
3639 Patching the kernel involves changing or adding configurations to an existing kernel,
3640 changing or adding recipes to the kernel that are needed to support specific hardware features,
3641 or even altering the source code itself.
3642 <note>
3643 You can use the <filename>yocto-kernel</filename> script
3644 found in the <link linkend='source-directory'>Source Directory</link>
3645 under <filename>scripts</filename> to manage kernel patches and configuration.
3646 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>"
3647 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
3648 more information.</note>
3649 </para>
3650
3651 <para>
3652 This example creates a simple patch by adding some QEMU emulator console
3653 output at boot time through <filename>printk</filename> statements in the kernel's
3654 <filename>calibrate.c</filename> source code file.
3655 Applying the patch and booting the modified image causes the added
3656 messages to appear on the emulator's console.
3657 </para>
3658
3659 <para>
3660 The example assumes a clean build exists for the <filename>qemux86</filename>
3661 machine in a
3662 <link linkend='source-directory'>Source Directory</link>
3663 named <filename>poky</filename>.
3664 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
3665 <filename>build</filename> and is located in <filename>poky</filename> and
3666 the kernel is based on the Linux 3.4 kernel.
3667 For general information on how to configure the most efficient build, see the
3668 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
3669 in the Yocto Project Quick Start.
3670 </para>
3671
3672 <para>
3673 Also, for more information on patching the kernel, see the
3674 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
3675 section in the Yocto Project Linux Kernel Development Manual.
3676 </para>
3677
3678 <section id='create-a-layer-for-your-changes'>
3679 <title>Create a Layer for your Changes</title>
3680
3681 <para>
3682 The first step is to create a layer so you can isolate your
3683 changes.
3684 Rather than use the <filename>yocto-layer</filename> script
3685 to create the layer, this example steps through the process
3686 by hand.
3687 If you want information on the script that creates a general
3688 layer, see the
3689 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3690 section.
3691 </para>
3692
3693 <para>
3694 These two commands create a directory you can use for your
3695 layer:
3696 <literallayout class='monospaced'>
3697 $ cd ~/poky
3698 $ mkdir meta-mylayer
3699 </literallayout>
3700 Creating a directory that follows the Yocto Project layer naming
3701 conventions sets up the layer for your changes.
3702 The layer is where you place your configuration files, append
3703 files, and patch files.
3704 To learn more about creating a layer and filling it with the
3705 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
3706 and Creating Layers</link>" section.
3707 </para>
3708 </section>
3709
3710 <section id='finding-the-kernel-source-code'>
3711 <title>Finding the Kernel Source Code</title>
3712
3713 <para>
3714 Each time you build a kernel image, the kernel source code is fetched
3715 and unpacked into the following directory:
3716 <literallayout class='monospaced'>
3717 ${S}/linux
3718 </literallayout>
3719 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
3720 section and the
3721 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
3722 for more information about where source is kept during a build.
3723 </para>
3724
3725 <para>
3726 For this example, we are going to patch the
3727 <filename>init/calibrate.c</filename> file
3728 by adding some simple console <filename>printk</filename> statements that we can
3729 see when we boot the image using QEMU.
3730 </para>
3731 </section>
3732
3733 <section id='creating-the-patch'>
3734 <title>Creating the Patch</title>
3735
3736 <para>
3737 Two methods exist by which you can create the patch:
3738 <link linkend='using-a-git-workflow'>Git workflow</link> and
3739 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
3740 For kernel patches, the Git workflow is more appropriate.
3741 This section assumes the Git workflow and shows the steps specific to
3742 this example.
3743 <orderedlist>
3744 <listitem><para><emphasis>Change the working directory</emphasis>:
3745 Change to where the kernel source code is before making
3746 your edits to the <filename>calibrate.c</filename> file:
3747 <literallayout class='monospaced'>
3748 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
3749 </literallayout>
3750 Because you are working in an established Git repository,
3751 you must be in this directory in order to commit your changes
3752 and create the patch file.
3753 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
3754 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
3755 represent the version and revision for the
3756 <filename>linux-yocto</filename> recipe.
3757 The <filename>PV</filename> variable includes the Git meta and machine
3758 hashes, which make the directory name longer than you might
3759 expect.
3760 </note></para></listitem>
3761 <listitem><para><emphasis>Edit the source file</emphasis>:
3762 Edit the <filename>init/calibrate.c</filename> file to have the
3763 following changes:
3764 <literallayout class='monospaced'>
3765 void calibrate_delay(void)
3766 {
3767 unsigned long lpj;
3768 static bool printed;
3769 int this_cpu = smp_processor_id();
3770
3771 printk("*************************************\n");
3772 printk("* *\n");
3773 printk("* HELLO YOCTO KERNEL *\n");
3774 printk("* *\n");
3775 printk("*************************************\n");
3776
3777 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
3778 .
3779 .
3780 .
3781 </literallayout></para></listitem>
3782 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
3783 These Git commands display the modified file, stage it, and then
3784 commit the file:
3785 <literallayout class='monospaced'>
3786 $ git status
3787 $ git add init/calibrate.c
3788 $ git commit -m "calibrate: Add printk example"
3789 </literallayout></para></listitem>
3790 <listitem><para><emphasis>Generate the patch file</emphasis>:
3791 This Git command creates the a patch file named
3792 <filename>0001-calibrate-Add-printk-example.patch</filename>
3793 in the current directory.
3794 <literallayout class='monospaced'>
3795 $ git format-patch -1
3796 </literallayout>
3797 </para></listitem>
3798 </orderedlist>
3799 </para>
3800 </section>
3801
3802 <section id='set-up-your-layer-for-the-build'>
3803 <title>Set Up Your Layer for the Build</title>
3804
3805 <para>These steps get your layer set up for the build:
3806 <orderedlist>
3807 <listitem><para><emphasis>Create additional structure</emphasis>:
3808 Create the additional layer structure:
3809 <literallayout class='monospaced'>
3810 $ cd ~/poky/meta-mylayer
3811 $ mkdir conf
3812 $ mkdir recipes-kernel
3813 $ mkdir recipes-kernel/linux
3814 $ mkdir recipes-kernel/linux/linux-yocto
3815 </literallayout>
3816 The <filename>conf</filename> directory holds your configuration files, while the
3817 <filename>recipes-kernel</filename> directory holds your append file and
3818 your patch file.</para></listitem>
3819 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
3820 Move to the <filename>meta-mylayer/conf</filename> directory and create
3821 the <filename>layer.conf</filename> file as follows:
3822 <literallayout class='monospaced'>
3823 # We have a conf and classes directory, add to BBPATH
3824 BBPATH .= ":${LAYERDIR}"
3825
3826 # We have recipes-* directories, add to BBFILES
3827 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
3828 ${LAYERDIR}/recipes-*/*/*.bbappend"
3829
3830 BBFILE_COLLECTIONS += "mylayer"
3831 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
3832 BBFILE_PRIORITY_mylayer = "5"
3833 </literallayout>
3834 Notice <filename>mylayer</filename> as part of the last three
3835 statements.</para></listitem>
3836 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
3837 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
3838 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
3839 <literallayout class='monospaced'>
3840 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3841
3842 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
3843 </literallayout>
3844 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
3845 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
3846 statements enable the OpenEmbedded build system to find the patch file.
3847 For more information on using append files, see the
3848 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3849 section.
3850 </para></listitem>
3851 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
3852 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
3853 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
3854 directory.</para></listitem>
3855 </orderedlist>
3856 </para>
3857 </section>
3858
3859 <section id='set-up-for-the-build'>
3860 <title>Set Up for the Build</title>
3861
3862 <para>
3863 Do the following to make sure the build parameters are set up for the example.
3864 Once you set up these build parameters, they do not have to change unless you
3865 change the target architecture of the machine you are building:
3866 <itemizedlist>
3867 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
3868 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3869 definition within the <filename>local.conf</filename> file in the
3870 <link linkend='build-directory'>Build Directory</link>
3871 specifies the target architecture used when building the Linux kernel.
3872 By default, <filename>MACHINE</filename> is set to
3873 <filename>qemux86</filename>, which specifies a 32-bit
3874 <trademark class='registered'>Intel</trademark> Architecture
3875 target machine suitable for the QEMU emulator.</para></listitem>
3876 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
3877 layer:</emphasis> The
3878 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
3879 variable in the
3880 <filename>bblayers.conf</filename> file found in the
3881 <filename>poky/build/conf</filename> directory needs to have the path to your local
3882 <filename>meta-mylayer</filename> layer.
3883 By default, the <filename>BBLAYERS</filename> variable contains paths to
3884 <filename>meta</filename>, <filename>meta-yocto</filename>, and
3885 <filename>meta-yocto-bsp</filename> in the
3886 <filename>poky</filename> Git repository.
3887 Add the path to your <filename>meta-mylayer</filename> location:
3888 <literallayout class='monospaced'>
3889 BBLAYERS ?= " \
3890 $HOME/poky/meta \
3891 $HOME/poky/meta-yocto \
3892 $HOME/poky/meta-yocto-bsp \
3893 $HOME/poky/meta-mylayer \
3894 "
3895
3896 BBLAYERS_NON_REMOVABLE ?= " \
3897 $HOME/poky/meta \
3898 $HOME/poky/meta-yocto \
3899 "
3900 </literallayout></para></listitem>
3901 </itemizedlist>
3902 </para>
3903 </section>
3904
3905 <section id='build-the-modified-qemu-kernel-image'>
3906 <title>Build the Modified QEMU Kernel Image</title>
3907
3908 <para>
3909 The following steps build your modified kernel image:
3910 <orderedlist>
3911 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
3912 Your environment should be set up since you previously sourced
3913 the
3914 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3915 script.
3916 If it is not, source the script again from <filename>poky</filename>.
3917 <literallayout class='monospaced'>
3918 $ cd ~/poky
3919 $ source &OE_INIT_FILE;
3920 </literallayout>
3921 </para></listitem>
3922 <listitem><para><emphasis>Clean up</emphasis>:
3923 Be sure to clean the shared state out by using BitBake
3924 to run from within the Build Directory the
3925 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
3926 task as follows:
3927 <literallayout class='monospaced'>
3928 $ bitbake -c cleansstate linux-yocto
3929 </literallayout></para>
3930 <para>
3931 <note>
3932 Never remove any files by hand from the
3933 <filename>tmp/deploy</filename>
3934 directory inside the
3935 <link linkend='build-directory'>Build Directory</link>.
3936 Always use the various BitBake clean tasks to
3937 clear out previous build artifacts.
3938 For information on the clean tasks, see the
3939 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
3940 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
3941 and
3942 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
3943 sections all in the Yocto Project Reference
3944 Manual.
3945 </note>
3946 </para></listitem>
3947 <listitem><para><emphasis>Build the image</emphasis>:
3948 Next, build the kernel image using this command:
3949 <literallayout class='monospaced'>
3950 $ bitbake -k linux-yocto
3951 </literallayout></para></listitem>
3952 </orderedlist>
3953 </para>
3954 </section>
3955
3956 <section id='boot-the-image-and-verify-your-changes'>
3957 <title>Boot the Image and Verify Your Changes</title>
3958
3959 <para>
3960 These steps boot the image and allow you to see the changes
3961 <orderedlist>
3962 <listitem><para><emphasis>Boot the image</emphasis>:
3963 Boot the modified image in the QEMU emulator
3964 using this command:
3965 <literallayout class='monospaced'>
3966 $ runqemu qemux86
3967 </literallayout></para></listitem>
3968 <listitem><para><emphasis>Verify the changes</emphasis>:
3969 Log into the machine using <filename>root</filename> with no password and then
3970 use the following shell command to scroll through the console's boot output.
3971 <literallayout class='monospaced'>
3972 # dmesg | less
3973 </literallayout>
3974 You should see the results of your <filename>printk</filename> statements
3975 as part of the output.</para></listitem>
3976 </orderedlist>
3977 </para>
3978 </section>
3979 </section>
3980
3981 <section id='making-images-more-secure'>
3982 <title>Making Images More Secure</title>
3983
3984 <para>
3985 Security is of increasing concern for embedded devices.
3986 Consider the issues and problems discussed in just this
3987 sampling of work found across the Internet:
3988 <itemizedlist>
3989 <listitem><para><emphasis>
3990 "<ulink url='https://www.schneier.com/blog/archives/2014/01/security_risks_9.html'>Security Risks of Embedded Systems</ulink>"</emphasis>
3991 by Bruce Schneier
3992 </para></listitem>
3993 <listitem><para><emphasis>
3994 "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
3995 by Carna Botnet</para></listitem>
3996 <listitem><para><emphasis>
3997 "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
3998 by Jake Edge
3999 </para></listitem>
4000 <listitem><para><emphasis>
4001 "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security
4002Gateways via their Web Interfaces</ulink>"</emphasis>
4003 by Ben Williams
4004 </para></listitem>
4005 </itemizedlist>
4006 </para>
4007
4008 <para>
4009 When securing your image is of concern, there are steps, tools,
4010 and variables that you can consider to help you reach the
4011 security goals you need for your particular device.
4012 Not all situations are identical when it comes to making an
4013 image secure.
4014 Consequently, this section provides some guidance and suggestions
4015 for consideration when you want to make your image more secure.
4016 <note>
4017 Because the security requirements and risks are
4018 different for every type of device, this section cannot
4019 provide a complete reference on securing your custom OS.
4020 It is strongly recommended that you also consult other sources
4021 of information on embedded Linux system hardening and on
4022 security.
4023 </note>
4024 </para>
4025
4026 <section id='general-considerations'>
4027 <title>General Considerations</title>
4028
4029 <para>
4030 General considerations exist that help you create more
4031 secure images.
4032 You should consider the following suggestions to help
4033 make your device more secure:
4034 <itemizedlist>
4035 <listitem><para>
4036 Scan additional code you are adding to the system
4037 (e.g. application code) by using static analysis
4038 tools.
4039 Look for buffer overflows and other potential
4040 security problems.
4041 </para></listitem>
4042 <listitem><para>
4043 Pay particular attention to to the security for
4044 any web-based administration interface.
4045 </para>
4046 <para>Web interfaces typically need to perform
4047 administrative functions and tend to need to run with
4048 elevated privileges.
4049 Thus, the consequences resulting from the interface's
4050 security becoming compromised can be serious.
4051 Look for common web vulnerabilities such as
4052 cross-site-scripting (XSS), unvalidated inputs,
4053 and so forth.</para>
4054 <para>As with system passwords, the default credentials
4055 for accessing a web-based interface should not be the
4056 same across all devices.
4057 This is particularly true if the interface is enabled
4058 by default as it can be assumed that many end-users
4059 will not change the credentials.
4060 </para></listitem>
4061 <listitem><para>
4062 Ensure you can update the software on the device to
4063 mitigate vulnerabilities discovered in the future.
4064 This consideration especially applies when your
4065 device is network-enabled.
4066 </para></listitem>
4067 <listitem><para>
4068 Ensure you remove or disable debugging functionality
4069 before producing the final image.
4070 For information on how to do this, see the
4071 "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>"
4072 section.
4073 </para></listitem>
4074 <listitem><para>
4075 Ensure you have no network services listening that
4076 are not needed.
4077 </para></listitem>
4078 <listitem><para>
4079 Remove any software from the image that is not needed.
4080 </para></listitem>
4081 <listitem><para>
4082 Enable hardware support for secure boot functionality
4083 when your device supports this functionality.
4084 </para></listitem>
4085 </itemizedlist>
4086 </para>
4087 </section>
4088
4089 <section id='security-flags'>
4090 <title>Security Flags</title>
4091
4092 <para>
4093 The Yocto Project has security flags that you can enable that
4094 help make your build output more secure.
4095 The security flags are in the
4096 <filename>meta/conf/distro/include/security_flags.inc</filename>
4097 file in your
4098 <link linkend='source-directory'>Source Directory</link>
4099 (e.g. <filename>poky</filename>).
4100 <note>
4101 Depending on the recipe, certain security flags are enabled
4102 and disabled by default.
4103 </note>
4104 </para>
4105
4106 <para>
4107<!--
4108 The GCC/LD flags in <filename>security_flags.inc</filename>
4109 enable more secure code generation.
4110 By including the <filename>security_flags.inc</filename>
4111 file, you enable flags to the compiler and linker that cause
4112 them to generate more secure code.
4113 <note>
4114 The GCC/LD flags are enabled by default in the
4115 <filename>poky-lsb</filename> distribution.
4116 </note>
4117-->
4118 Use the following line in your
4119 <filename>local.conf</filename> file or in your custom
4120 distribution configuration file to enable the security
4121 compiler and linker flags to your build:
4122 <literallayout class='monospaced'>
4123 require conf/distro/include/security_flags.inc
4124 </literallayout>
4125 </para>
4126 </section>
4127
4128 <section id='considerations-specific-to-the-openembedded-build-system'>
4129 <title>Considerations Specific to the OpenEmbedded Build System</title>
4130
4131 <para>
4132 You can take some steps that are specific to the
4133 OpenEmbedded build system to make your images more secure:
4134 <itemizedlist>
4135 <listitem><para>
4136 Ensure "debug-tweaks" is not listed with
4137 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>.
4138 The default is to enable "debug-tweaks" by adding it
4139 to
4140 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
4141 in <filename>local.conf</filename>.
4142 However, you should comment out the variable or be
4143 sure that it does not have "debug-tweaks" before
4144 producing your final image.
4145 Among other things, leaving this in place sets the
4146 root password as blank, which makes logging in for
4147 debugging or inspection easy during
4148 development but also means anyone can easily log in
4149 during production.
4150 </para></listitem>
4151 <listitem><para>
4152 It is possible to set a root password for the image
4153 and also to set passwords for any extra users you might
4154 add (e.g. administrative or service type users).
4155 When you set up passwords for multiple images or
4156 users, you should not duplicate passwords.
4157 </para>
4158 <para>
4159 To set up passwords, use the
4160 <filename>extrausers</filename> class, which is the
4161 preferred method.
4162 For an example on how to set up both root and user
4163 passwords, see the
4164 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>"
4165 section.
4166 <note>
4167 When adding extra user accounts or setting a
4168 root password, be cautious about setting the
4169 same password on every device.
4170 If you do this, and the password you have set
4171 is exposed, then every device is now potentially
4172 compromised.
4173 If you need this access but want to ensure
4174 security, consider setting a different,
4175 random password for each device.
4176 Typically, you do this as a separate step after
4177 you deploy the image onto the device.
4178 </note>
4179 </para></listitem>
4180 <listitem><para>
4181 Consider enabling a Mandatory Access Control (MAC)
4182 framework (such as SMACK or SELinux) and tuning it
4183 appropriately for your device's usage.
4184 </para></listitem>
4185 </itemizedlist>
4186 </para>
4187
4188 <para>
4189 </para>
4190 </section>
4191
4192 <section id='tools-for-hardening-your-image'>
4193 <title>Tools for Hardening Your Image</title>
4194
4195 <para>
4196 The Yocto Project provides tools for making your image
4197 more secure.
4198 You can find these tools in the
4199 <filename>meta-security</filename> layer of the
4200 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
4201 </para>
4202 </section>
4203 </section>
4204
4205 <section id='creating-your-own-distribution'>
4206 <title>Creating Your Own Distribution</title>
4207
4208 <para>
4209 When you build an image using the Yocto Project and
4210 do not alter any distribution
4211 <link linkend='metadata'>Metadata</link>, you are creating a
4212 Poky distribution.
4213 If you wish to gain more control over package alternative
4214 selections, compile-time options, and other low-level
4215 configurations, you can create your own distribution.
4216 </para>
4217
4218 <para>
4219 To create your own distribution, the basic steps consist of
4220 creating your own distribution layer, creating your own
4221 distribution configuration file, and then adding any needed
4222 code and Metadata to the layer.
4223 The following steps provide some more detail:
4224 <itemizedlist>
4225 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
4226 Create your distribution layer so that you can keep your
4227 Metadata and code for the distribution separate.
4228 It is strongly recommended that you create and use your own
4229 layer for configuration and code.
4230 Using your own layer as compared to just placing
4231 configurations in a <filename>local.conf</filename>
4232 configuration file makes it easier to reproduce the same
4233 build configuration when using multiple build machines.
4234 See the
4235 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
4236 section for information on how to quickly set up a layer.
4237 </para></listitem>
4238 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
4239 The distribution configuration file needs to be created in
4240 the <filename>conf/distro</filename> directory of your
4241 layer.
4242 You need to name it using your distribution name
4243 (e.g. <filename>mydistro.conf</filename>).
4244 <note>
4245 The
4246 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
4247 variable in your
4248 <filename>local.conf</filename> file determines the
4249 name of your distribution.
4250 </note></para>
4251 <para>You can split out parts of your configuration file
4252 into include files and then "require" them from within
4253 your distribution configuration file.
4254 Be sure to place the include files in the
4255 <filename>conf/distro/include</filename> directory of
4256 your layer.
4257 A common example usage of include files would be to
4258 separate out the selection of desired version and revisions
4259 for individual recipes.
4260</para>
4261 <para>Your configuration file needs to set the following
4262 required variables:
4263 <literallayout class='monospaced'>
4264 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
4265 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
4266 </literallayout>
4267 These following variables are optional and you typically
4268 set them from the distribution configuration file:
4269 <literallayout class='monospaced'>
4270 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4271 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
4272 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
4273 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
4274 </literallayout>
4275 <tip>
4276 If you want to base your distribution configuration file
4277 on the very basic configuration from OE-Core, you
4278 can use
4279 <filename>conf/distro/defaultsetup.conf</filename> as
4280 a reference and just include variables that differ
4281 as compared to <filename>defaultsetup.conf</filename>.
4282 Alternatively, you can create a distribution
4283 configuration file from scratch using the
4284 <filename>defaultsetup.conf</filename> file
4285 or configuration files from other distributions
4286 such as Poky or Angstrom as references.
4287 </tip></para></listitem>
4288 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
4289 Be sure to define any other variables for which you want to
4290 create a default or enforce as part of the distribution
4291 configuration.
4292 You can include nearly any variable from the
4293 <filename>local.conf</filename> file.
4294 The variables you use are not limited to the list in the
4295 previous bulleted item.</para></listitem>
4296 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
4297 In your <filename>local.conf</filename> file in the
4298 <link linkend='build-directory'>Build Directory</link>,
4299 set your
4300 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
4301 variable to point to your distribution's configuration file.
4302 For example, if your distribution's configuration file is
4303 named <filename>mydistro.conf</filename>, then you point
4304 to it as follows:
4305 <literallayout class='monospaced'>
4306 DISTRO = "mydistro"
4307 </literallayout></para></listitem>
4308 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
4309 Use your layer to hold other information needed for the
4310 distribution:
4311 <itemizedlist>
4312 <listitem><para>Add recipes for installing
4313 distro-specific configuration files that are not
4314 already installed by another recipe.
4315 If you have distro-specific configuration files
4316 that are included by an existing recipe, you should
4317 add an append file (<filename>.bbappend</filename>)
4318 for those.
4319 For general information and recommendations
4320 on how to add recipes to your layer, see the
4321 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
4322 and
4323 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
4324 sections.</para></listitem>
4325 <listitem><para>Add any image recipes that are specific
4326 to your distribution.</para></listitem>
4327 <listitem><para>Add a <filename>psplash</filename>
4328 append file for a branded splash screen.
4329 For information on append files, see the
4330 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
4331 section.</para></listitem>
4332 <listitem><para>Add any other append files to make
4333 custom changes that are specific to individual
4334 recipes.</para></listitem>
4335 </itemizedlist></para></listitem>
4336 </itemizedlist>
4337 </para>
4338 </section>
4339
4340 <section id='creating-a-custom-template-configuration-directory'>
4341 <title>Creating a Custom Template Configuration Directory</title>
4342
4343 <para>
4344 If you're producing your own customized version
4345 of the build system for use by other users, you might
4346 want to customize the message shown by the setup script or
4347 you might want to change the template configuration files (i.e.
4348 (<filename>local.conf</filename> and
4349 <filename>bblayers.conf</filename>) that are created in
4350 a new build directory.
4351 </para>
4352
4353 <para>
4354 The OpenEmbedded build system uses the environment variable
4355 <filename>TEMPLATECONF</filename> to locate the directory
4356 from which it gathers configuration information that ultimately
4357 ends up in the
4358 <link linkend='build-directory'>Build Directory's</link>
4359 <filename>conf</filename> directory.
4360 By default, <filename>TEMPLATECONF</filename> is set as
4361 follows in the <filename>poky</filename> repository:
4362 <literallayout class='monospaced'>
4363 TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf}
4364 </literallayout>
4365 This is the directory used by the build system to find templates
4366 from which to build some key configuration files.
4367 If you look at this directory, you will see the
4368 <filename>bblayers.conf.sample</filename>,
4369 <filename>local.conf.sample</filename>, and
4370 <filename>conf-notes.txt</filename> files.
4371 The build system uses these files to form the respective
4372 <filename>bblayers.conf</filename> file,
4373 <filename>local.conf</filename> file, and display the list of
4374 BitBake targets when running the setup script.
4375 </para>
4376
4377 <para>
4378 To override these default configuration files with
4379 configurations you want used within every new
4380 Build Directory, simply set the
4381 <filename>TEMPLATECONF</filename> variable to your directory.
4382 The <filename>TEMPLATECONF</filename> variable is set in the
4383 <filename>.templateconf</filename> file, which is in the
4384 top-level
4385 <link linkend='source-directory'>Source Directory</link>
4386 folder (e.g. <filename>poky</filename>).
4387 Edit the <filename>.templateconf</filename> so that it can locate
4388 your directory.
4389 </para>
4390
4391 <para>
4392 Best practices dictate that you should keep your
4393 template configuration directory in your custom distribution layer.
4394 For example, suppose you have a layer named
4395 <filename>meta-mylayer</filename> located in your home directory
4396 and you want your template configuration directory named
4397 <filename>myconf</filename>.
4398 Changing the <filename>.templateconf</filename> as follows
4399 causes the OpenEmbedded build system to look in your directory
4400 and base its configuration files on the
4401 <filename>*.sample</filename> configuration files it finds.
4402 The final configuration files (i.e.
4403 <filename>local.conf</filename> and
4404 <filename>bblayers.conf</filename> ultimately still end up in
4405 your Build Directory, but they are based on your
4406 <filename>*.sample</filename> files.
4407 <literallayout class='monospaced'>
4408 TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf}
4409 </literallayout>
4410 </para>
4411
4412 <para>
4413 Aside from the <filename>*.sample</filename> configuration files,
4414 the <filename>conf-notes.txt</filename> also resides in the
4415 default <filename>meta-yocto/conf</filename> directory.
4416 The scripts that set up the build environment
4417 (i.e.
4418 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
4419 and
4420 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>)
4421 use this file to display BitBake targets as part of the script
4422 output.
4423 Customizing this <filename>conf-notes.txt</filename> file is a
4424 good way to make sure your list of custom targets appears
4425 as part of the script's output.
4426 </para>
4427
4428 <para>
4429 Here is the default list of targets displayed as a result of
4430 running either of the setup scripts:
4431 <literallayout class='monospaced'>
4432 You can now run 'bitbake &lt;target&gt;'
4433
4434 Common targets are:
4435 core-image-minimal
4436 core-image-sato
4437 meta-toolchain
4438 adt-installer
4439 meta-ide-support
4440 </literallayout>
4441 </para>
4442
4443 <para>
4444 Changing the listed common targets is as easy as editing your
4445 version of <filename>conf-notes.txt</filename> in your
4446 custom template configuration directory and making sure you
4447 have <filename>TEMPLATECONF</filename> set to your directory.
4448 </para>
4449 </section>
4450
4451 <section id='building-a-tiny-system'>
4452 <title>Building a Tiny System</title>
4453
4454 <para>
4455 Very small distributions have some significant advantages such
4456 as requiring less on-die or in-package memory (cheaper), better
4457 performance through efficient cache usage, lower power requirements
4458 due to less memory, faster boot times, and reduced development
4459 overhead.
4460 Some real-world examples where a very small distribution gives
4461 you distinct advantages are digital cameras, medical devices,
4462 and small headless systems.
4463 </para>
4464
4465 <para>
4466 This section presents information that shows you how you can
4467 trim your distribution to even smaller sizes than the
4468 <filename>poky-tiny</filename> distribution, which is around
4469 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
4470 </para>
4471
4472 <section id='tiny-system-overview'>
4473 <title>Overview</title>
4474
4475 <para>
4476 The following list presents the overall steps you need to
4477 consider and perform to create distributions with smaller
4478 root filesystems, achieve faster boot times, maintain your critical
4479 functionality, and avoid initial RAM disks:
4480 <itemizedlist>
4481 <listitem><para>
4482 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
4483 </para></listitem>
4484 <listitem><para>
4485 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
4486 </para></listitem>
4487 <listitem><para>
4488 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
4489 </para></listitem>
4490 <listitem><para>
4491 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
4492 </para></listitem>
4493 <listitem><para>
4494 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
4495 </para></listitem>
4496 <listitem><para>
4497 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
4498 </para></listitem>
4499 <listitem><para>
4500 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
4501 </para></listitem>
4502 </itemizedlist>
4503 </para>
4504 </section>
4505
4506 <section id='goals-and-guiding-principles'>
4507 <title>Goals and Guiding Principles</title>
4508
4509 <para>
4510 Before you can reach your destination, you need to know
4511 where you are going.
4512 Here is an example list that you can use as a guide when
4513 creating very small distributions:
4514 <itemizedlist>
4515 <listitem><para>Determine how much space you need
4516 (e.g. a kernel that is 1 Mbyte or less and
4517 a root filesystem that is 3 Mbytes or less).
4518 </para></listitem>
4519 <listitem><para>Find the areas that are currently
4520 taking 90% of the space and concentrate on reducing
4521 those areas.
4522 </para></listitem>
4523 <listitem><para>Do not create any difficult "hacks"
4524 to achieve your goals.</para></listitem>
4525 <listitem><para>Leverage the device-specific
4526 options.</para></listitem>
4527 <listitem><para>Work in a separate layer so that you
4528 keep changes isolated.
4529 For information on how to create layers, see
4530 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
4531 </para></listitem>
4532 </itemizedlist>
4533 </para>
4534 </section>
4535
4536 <section id='understand-what-gives-your-image-size'>
4537 <title>Understand What Contributes to Your Image Size</title>
4538
4539 <para>
4540 It is easiest to have something to start with when creating
4541 your own distribution.
4542 You can use the Yocto Project out-of-the-box to create the
4543 <filename>poky-tiny</filename> distribution.
4544 Ultimately, you will want to make changes in your own
4545 distribution that are likely modeled after
4546 <filename>poky-tiny</filename>.
4547 <note>
4548 To use <filename>poky-tiny</filename> in your build,
4549 set the
4550 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
4551 variable in your
4552 <filename>local.conf</filename> file to "poky-tiny"
4553 as described in the
4554 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
4555 section.
4556 </note>
4557 </para>
4558
4559 <para>
4560 Understanding some memory concepts will help you reduce the
4561 system size.
4562 Memory consists of static, dynamic, and temporary memory.
4563 Static memory is the TEXT (code), DATA (initialized data
4564 in the code), and BSS (uninitialized data) sections.
4565 Dynamic memory represents memory that is allocated at runtime:
4566 stacks, hash tables, and so forth.
4567 Temporary memory is recovered after the boot process.
4568 This memory consists of memory used for decompressing
4569 the kernel and for the <filename>__init__</filename>
4570 functions.
4571 </para>
4572
4573 <para>
4574 To help you see where you currently are with kernel and root
4575 filesystem sizes, you can use two tools found in the
4576 <link linkend='source-directory'>Source Directory</link> in
4577 the <filename>scripts/tiny/</filename> directory:
4578 <itemizedlist>
4579 <listitem><para><filename>ksize.py</filename>: Reports
4580 component sizes for the kernel build objects.
4581 </para></listitem>
4582 <listitem><para><filename>dirsize.py</filename>: Reports
4583 component sizes for the root filesystem.</para></listitem>
4584 </itemizedlist>
4585 This next tool and command help you organize configuration
4586 fragments and view file dependencies in a human-readable form:
4587 <itemizedlist>
4588 <listitem><para><filename>merge_config.sh</filename>:
4589 Helps you manage configuration files and fragments
4590 within the kernel.
4591 With this tool, you can merge individual configuration
4592 fragments together.
4593 The tool allows you to make overrides and warns you
4594 of any missing configuration options.
4595 The tool is ideal for allowing you to iterate on
4596 configurations, create minimal configurations, and
4597 create configuration files for different machines
4598 without having to duplicate your process.</para>
4599 <para>The <filename>merge_config.sh</filename> script is
4600 part of the Linux Yocto kernel Git repositories
4601 (i.e. <filename>linux-yocto-3.14</filename>,
4602 <filename>linux-yocto-3.10</filename>,
4603 <filename>linux-yocto-3.8</filename>, and so forth)
4604 in the
4605 <filename>scripts/kconfig</filename> directory.</para>
4606 <para>For more information on configuration fragments,
4607 see the
4608 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
4609 section of the Yocto Project Linux Kernel Development
4610 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
4611 section, which is in this manual.</para></listitem>
4612 <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
4613 Using the BitBake command with these options brings up
4614 a Dependency Explorer from which you can view file
4615 dependencies.
4616 Understanding these dependencies allows you to make
4617 informed decisions when cutting out various pieces of the
4618 kernel and root filesystem.</para></listitem>
4619 </itemizedlist>
4620 </para>
4621 </section>
4622
4623 <section id='trim-the-root-filesystem'>
4624 <title>Trim the Root Filesystem</title>
4625
4626 <para>
4627 The root filesystem is made up of packages for booting,
4628 libraries, and applications.
4629 To change things, you can configure how the packaging happens,
4630 which changes the way you build them.
4631 You can also tweak the filesystem itself or select a different
4632 filesystem.
4633 </para>
4634
4635 <para>
4636 First, find out what is hogging your root filesystem by running the
4637 <filename>dirsize.py</filename> script from your root directory:
4638 <literallayout class='monospaced'>
4639 $ cd &lt;root-directory-of-image&gt;
4640 $ dirsize.py 100000 > dirsize-100k.log
4641 $ cat dirsize-100k.log
4642 </literallayout>
4643 You can apply a filter to the script to ignore files under
4644 a certain size.
4645 The previous example filters out any files below 100 Kbytes.
4646 The sizes reported by the tool are uncompressed, and thus
4647 will be smaller by a relatively constant factor in a
4648 compressed root filesystem.
4649 When you examine your log file, you can focus on areas of the
4650 root filesystem that take up large amounts of memory.
4651 </para>
4652
4653 <para>
4654 You need to be sure that what you eliminate does not cripple
4655 the functionality you need.
4656 One way to see how packages relate to each other is by using
4657 the Dependency Explorer UI with the BitBake command:
4658 <literallayout class='monospaced'>
4659 $ cd &lt;image-directory&gt;
4660 $ bitbake -u depexp -g &lt;image&gt;
4661 </literallayout>
4662 Use the interface to select potential packages you wish to
4663 eliminate and see their dependency relationships.
4664 </para>
4665
4666 <para>
4667 When deciding how to reduce the size, get rid of packages that
4668 result in minimal impact on the feature set.
4669 For example, you might not need a VGA display.
4670 Or, you might be able to get by with <filename>devtmpfs</filename>
4671 and <filename>mdev</filename> instead of
4672 <filename>udev</filename>.
4673 </para>
4674
4675 <para>
4676 Use your <filename>local.conf</filename> file to make changes.
4677 For example, to eliminate <filename>udev</filename> and
4678 <filename>glib</filename>, set the following in the
4679 local configuration file:
4680 <literallayout class='monospaced'>
4681 VIRTUAL-RUNTIME_dev_manager = ""
4682 </literallayout>
4683 </para>
4684
4685 <para>
4686 Finally, you should consider exactly the type of root
4687 filesystem you need to meet your needs while also reducing
4688 its size.
4689 For example, consider <filename>cramfs</filename>,
4690 <filename>squashfs</filename>, <filename>ubifs</filename>,
4691 <filename>ext2</filename>, or an <filename>initramfs</filename>
4692 using <filename>initramfs</filename>.
4693 Be aware that <filename>ext3</filename> requires a 1 Mbyte
4694 journal.
4695 If you are okay with running read-only, you do not need this
4696 journal.
4697 </para>
4698
4699 <note>
4700 After each round of elimination, you need to rebuild your
4701 system and then use the tools to see the effects of your
4702 reductions.
4703 </note>
4704
4705
4706 </section>
4707
4708 <section id='trim-the-kernel'>
4709 <title>Trim the Kernel</title>
4710
4711 <para>
4712 The kernel is built by including policies for hardware-independent
4713 aspects.
4714 What subsystems do you enable?
4715 For what architecture are you building?
4716 Which drivers do you build by default?
4717 <note>You can modify the kernel source if you want to help
4718 with boot time.
4719 </note>
4720 </para>
4721
4722 <para>
4723 Run the <filename>ksize.py</filename> script from the top-level
4724 Linux build directory to get an idea of what is making up
4725 the kernel:
4726 <literallayout class='monospaced'>
4727 $ cd &lt;top-level-linux-build-directory&gt;
4728 $ ksize.py > ksize.log
4729 $ cat ksize.log
4730 </literallayout>
4731 When you examine the log, you will see how much space is
4732 taken up with the built-in <filename>.o</filename> files for
4733 drivers, networking, core kernel files, filesystem, sound,
4734 and so forth.
4735 The sizes reported by the tool are uncompressed, and thus
4736 will be smaller by a relatively constant factor in a compressed
4737 kernel image.
4738 Look to reduce the areas that are large and taking up around
4739 the "90% rule."
4740 </para>
4741
4742 <para>
4743 To examine, or drill down, into any particular area, use the
4744 <filename>-d</filename> option with the script:
4745 <literallayout class='monospaced'>
4746 $ ksize.py -d > ksize.log
4747 </literallayout>
4748 Using this option breaks out the individual file information
4749 for each area of the kernel (e.g. drivers, networking, and
4750 so forth).
4751 </para>
4752
4753 <para>
4754 Use your log file to see what you can eliminate from the kernel
4755 based on features you can let go.
4756 For example, if you are not going to need sound, you do not
4757 need any drivers that support sound.
4758 </para>
4759
4760 <para>
4761 After figuring out what to eliminate, you need to reconfigure
4762 the kernel to reflect those changes during the next build.
4763 You could run <filename>menuconfig</filename> and make all your
4764 changes at once.
4765 However, that makes it difficult to see the effects of your
4766 individual eliminations and also makes it difficult to replicate
4767 the changes for perhaps another target device.
4768 A better method is to start with no configurations using
4769 <filename>allnoconfig</filename>, create configuration
4770 fragments for individual changes, and then manage the
4771 fragments into a single configuration file using
4772 <filename>merge_config.sh</filename>.
4773 The tool makes it easy for you to iterate using the
4774 configuration change and build cycle.
4775 </para>
4776
4777 <para>
4778 Each time you make configuration changes, you need to rebuild
4779 the kernel and check to see what impact your changes had on
4780 the overall size.
4781 </para>
4782 </section>
4783
4784 <section id='remove-package-management-requirements'>
4785 <title>Remove Package Management Requirements</title>
4786
4787 <para>
4788 Packaging requirements add size to the image.
4789 One way to reduce the size of the image is to remove all the
4790 packaging requirements from the image.
4791 This reduction includes both removing the package manager
4792 and its unique dependencies as well as removing the package
4793 management data itself.
4794 </para>
4795
4796 <para>
4797 To eliminate all the packaging requirements for an image,
4798 be sure that "package-management" is not part of your
4799 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4800 statement for the image.
4801 When you remove this feature, you are removing the package
4802 manager as well as its dependencies from the root filesystem.
4803 </para>
4804 </section>
4805
4806 <section id='look-for-other-ways-to-minimize-size'>
4807 <title>Look for Other Ways to Minimize Size</title>
4808
4809 <para>
4810 Depending on your particular circumstances, other areas that you
4811 can trim likely exist.
4812 The key to finding these areas is through tools and methods
4813 described here combined with experimentation and iteration.
4814 Here are a couple of areas to experiment with:
4815 <itemizedlist>
4816 <listitem><para><filename>eglibc</filename>:
4817 In general, follow this process:
4818 <orderedlist>
4819 <listitem><para>Remove <filename>eglibc</filename>
4820 features from
4821 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4822 that you think you do not need.</para></listitem>
4823 <listitem><para>Build your distribution.
4824 </para></listitem>
4825 <listitem><para>If the build fails due to missing
4826 symbols in a package, determine if you can
4827 reconfigure the package to not need those
4828 features.
4829 For example, change the configuration to not
4830 support wide character support as is done for
4831 <filename>ncurses</filename>.
4832 Or, if support for those characters is needed,
4833 determine what <filename>eglibc</filename>
4834 features provide the support and restore the
4835 configuration.
4836 </para></listitem>
4837 <listitem><para>Rebuild and repeat the process.
4838 </para></listitem>
4839 </orderedlist></para></listitem>
4840 <listitem><para><filename>busybox</filename>:
4841 For BusyBox, use a process similar as described for
4842 <filename>eglibc</filename>.
4843 A difference is you will need to boot the resulting
4844 system to see if you are able to do everything you
4845 expect from the running system.
4846 You need to be sure to integrate configuration fragments
4847 into Busybox because BusyBox handles its own core
4848 features and then allows you to add configuration
4849 fragments on top.
4850 </para></listitem>
4851 </itemizedlist>
4852 </para>
4853 </section>
4854
4855 <section id='iterate-on-the-process'>
4856 <title>Iterate on the Process</title>
4857
4858 <para>
4859 If you have not reached your goals on system size, you need
4860 to iterate on the process.
4861 The process is the same.
4862 Use the tools and see just what is taking up 90% of the root
4863 filesystem and the kernel.
4864 Decide what you can eliminate without limiting your device
4865 beyond what you need.
4866 </para>
4867
4868 <para>
4869 Depending on your system, a good place to look might be
4870 Busybox, which provides a stripped down
4871 version of Unix tools in a single, executable file.
4872 You might be able to drop virtual terminal services or perhaps
4873 ipv6.
4874 </para>
4875 </section>
4876 </section>
4877
4878 <section id='working-with-packages'>
4879 <title>Working with Packages</title>
4880
4881 <para>
4882 This section describes a few tasks that involve packages:
4883 <itemizedlist>
4884 <listitem><para>
4885 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
4886 </para></listitem>
4887 <listitem><para>
4888 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
4889 </para></listitem>
4890 <listitem><para>
4891 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
4892 </para></listitem>
4893 <listitem><para>
4894 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
4895 </para></listitem>
4896 <listitem><para>
4897 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
4898 </para></listitem>
4899 <listitem><para>
4900 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
4901 </para></listitem>
4902 </itemizedlist>
4903 </para>
4904
4905 <section id='excluding-packages-from-an-image'>
4906 <title>Excluding Packages from an Image</title>
4907
4908 <para>
4909 You might find it necessary to prevent specific packages
4910 from being installed into an image.
4911 If so, you can use several variables to direct the build
4912 system to essentially ignore installing recommended packages
4913 or to not install a package at all.
4914 </para>
4915
4916 <para>
4917 The following list introduces variables you can use to
4918 prevent packages from being installed into your image.
4919 Each of these variables only works with IPK and RPM
4920 package types.
4921 Support for Debian packages does not exist.
4922 Also, you can use these variables from your
4923 <filename>local.conf</filename> file or attach them to a
4924 specific image recipe by using a recipe name override.
4925 For more detail on the variables, see the descriptions in the
4926 Yocto Project Reference Manual's glossary chapter.
4927 <itemizedlist>
4928 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
4929 Use this variable to specify "recommended-only"
4930 packages that you do not want installed.
4931 </para></listitem>
4932 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
4933 Use this variable to prevent all "recommended-only"
4934 packages from being installed.
4935 </para></listitem>
4936 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
4937 Use this variable to prevent specific packages from
4938 being installed regardless of whether they are
4939 "recommended-only" or not.
4940 You need to realize that the build process could
4941 fail with an error when you
4942 prevent the installation of a package whose presence
4943 is required by an installed package.
4944 </para></listitem>
4945 </itemizedlist>
4946 </para>
4947 </section>
4948
4949 <section id='incrementing-a-package-revision-number'>
4950 <title>Incrementing a Package Revision Number</title>
4951
4952 <para>
4953 If a committed change results in changing the package output,
4954 then the value of the
4955 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4956 variable needs to be increased (or "bumped").
4957 Increasing <filename>PR</filename> occurs one of two ways:
4958 <itemizedlist>
4959 <listitem><para>Automatically using a Package Revision
4960 Service (PR Service).</para></listitem>
4961 <listitem><para>Manually incrementing the
4962 <filename>PR</filename> variable.</para></listitem>
4963 </itemizedlist>
4964 </para>
4965
4966 <para>
4967 Given that one of the challenges any build system and its
4968 users face is how to maintain a package feed that is compatible
4969 with existing package manager applications such as
4970 RPM, APT, and OPKG, using an automated system is much
4971 preferred over a manual system.
4972 In either system, the main requirement is that version
4973 numbering increases in a linear fashion and that a number of
4974 version components exist that support that linear progression.
4975 </para>
4976
4977 <para>
4978 The following two sections provide information on the PR Service
4979 and on manual <filename>PR</filename> bumping.
4980 </para>
4981
4982 <section id='working-with-a-pr-service'>
4983 <title>Working With a PR Service</title>
4984
4985 <para>
4986 As mentioned, attempting to maintain revision numbers in the
4987 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4988 is error prone, inaccurate, and causes problems for people
4989 submitting recipes.
4990 Conversely, the PR Service automatically generates
4991 increasing numbers, particularly the revision field,
4992 which removes the human element.
4993 <note>
4994 For additional information on using a PR Service, you
4995 can see the
4996 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
4997 wiki page.
4998 </note>
4999 </para>
5000
5001 <para>
5002 The Yocto Project uses variables in order of
5003 decreasing priority to facilitate revision numbering (i.e.
5004 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
5005 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
5006 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
5007 for epoch, version, and revision, respectively).
5008 The values are highly dependent on the policies and
5009 procedures of a given distribution and package feed.
5010 </para>
5011
5012 <para>
5013 Because the OpenEmbedded build system uses
5014 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
5015 which are unique to a given build, the build system
5016 knows when to rebuild packages.
5017 All the inputs into a given task are represented by a
5018 signature, which can trigger a rebuild when different.
5019 Thus, the build system itself does not rely on the
5020 <filename>PR</filename> numbers to trigger a rebuild.
5021 The signatures, however, can be used to generate
5022 <filename>PR</filename> values.
5023 </para>
5024
5025 <para>
5026 The PR Service works with both
5027 <filename>OEBasic</filename> and
5028 <filename>OEBasicHash</filename> generators.
5029 The value of <filename>PR</filename> bumps when the
5030 checksum changes and the different generator mechanisms
5031 change signatures under different circumstances.
5032 </para>
5033
5034 <para>
5035 As implemented, the build system includes values from
5036 the PR Service into the <filename>PR</filename> field as
5037 an addition using the form "<filename>.x</filename>" so
5038 <filename>r0</filename> becomes <filename>r0.1</filename>,
5039 <filename>r0.2</filename> and so forth.
5040 This scheme allows existing <filename>PR</filename> values
5041 to be used for whatever reasons, which include manual
5042 <filename>PR</filename> bumps, should it be necessary.
5043 </para>
5044
5045 <para>
5046 By default, the PR Service is not enabled or running.
5047 Thus, the packages generated are just "self consistent".
5048 The build system adds and removes packages and
5049 there are no guarantees about upgrade paths but images
5050 will be consistent and correct with the latest changes.
5051 </para>
5052
5053 <para>
5054 The simplest form for a PR Service is for it to exist
5055 for a single host development system that builds the
5056 package feed (building system).
5057 For this scenario, you can enable a local PR Service by
5058 setting
5059 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
5060 in your <filename>local.conf</filename> file in the
5061 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
5062 <literallayout class='monospaced'>
5063 PRSERV_HOST = "localhost:0"
5064 </literallayout>
5065 Once the service is started, packages will automatically
5066 get increasing <filename>PR</filename> values and
5067 BitBake will take care of starting and stopping the server.
5068 </para>
5069
5070 <para>
5071 If you have a more complex setup where multiple host
5072 development systems work against a common, shared package
5073 feed, you have a single PR Service running and it is
5074 connected to each building system.
5075 For this scenario, you need to start the PR Service using
5076 the <filename>bitbake-prserv</filename> command:
5077 <literallayout class='monospaced'>
5078 bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
5079 </literallayout>
5080 In addition to hand-starting the service, you need to
5081 update the <filename>local.conf</filename> file of each
5082 building system as described earlier so each system
5083 points to the server and port.
5084 </para>
5085
5086 <para>
5087 It is also recommended you use build history, which adds
5088 some sanity checks to package versions, in conjunction with
5089 the server that is running the PR Service.
5090 To enable build history, add the following to each building
5091 system's <filename>local.conf</filename> file:
5092 <literallayout class='monospaced'>
5093 # It is recommended to activate "buildhistory" for testing the PR service
5094 INHERIT += "buildhistory"
5095 BUILDHISTORY_COMMIT = "1"
5096 </literallayout>
5097 For information on build history, see the
5098 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
5099 section in the Yocto Project Reference Manual.
5100 </para>
5101
5102 <note>
5103 <para>The OpenEmbedded build system does not maintain
5104 <filename>PR</filename> information as part of the
5105 shared state (sstate) packages.
5106 If you maintain an sstate feed, its expected that either
5107 all your building systems that contribute to the sstate
5108 feed use a shared PR Service, or you do not run a PR
5109 Service on any of your building systems.
5110 Having some systems use a PR Service while others do
5111 not leads to obvious problems.</para>
5112 <para>For more information on shared state, see the
5113 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
5114 section in the Yocto Project Reference Manual.</para>
5115 </note>
5116 </section>
5117
5118 <section id='manually-bumping-pr'>
5119 <title>Manually Bumping PR</title>
5120
5121 <para>
5122 The alternative to setting up a PR Service is to manually
5123 bump the
5124 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
5125 variable.
5126 </para>
5127
5128 <para>
5129 If a committed change results in changing the package output,
5130 then the value of the PR variable needs to be increased
5131 (or "bumped") as part of that commit.
5132 For new recipes you should add the <filename>PR</filename>
5133 variable and set its initial value equal to "r0", which is the default.
5134 Even though the default value is "r0", the practice of adding it to a new recipe makes
5135 it harder to forget to bump the variable when you make changes
5136 to the recipe in future.
5137 </para>
5138
5139 <para>
5140 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
5141 you can also use the
5142 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
5143 variable to ensure that
5144 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
5145 <filename>.inc</filename> file itself is changed.
5146 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
5147 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
5148 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
5149 If the <filename>.inc</filename> file is changed then its
5150 <filename>INC_PR</filename> should be incremented.
5151 </para>
5152
5153 <para>
5154 When upgrading the version of a package, assuming the
5155 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
5156 changes, the <filename>PR</filename> variable should be
5157 reset to "r0" (or "$(INC_PR).0" if you are using
5158 <filename>INC_PR</filename>).
5159 </para>
5160
5161 <para>
5162 Usually, version increases occur only to packages.
5163 However, if for some reason <filename>PV</filename> changes but does not
5164 increase, you can increase the
5165 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
5166 variable (Package Epoch).
5167 The <filename>PE</filename> variable defaults to "0".
5168 </para>
5169
5170 <para>
5171 Version numbering strives to follow the
5172 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
5173 Debian Version Field Policy Guidelines</ulink>.
5174 These guidelines define how versions are compared and what "increasing" a version means.
5175 </para>
5176 </section>
5177 </section>
5178
5179 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
5180 <title>Handling a Package Name Alias</title>
5181 <para>
5182 Sometimes a package name you are using might exist under
5183 an alias or as a similarly named package in a different
5184 distribution.
5185 The OpenEmbedded build system implements a
5186 <filename>do_distro_check</filename>
5187 task that automatically connects to major distributions
5188 and checks for these situations.
5189 If the package exists under a different name in a different
5190 distribution, you get a <filename>distro_check</filename>
5191 mismatch.
5192 You can resolve this problem by defining a per-distro recipe
5193 name alias using the
5194 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
5195 variable.
5196 </para>
5197
5198 <para>
5199 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
5200 variable:
5201 <literallayout class='monospaced'>
5202 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
5203 distro2=package_name_alias2 \
5204 distro3=package_name_alias3 \
5205 ..."
5206 </literallayout>
5207 </para>
5208
5209 <para>
5210 If you have more than one distribution alias, separate them with a space.
5211 Note that the build system currently automatically checks the
5212 Fedora, OpenSUSE, Debian, Ubuntu,
5213 and Mandriva distributions for source package recipes without having to specify them
5214 using the <filename>DISTRO_PN_ALIAS</filename> variable.
5215 For example, the following command generates a report that lists the Linux distributions
5216 that include the sources for each of the recipes.
5217 <literallayout class='monospaced'>
5218 $ bitbake world -f -c distro_check
5219 </literallayout>
5220 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
5221 file found in the
5222 <link linkend='source-directory'>Source Directory</link>.
5223 </para>
5224 </section>
5225
5226 <section id='handling-optional-module-packaging'>
5227 <title>Handling Optional Module Packaging</title>
5228
5229 <para>
5230 Many pieces of software split functionality into optional
5231 modules (or plug-ins) and the plug-ins that are built
5232 might depend on configuration options.
5233 To avoid having to duplicate the logic that determines what
5234 modules are available in your recipe or to avoid having
5235 to package each module by hand, the OpenEmbedded build system
5236 provides functionality to handle module packaging dynamically.
5237 </para>
5238
5239 <para>
5240 To handle optional module packaging, you need to do two things:
5241 <itemizedlist>
5242 <listitem><para>Ensure the module packaging is actually
5243 done.</para></listitem>
5244 <listitem><para>Ensure that any dependencies on optional
5245 modules from other recipes are satisfied by your recipe.
5246 </para></listitem>
5247 </itemizedlist>
5248 </para>
5249
5250 <section id='making-sure-the-packaging-is-done'>
5251 <title>Making Sure the Packaging is Done</title>
5252
5253 <para>
5254 To ensure the module packaging actually gets done, you use
5255 the <filename>do_split_packages</filename> function within
5256 the <filename>populate_packages</filename> Python function
5257 in your recipe.
5258 The <filename>do_split_packages</filename> function
5259 searches for a pattern of files or directories under a
5260 specified path and creates a package for each one it finds
5261 by appending to the
5262 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
5263 variable and setting the appropriate values for
5264 <filename>FILES_packagename</filename>,
5265 <filename>RDEPENDS_packagename</filename>,
5266 <filename>DESCRIPTION_packagename</filename>, and so forth.
5267 Here is an example from the <filename>lighttpd</filename>
5268 recipe:
5269 <literallayout class='monospaced'>
5270 python populate_packages_prepend () {
5271 lighttpd_libdir = d.expand('${libdir}')
5272 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
5273 'lighttpd-module-%s', 'Lighttpd module for %s',
5274 extra_depends='')
5275 }
5276 </literallayout>
5277 The previous example specifies a number of things in the
5278 call to <filename>do_split_packages</filename>.
5279 <itemizedlist>
5280 <listitem><para>A directory within the files installed
5281 by your recipe through <filename>do_install</filename>
5282 in which to search.</para></listitem>
5283 <listitem><para>A regular expression used to match module
5284 files in that directory.
5285 In the example, note the parentheses () that mark
5286 the part of the expression from which the module
5287 name should be derived.</para></listitem>
5288 <listitem><para>A pattern to use for the package names.
5289 </para></listitem>
5290 <listitem><para>A description for each package.
5291 </para></listitem>
5292 <listitem><para>An empty string for
5293 <filename>extra_depends</filename>, which disables
5294 the default dependency on the main
5295 <filename>lighttpd</filename> package.
5296 Thus, if a file in <filename>${libdir}</filename>
5297 called <filename>mod_alias.so</filename> is found,
5298 a package called <filename>lighttpd-module-alias</filename>
5299 is created for it and the
5300 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
5301 is set to "Lighttpd module for alias".</para></listitem>
5302 </itemizedlist>
5303 </para>
5304
5305 <para>
5306 Often, packaging modules is as simple as the previous
5307 example.
5308 However, more advanced options exist that you can use
5309 within <filename>do_split_packages</filename> to modify its
5310 behavior.
5311 And, if you need to, you can add more logic by specifying
5312 a hook function that is called for each package.
5313 It is also perfectly acceptable to call
5314 <filename>do_split_packages</filename> multiple times if
5315 you have more than one set of modules to package.
5316 </para>
5317
5318 <para>
5319 For more examples that show how to use
5320 <filename>do_split_packages</filename>, see the
5321 <filename>connman.inc</filename> file in the
5322 <filename>meta/recipes-connectivity/connman/</filename>
5323 directory of the <filename>poky</filename>
5324 <link linkend='yocto-project-repositories'>source repository</link>.
5325 You can also find examples in
5326 <filename>meta/classes/kernel.bbclass</filename>.
5327 </para>
5328
5329 <para>
5330 Following is a reference that shows
5331 <filename>do_split_packages</filename> mandatory and
5332 optional arguments:
5333 <literallayout class='monospaced'>
5334 Mandatory arguments
5335
5336 root
5337 The path in which to search
5338 file_regex
5339 Regular expression to match searched files.
5340 Use parentheses () to mark the part of this
5341 expression that should be used to derive the
5342 module name (to be substituted where %s is
5343 used in other function arguments as noted below)
5344 output_pattern
5345 Pattern to use for the package names. Must
5346 include %s.
5347 description
5348 Description to set for each package. Must
5349 include %s.
5350
5351 Optional arguments
5352
5353 postinst
5354 Postinstall script to use for all packages
5355 (as a string)
5356 recursive
5357 True to perform a recursive search - default
5358 False
5359 hook
5360 A hook function to be called for every match.
5361 The function will be called with the following
5362 arguments (in the order listed):
5363
5364 f
5365 Full path to the file/directory match
5366 pkg
5367 The package name
5368 file_regex
5369 As above
5370 output_pattern
5371 As above
5372 modulename
5373 The module name derived using file_regex
5374
5375 extra_depends
5376 Extra runtime dependencies (RDEPENDS) to be
5377 set for all packages. The default value of None
5378 causes a dependency on the main package
5379 (${PN}) - if you do not want this, pass empty
5380 string '' for this parameter.
5381 aux_files_pattern
5382 Extra item(s) to be added to FILES for each
5383 package. Can be a single string item or a list
5384 of strings for multiple items. Must include %s.
5385 postrm
5386 postrm script to use for all packages (as a
5387 string)
5388 allow_dirs
5389 True to allow directories to be matched -
5390 default False
5391 prepend
5392 If True, prepend created packages to PACKAGES
5393 instead of the default False which appends them
5394 match_path
5395 match file_regex on the whole relative path to
5396 the root rather than just the file name
5397 aux_files_pattern_verbatim
5398 Extra item(s) to be added to FILES for each
5399 package, using the actual derived module name
5400 rather than converting it to something legal
5401 for a package name. Can be a single string item
5402 or a list of strings for multiple items. Must
5403 include %s.
5404 allow_links
5405 True to allow symlinks to be matched - default
5406 False
5407 summary
5408 Summary to set for each package. Must include %s;
5409 defaults to description if not set.
5410 </literallayout>
5411 </para>
5412 </section>
5413
5414 <section id='satisfying-dependencies'>
5415 <title>Satisfying Dependencies</title>
5416
5417 <para>
5418 The second part for handling optional module packaging
5419 is to ensure that any dependencies on optional modules
5420 from other recipes are satisfied by your recipe.
5421 You can be sure these dependencies are satisfied by
5422 using the
5423 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
5424 Here is an example that continues with the
5425 <filename>lighttpd</filename> recipe shown earlier:
5426 <literallayout class='monospaced'>
5427 PACKAGES_DYNAMIC = "lighttpd-module-.*"
5428 </literallayout>
5429 The name specified in the regular expression can of
5430 course be anything.
5431 In this example, it is <filename>lighttpd-module-</filename>
5432 and is specified as the prefix to ensure that any
5433 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
5434 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
5435 on a package name starting with the prefix are satisfied
5436 during build time.
5437 If you are using <filename>do_split_packages</filename>
5438 as described in the previous section, the value you put in
5439 <filename>PACKAGES_DYNAMIC</filename> should correspond to
5440 the name pattern specified in the call to
5441 <filename>do_split_packages</filename>.
5442 </para>
5443 </section>
5444 </section>
5445
5446 <section id='using-runtime-package-management'>
5447 <title>Using Runtime Package Management</title>
5448
5449 <para>
5450 During a build, BitBake always transforms a recipe into one or
5451 more packages.
5452 For example, BitBake takes the <filename>bash</filename> recipe
5453 and currently produces the <filename>bash-dbg</filename>,
5454 <filename>bash-staticdev</filename>,
5455 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
5456 <filename>bash-locale</filename>, and
5457 <filename>bash</filename> packages.
5458 Not all generated packages are included in an image.
5459 </para>
5460
5461 <para>
5462 In several situations, you might need to update, add, remove,
5463 or query the packages on a target device at runtime
5464 (i.e. without having to generate a new image).
5465 Examples of such situations include:
5466 <itemizedlist>
5467 <listitem><para>
5468 You want to provide in-the-field updates to deployed
5469 devices (e.g. security updates).
5470 </para></listitem>
5471 <listitem><para>
5472 You want to have a fast turn-around development cycle
5473 for one or more applications that run on your device.
5474 </para></listitem>
5475 <listitem><para>
5476 You want to temporarily install the "debug" packages
5477 of various applications on your device so that
5478 debugging can be greatly improved by allowing
5479 access to symbols and source debugging.
5480 </para></listitem>
5481 <listitem><para>
5482 You want to deploy a more minimal package selection of
5483 your device but allow in-the-field updates to add a
5484 larger selection for customization.
5485 </para></listitem>
5486 </itemizedlist>
5487 </para>
5488
5489 <para>
5490 In all these situations, you have something similar to a more
5491 traditional Linux distribution in that in-field devices
5492 are able to receive pre-compiled packages from a server for
5493 installation or update.
5494 Being able to install these packages on a running,
5495 in-field device is what is termed "runtime package
5496 management".
5497 </para>
5498
5499 <para>
5500 In order to use runtime package management, you
5501 need a host/server machine that serves up the pre-compiled
5502 packages plus the required metadata.
5503 You also need package manipulation tools on the target.
5504 The build machine is a likely candidate to act as the server.
5505 However, that machine does not necessarily have to be the
5506 package server.
5507 The build machine could push its artifacts to another machine
5508 that acts as the server (e.g. Internet-facing).
5509 </para>
5510
5511 <para>
5512 A simple build that targets just one device produces
5513 more than one package database.
5514 In other words, the packages produced by a build are separated
5515 out into a couple of different package groupings based on
5516 criteria such as the target's CPU architecture, the target
5517 board, or the C library used on the target.
5518 For example, a build targeting the <filename>qemuarm</filename>
5519 device produces the following three package databases:
5520 <filename>all</filename>, <filename>armv5te</filename>, and
5521 <filename>qemuarm</filename>.
5522 If you wanted your <filename>qemuarm</filename> device to be
5523 aware of all the packages that were available to it,
5524 you would need to point it to each of these databases
5525 individually.
5526 In a similar way, a traditional Linux distribution usually is
5527 configured to be aware of a number of software repositories
5528 from which it retrieves packages.
5529 </para>
5530
5531 <para>
5532 Using runtime package management is completely optional and
5533 not required for a successful build or deployment in any
5534 way.
5535 But if you want to make use of runtime package management,
5536 you need to do a couple things above and beyond the basics.
5537 The remainder of this section describes what you need to do.
5538 </para>
5539
5540 <section id='runtime-package-management-build'>
5541 <title>Build Considerations</title>
5542
5543 <para>
5544 This section describes build considerations that you need
5545 to be aware of in order to provide support for runtime
5546 package management.
5547 </para>
5548
5549 <para>
5550 When BitBake generates packages it needs to know
5551 what format or formats to use.
5552 In your configuration, you use the
5553 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
5554 variable to specify the format.
5555 <note>
5556 You can choose to have more than one format but you must
5557 provide at least one.
5558 </note>
5559 </para>
5560
5561 <para>
5562 If you would like your image to start off with a basic
5563 package database of the packages in your current build
5564 as well as have the relevant tools available on the
5565 target for runtime package management, you can include
5566 "package-management" in the
5567 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5568 variable.
5569 Including "package-management" in this
5570 configuration variable ensures that when the image
5571 is assembled for your target, the image includes
5572 the currently-known package databases as well as
5573 the target-specific tools required for runtime
5574 package management to be performed on the target.
5575 However, this is not strictly necessary.
5576 You could start your image off without any databases
5577 but only include the required on-target package
5578 tool(s).
5579 As an example, you could include "opkg" in your
5580 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
5581 variable if you are using the IPK package format.
5582 You can then initialize your target's package database(s)
5583 later once your image is up and running.
5584 </para>
5585
5586 <para>
5587 Whenever you perform any sort of build step that can
5588 potentially generate a package or modify an existing
5589 package, it is always a good idea to re-generate the
5590 package index with:
5591 <literallayout class='monospaced'>
5592 $ bitbake package-index
5593 </literallayout>
5594 Realize that it is not sufficient to simply do the
5595 following:
5596 <literallayout class='monospaced'>
5597 $ bitbake &lt;some-package&gt; package-index
5598 </literallayout>
5599 This is because BitBake does not properly schedule the
5600 <filename>package-index</filename> target fully after any
5601 other target has completed.
5602 Thus, be sure to run the package update step separately.
5603 </para>
5604
5605 <para>
5606 As described below in the
5607 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
5608 section, if you are using IPK as your package format, you
5609 can make use of the
5610 <filename>distro-feed-configs</filename> recipe provided
5611 by <filename>meta-oe</filename> in order to configure your
5612 target to use your IPK databases.
5613 </para>
5614
5615 <para>
5616 When your build is complete, your packages reside in the
5617 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
5618 directory.
5619 For example, if <filename>${TMPDIR}</filename>
5620 is <filename>tmp</filename> and your selected package type
5621 is IPK, then your IPK packages are available in
5622 <filename>tmp/deploy/ipk</filename>.
5623 </para>
5624 </section>
5625
5626 <section id='runtime-package-management-server'>
5627 <title>Host or Server Machine Setup</title>
5628
5629 <para>
5630 Typically, packages are served from a server using
5631 HTTP.
5632 However, other protocols are possible.
5633 If you want to use HTTP, then setup and configure a
5634 web server, such as Apache 2 or lighttpd, on the machine
5635 serving the packages.
5636 </para>
5637
5638 <para>
5639 As previously mentioned, the build machine can act as the
5640 package server.
5641 In the following sections that describe server machine
5642 setups, the build machine is assumed to also be the server.
5643 </para>
5644
5645 <section id='package-server-apache'>
5646 <title>Serving Packages via Apache 2</title>
5647
5648 <para>
5649 This example assumes you are using the Apache 2
5650 server:
5651 <orderedlist>
5652 <listitem><para>
5653 Add the directory to your Apache
5654 configuration, which you can find at
5655 <filename>/etc/httpd/conf/httpd.conf</filename>.
5656 Use commands similar to these on the
5657 development system.
5658 These example commands assume a top-level
5659 <link linkend='source-directory'>Source Directory</link>
5660 named <filename>poky</filename> in your home
5661 directory.
5662 The example also assumes an RPM package type.
5663 If you are using a different package type, such
5664 as IPK, use "ipk" in the pathnames:
5665 <literallayout class='monospaced'>
5666 &lt;VirtualHost *:80&gt;
5667 ....
5668 Alias /rpm ~/poky/build/tmp/deploy/rpm
5669 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
5670 Options +Indexes
5671 &lt;/Directory&gt;
5672 &lt;/VirtualHost&gt;
5673 </literallayout></para></listitem>
5674 <listitem><para>
5675 Reload the Apache configuration as described
5676 in this step.
5677 For all commands, be sure you have root
5678 privileges.
5679 </para>
5680
5681 <para>
5682 If your development system is using Fedora or
5683 CentOS, use the following:
5684 <literallayout class='monospaced'>
5685 # service httpd reload
5686 </literallayout>
5687 For Ubuntu and Debian, use the following:
5688 <literallayout class='monospaced'>
5689 # /etc/init.d/apache2 reload
5690 </literallayout>
5691 For OpenSUSE, use the following:
5692 <literallayout class='monospaced'>
5693 # /etc/init.d/apache2 reload
5694 </literallayout></para></listitem>
5695 <listitem><para>
5696 If you are using Security-Enhanced Linux
5697 (SELinux), you need to label the files as
5698 being accessible through Apache.
5699 Use the following command from the development
5700 host.
5701 This example assumes RPM package types:
5702 <literallayout class='monospaced'>
5703 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
5704 </literallayout></para></listitem>
5705 </orderedlist>
5706 </para>
5707 </section>
5708
5709 <section id='package-server-lighttpd'>
5710 <title>Serving Packages via lighttpd</title>
5711
5712 <para>
5713 If you are using lighttpd, all you need
5714 to do is to provide a link from your
5715 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
5716 directory to lighttpd's document-root.
5717 You can determine the specifics of your lighttpd
5718 installation by looking through its configuration file,
5719 which is usually found at:
5720 <filename>/etc/lighttpd/lighttpd.conf</filename>.
5721 </para>
5722
5723 <para>
5724 For example, if you are using IPK, lighttpd's
5725 document-root is set to
5726 <filename>/var/www/lighttpd</filename>, and you had
5727 packages for a target named "BOARD",
5728 then you might create a link from your build location
5729 to lighttpd's document-root as follows:
5730 <literallayout class='monospaced'>
5731 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
5732 </literallayout>
5733 </para>
5734
5735 <para>
5736 At this point, you need to start the lighttpd server.
5737 The method used to start the server varies by
5738 distribution.
5739 However, one basic method that starts it by hand is:
5740 <literallayout class='monospaced'>
5741 # lighttpd -f /etc/lighttpd/lighttpd.conf
5742 </literallayout>
5743 </para>
5744 </section>
5745 </section>
5746
5747 <section id='runtime-package-management-target'>
5748 <title>Target Setup</title>
5749
5750 <para>
5751 Setting up the target differs depending on the
5752 package management system.
5753 This section provides information for RPM and IPK.
5754 </para>
5755
5756 <section id='runtime-package-management-target-rpm'>
5757 <title>Using RPM</title>
5758
5759 <para>
5760 The application for performing runtime package
5761 management of RPM packages on the target is called
5762 <filename>smart</filename>.
5763 </para>
5764
5765 <para>
5766 On the target machine, you need to inform
5767 <filename>smart</filename> of every package database
5768 you want to use.
5769 As an example, suppose your target device can use the
5770 following three package databases from a server named
5771 <filename>server.name</filename>:
5772 <filename>all</filename>, <filename>i586</filename>,
5773 and <filename>qemux86</filename>.
5774 Given this example, issue the following commands on the
5775 target:
5776 <literallayout class='monospaced'>
5777 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
5778 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
5779 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
5780 </literallayout>
5781 Also from the target machine, fetch the repository
5782 information using this command:
5783 <literallayout class='monospaced'>
5784 # smart update
5785 </literallayout>
5786 You can now use the <filename>smart query</filename>
5787 and <filename>smart install</filename> commands to
5788 find and install packages from the repositories.
5789 </para>
5790 </section>
5791
5792 <section id='runtime-package-management-target-ipk'>
5793 <title>Using IPK</title>
5794
5795 <para>
5796 The application for performing runtime package
5797 management of IPK packages on the target is called
5798 <filename>opkg</filename>.
5799 </para>
5800
5801 <para>
5802 In order to inform <filename>opkg</filename> of the
5803 package databases you want to use, simply create one
5804 or more <filename>*.conf</filename> files in the
5805 <filename>/etc/opkg</filename> directory on the target.
5806 The <filename>opkg</filename> application uses them
5807 to find its available package databases.
5808 As an example, suppose you configured your HTTP server
5809 on your machine named
5810 <filename>www.mysite.com</filename> to serve files
5811 from a <filename>BOARD-dir</filename> directory under
5812 its document-root.
5813 In this case, you might create a configuration
5814 file on the target called
5815 <filename>/etc/opkg/base-feeds.conf</filename> that
5816 contains:
5817 <literallayout class='monospaced'>
5818 src/gz all http://www.mysite.com/BOARD-dir/all
5819 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
5820 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
5821 </literallayout>
5822 </para>
5823
5824 <para>
5825 As a way of making it easier to generate and make
5826 these IPK configuration files available on your
5827 target, simply define
5828 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
5829 to point to your server and the location within the
5830 document-root which contains the databases.
5831 For example: if you are serving your packages over
5832 HTTP, your server's IP address is 192.168.7.1, and
5833 your databases are located in a directory called
5834 <filename>BOARD-dir</filename> underneath your HTTP
5835 server's document-root, you need to set
5836 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
5837 <filename>http://192.168.7.1/BOARD-dir</filename> and
5838 a set of configuration files will be generated for you
5839 in your target to work with this feed.
5840 </para>
5841
5842 <para>
5843 On the target machine, fetch (or refresh) the
5844 repository information using this command:
5845 <literallayout class='monospaced'>
5846 # opkg update
5847 </literallayout>
5848 You can now use the <filename>opkg list</filename> and
5849 <filename>opkg install</filename> commands to find and
5850 install packages from the repositories.
5851 </para>
5852 </section>
5853 </section>
5854 </section>
5855
5856 <section id='testing-packages-with-ptest'>
5857 <title>Testing Packages With ptest</title>
5858
5859 <para>
5860 A Package Test (ptest) runs tests against packages built
5861 by the OpenEmbedded build system on the target machine.
5862 A ptest contains at least two items: the actual test, and
5863 a shell script (<filename>run-ptest</filename>) that starts
5864 the test.
5865 The shell script that starts the test must not contain
5866 the actual test, the script only starts it.
5867 On the other hand, the test can be anything from a simple
5868 shell script that runs a binary and checks the output to
5869 an elaborate system of test binaries and data files.
5870 </para>
5871
5872 <para>
5873 The test generates output in the format used by
5874 Automake:
5875 <literallayout class='monospaced'>
5876 &lt;result&gt;: &lt;testname&gt;
5877 </literallayout>
5878 where the result can be <filename>PASS</filename>,
5879 <filename>FAIL</filename>, or <filename>SKIP</filename>,
5880 and the testname can be any identifying string.
5881 </para>
5882
5883 <note>
5884 A recipe is "ptest-enabled" if it inherits the
5885 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5886 class.
5887 </note>
5888
5889 <section id='adding-ptest-to-your-build'>
5890 <title>Adding ptest to Your Build</title>
5891
5892 <para>
5893 To add package testing to your build, add the
5894 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5895 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
5896 variables to your <filename>local.conf</filename> file,
5897 which is found in the
5898 <link linkend='build-directory'>Build Directory</link>:
5899 <literallayout class='monospaced'>
5900 DISTRO_FEATURES_append = " ptest"
5901 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
5902 </literallayout>
5903 Once your build is complete, the ptest files are installed
5904 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
5905 directory within the image, where
5906 <filename>&lt;package&gt;</filename> is the name of the
5907 package.
5908 </para>
5909 </section>
5910
5911 <section id='running-ptest'>
5912 <title>Running ptest</title>
5913
5914 <para>
5915 The <filename>ptest-runner</filename> package installs a
5916 shell script that loops through all installed ptest test
5917 suites and runs them in sequence.
5918 Consequently, you might want to add this package to
5919 your image.
5920 </para>
5921 </section>
5922
5923 <section id='getting-your-package-ready'>
5924 <title>Getting Your Package Ready</title>
5925
5926 <para>
5927 In order to enable a recipe to run installed ptests
5928 on target hardware,
5929 you need to prepare the recipes that build the packages
5930 you want to test.
5931 Here is what you have to do for each recipe:
5932 <itemizedlist>
5933 <listitem><para><emphasis>Be sure the recipe
5934 inherits the
5935 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5936 class:</emphasis>
5937 Include the following line in each recipe:
5938 <literallayout class='monospaced'>
5939 inherit ptest
5940 </literallayout>
5941 </para></listitem>
5942 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
5943 This script starts your test.
5944 Locate the script where you will refer to it
5945 using
5946 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
5947 Here is an example that starts a test for
5948 <filename>dbus</filename>:
5949 <literallayout class='monospaced'>
5950 #!/bin/sh
5951 cd test
5952 make -k runtest-TESTS
5953 </literallayout>
5954 </para></listitem>
5955 <listitem><para><emphasis>Ensure dependencies are
5956 met:</emphasis>
5957 If the test adds build or runtime dependencies
5958 that normally do not exist for the package
5959 (such as requiring "make" to run the test suite),
5960 use the
5961 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
5962 and
5963 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
5964 variables in your recipe in order for the package
5965 to meet the dependencies.
5966 Here is an example where the package has a runtime
5967 dependency on "make":
5968 <literallayout class='monospaced'>
5969 RDEPENDS_${PN}-ptest += "make"
5970 </literallayout>
5971 </para></listitem>
5972 <listitem><para><emphasis>Add a function to build the
5973 test suite:</emphasis>
5974 Not many packages support cross-compilation of
5975 their test suites.
5976 Consequently, you usually need to add a
5977 cross-compilation function to the package.
5978 </para>
5979 <para>Many packages based on Automake compile and
5980 run the test suite by using a single command
5981 such as <filename>make check</filename>.
5982 However, the native <filename>make check</filename>
5983 builds and runs on the same computer, while
5984 cross-compiling requires that the package is built
5985 on the host but executed on the target.
5986 The built version of Automake that ships with the
5987 Yocto Project includes a patch that separates
5988 building and execution.
5989 Consequently, packages that use the unaltered,
5990 patched version of <filename>make check</filename>
5991 automatically cross-compiles.</para>
5992 <para>However, you still must add a
5993 <filename>do_compile_ptest</filename> function to
5994 build the test suite.
5995 Add a function similar to the following to your
5996 recipe:
5997 <literallayout class='monospaced'>
5998 do_compile_ptest() {
5999 oe_runmake buildtest-TESTS
6000 }
6001 </literallayout>
6002 </para></listitem>
6003 <listitem><para><emphasis>Ensure special configurations
6004 are set:</emphasis>
6005 If the package requires special configurations
6006 prior to compiling the test code, you must
6007 insert a <filename>do_configure_ptest</filename>
6008 function into the recipe.
6009 </para></listitem>
6010 <listitem><para><emphasis>Install the test
6011 suite:</emphasis>
6012 The <filename>ptest</filename> class
6013 automatically copies the file
6014 <filename>run-ptest</filename> to the target and
6015 then runs make <filename>install-ptest</filename>
6016 to run the tests.
6017 If this is not enough, you need to create a
6018 <filename>do_install_ptest</filename> function and
6019 make sure it gets called after the
6020 "make install-ptest" completes.
6021 </para></listitem>
6022 </itemizedlist>
6023 </para>
6024 </section>
6025 </section>
6026 </section>
6027
6028 <section id='working-with-source-files'>
6029 <title>Working with Source Files</title>
6030
6031 <para>
6032 The OpenEmbedded build system works with source files located
6033 through the
6034 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
6035 variable.
6036 When you build something using BitBake, a big part of the operation
6037 is locating and downloading all the source tarballs.
6038 For images, downloading all the source for various packages can
6039 take a significant amount of time.
6040 </para>
6041
6042 <para>
6043 This section presents information for working with source
6044 files that can lead to more efficient use of resources and
6045 time.
6046 </para>
6047
6048 <section id='setting-up-effective-mirrors'>
6049 <title>Setting up Effective Mirrors</title>
6050
6051 <para>
6052 As mentioned, a good deal that goes into a Yocto Project
6053 build is simply downloading all of the source tarballs.
6054 Maybe you have been working with another build system
6055 (OpenEmbedded or Angstrom) for which you have built up a
6056 sizable directory of source tarballs.
6057 Or, perhaps someone else has such a directory for which you
6058 have read access.
6059 If so, you can save time by adding statements to your
6060 configuration file so that the build process checks local
6061 directories first for existing tarballs before checking the
6062 Internet.
6063 </para>
6064
6065 <para>
6066 Here is an efficient way to set it up in your
6067 <filename>local.conf</filename> file:
6068 <literallayout class='monospaced'>
6069 SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/"
6070 INHERIT += "own-mirrors"
6071 BB_GENERATE_MIRROR_TARBALLS = "1"
6072 # BB_NO_NETWORK = "1"
6073 </literallayout>
6074 </para>
6075
6076 <para>
6077 In the previous example, the
6078 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
6079 variable causes the OpenEmbedded build system to generate
6080 tarballs of the Git repositories and store them in the
6081 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
6082 directory.
6083 Due to performance reasons, generating and storing these
6084 tarballs is not the build system's default behavior.
6085 </para>
6086
6087 <para>
6088 You can also use the
6089 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
6090 variable.
6091 For an example, see the variable's glossary entry in the
6092 Yocto Project Reference Manual.
6093 </para>
6094 </section>
6095
6096 <section id='getting-source-files-and-suppressing-the-build'>
6097 <title>Getting Source Files and Suppressing the Build</title>
6098
6099 <para>
6100 Another technique you can use to ready yourself for a
6101 successive string of build operations, is to pre-fetch
6102 all the source files without actually starting a build.
6103 This technique lets you work through any download issues
6104 and ultimately gathers all the source files into your
6105 download directory
6106 <ulink url='&YOCTO_DOCS_REF_URL;#structure-build-downloads'><filename>build/downloads</filename></ulink>,
6107 which is located with
6108 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>.
6109 </para>
6110
6111 <para>
6112 Use the following BitBake command form to fetch all the
6113 necessary sources without starting the build:
6114 <literallayout class='monospaced'>
6115 $ bitbake -c fetchall &lt;target&gt;
6116 </literallayout>
6117 This variation of the BitBake command guarantees that you
6118 have all the sources for that BitBake target should you
6119 disconnect from the Internet and want to do the build
6120 later offline.
6121 </para>
6122 </section>
6123 </section>
6124
6125 <section id="building-software-from-an-external-source">
6126 <title>Building Software from an External Source</title>
6127
6128 <para>
6129 By default, the OpenEmbedded build system uses the
6130 <link linkend='build-directory'>Build Directory</link> to
6131 build source code.
6132 The build process involves fetching the source files, unpacking
6133 them, and then patching them if necessary before the build takes
6134 place.
6135 </para>
6136
6137 <para>
6138 Situations exist where you might want to build software from source
6139 files that are external to and thus outside of the
6140 OpenEmbedded build system.
6141 For example, suppose you have a project that includes a new BSP with
6142 a heavily customized kernel.
6143 And, you want to minimize exposing the build system to the
6144 development team so that they can focus on their project and
6145 maintain everyone's workflow as much as possible.
6146 In this case, you want a kernel source directory on the development
6147 machine where the development occurs.
6148 You want the recipe's
6149 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
6150 variable to point to the external directory and use it as is, not
6151 copy it.
6152 </para>
6153
6154 <para>
6155 To build from software that comes from an external source, all you
6156 need to do is inherit the
6157 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
6158 class and then set the
6159 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
6160 variable to point to your external source code.
6161 Here are the statements to put in your
6162 <filename>local.conf</filename> file:
6163 <literallayout class='monospaced'>
6164 INHERIT += "externalsrc"
6165 EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
6166 </literallayout>
6167 </para>
6168
6169 <para>
6170 By default, <filename>externalsrc.bbclass</filename> builds
6171 the source code in a directory separate from the external source
6172 directory as specified by
6173 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
6174 If you need to have the source built in the same directory in
6175 which it resides, or some other nominated directory, you can set
6176 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
6177 to point to that directory:
6178 <literallayout class='monospaced'>
6179 EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
6180 </literallayout>
6181 </para>
6182 </section>
6183
6184 <section id="selecting-an-initialization-manager">
6185 <title>Selecting an Initialization Manager</title>
6186
6187 <para>
6188 By default, the Yocto Project uses SysVinit as the initialization
6189 manager.
6190 However, support also exists for systemd,
6191 which is a full replacement for init with
6192 parallel starting of services, reduced shell overhead and other
6193 features that are used by many distributions.
6194 </para>
6195
6196 <para>
6197 If you want to use SysVinit, you do
6198 not have to do anything.
6199 But, if you want to use systemd, you must
6200 take some steps as described in the following sections.
6201 </para>
6202
6203 <section id='using-systemd-exclusively'>
6204 <title>Using systemd Exclusively</title>
6205
6206 <para>
6207 Set the these variables in your distribution configuration
6208 file as follows:
6209 <literallayout class='monospaced'>
6210 DISTRO_FEATURES_append = " systemd"
6211 VIRTUAL-RUNTIME_init_manager = "systemd"
6212 </literallayout>
6213 You can also prevent the SysVinit
6214 distribution feature from
6215 being automatically enabled as follows:
6216 <literallayout class='monospaced'>
6217 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
6218 </literallayout>
6219 Doing so removes any redundant SysVinit scripts.
6220 </para>
6221
6222 <para>
6223 To remove initscripts from your image altogether,
6224 set this variable also:
6225 <literallayout class='monospaced'>
6226 VIRTUAL-RUNTIME_initscripts = ""
6227 </literallayout>
6228 </para>
6229
6230 <para>
6231 For information on the backfill variable, see
6232 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
6233 </para>
6234 </section>
6235
6236 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
6237 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
6238
6239 <para>
6240 Set the these variables in your distribution configuration
6241 file as follows:
6242 <literallayout class='monospaced'>
6243 DISTRO_FEATURES_append = " systemd"
6244 VIRTUAL-RUNTIME_init_manager = "systemd"
6245 </literallayout>
6246 Doing so causes your main image to use the
6247 <filename>packagegroup-core-boot.bb</filename> recipe and
6248 systemd.
6249 The rescue/minimal image cannot use this package group.
6250 However, it can install SysVinit
6251 and the appropriate packages will have support for both
6252 systemd and SysVinit.
6253 </para>
6254 </section>
6255 </section>
6256
6257 <section id="platdev-appdev-srcrev">
6258 <title>Using an External SCM</title>
6259
6260 <para>
6261 If you're working on a recipe that pulls from an external Source
6262 Code Manager (SCM), it is possible to have the OpenEmbedded build
6263 system notice new recipe changes added to the SCM and then build
6264 the resulting packages that depend on the new recipes by using
6265 the latest versions.
6266 This only works for SCMs from which it is possible to get a
6267 sensible revision number for changes.
6268 Currently, you can do this with Apache Subversion (SVN), Git, and
6269 Bazaar (BZR) repositories.
6270 </para>
6271
6272 <para>
6273 To enable this behavior, the
6274 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
6275 of the recipe needs to reference
6276 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
6277 Here is an example:
6278 <literallayout class='monospaced'>
6279 PV = "1.2.3+git${SRCPV}
6280 </literallayout>
6281 Then, you can add the following to your
6282 <filename>local.conf</filename>:
6283 <literallayout class='monospaced'>
6284 SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
6285 </literallayout>
6286 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
6287 is the name of the recipe for which you want to enable automatic source
6288 revision updating.
6289 </para>
6290
6291 <para>
6292 If you do not want to update your local configuration file, you can
6293 add the following directly to the recipe to finish enabling
6294 the feature:
6295 <literallayout class='monospaced'>
6296 SRCREV = "${AUTOREV}"
6297 </literallayout>
6298 </para>
6299
6300 <para>
6301 The Yocto Project provides a distribution named
6302 <filename>poky-bleeding</filename>, whose configuration
6303 file contains the line:
6304 <literallayout class='monospaced'>
6305 require conf/distro/include/poky-floating-revisions.inc
6306 </literallayout>
6307 This line pulls in the listed include file that contains
6308 numerous lines of exactly that form:
6309 <literallayout class='monospaced'>
6310 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
6311 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
6312 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
6313 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
6314 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
6315 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
6316 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
6317 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
6318 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
6319 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
6320 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
6321 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
6322 SRCREV_pn-screenshot ?= "${AUTOREV}"
6323 SRCREV_pn-libfakekey ?= "${AUTOREV}"
6324 SRCREV_pn-oprofileui ?= "${AUTOREV}"
6325 .
6326 .
6327 .
6328 </literallayout>
6329 These lines allow you to experiment with building a
6330 distribution that tracks the latest development source
6331 for numerous packages.
6332 <note><title>Caution</title>
6333 The <filename>poky-bleeding</filename> distribution
6334 is not tested on a regular basis.
6335 Keep this in mind if you use it.
6336 </note>
6337 </para>
6338 </section>
6339
6340 <section id='creating-a-read-only-root-filesystem'>
6341 <title>Creating a Read-Only Root Filesystem</title>
6342
6343 <para>
6344 Suppose, for security reasons, you need to disable
6345 your target device's root filesystem's write permissions
6346 (i.e. you need a read-only root filesystem).
6347 Or, perhaps you are running the device's operating system
6348 from a read-only storage device.
6349 For either case, you can customize your image for
6350 that behavior.
6351 </para>
6352
6353 <note>
6354 Supporting a read-only root filesystem requires that the system and
6355 applications do not try to write to the root filesystem.
6356 You must configure all parts of the target system to write
6357 elsewhere, or to gracefully fail in the event of attempting to
6358 write to the root filesystem.
6359 </note>
6360
6361 <section id='creating-the-root-filesystem'>
6362 <title>Creating the Root Filesystem</title>
6363
6364 <para>
6365 To create the read-only root filesystem, simply add the
6366 "read-only-rootfs" feature to your image.
6367 Using either of the following statements in your
6368 image recipe or from within the
6369 <filename>local.conf</filename> file found in the
6370 <link linkend='build-directory'>Build Directory</link>
6371 causes the build system to create a read-only root filesystem:
6372 <literallayout class='monospaced'>
6373 IMAGE_FEATURES = "read-only-rootfs"
6374 </literallayout>
6375 or
6376 <literallayout class='monospaced'>
6377 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
6378 </literallayout>
6379 </para>
6380
6381 <para>
6382 For more information on how to use these variables, see the
6383 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
6384 section.
6385 For information on the variables, see
6386 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6387 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
6388 </para>
6389 </section>
6390
6391 <section id='post-installation-scripts'>
6392 <title>Post-Installation Scripts</title>
6393
6394 <para>
6395 It is very important that you make sure all
6396 post-Installation (<filename>pkg_postinst</filename>) scripts
6397 for packages that are installed into the image can be run
6398 at the time when the root filesystem is created during the
6399 build on the host system.
6400 These scripts cannot attempt to run during first-boot on the
6401 target device.
6402 With the "read-only-rootfs" feature enabled,
6403 the build system checks during root filesystem creation to make
6404 sure all post-installation scripts succeed.
6405 If any of these scripts still need to be run after the root
6406 filesystem is created, the build immediately fails.
6407 These build-time checks ensure that the build fails
6408 rather than the target device fails later during its
6409 initial boot operation.
6410 </para>
6411
6412 <para>
6413 Most of the common post-installation scripts generated by the
6414 build system for the out-of-the-box Yocto Project are engineered
6415 so that they can run during root filesystem creation
6416 (e.g. post-installation scripts for caching fonts).
6417 However, if you create and add custom scripts, you need
6418 to be sure they can be run during this file system creation.
6419 </para>
6420
6421 <para>
6422 Here are some common problems that prevent
6423 post-installation scripts from running during root filesystem
6424 creation:
6425 <itemizedlist>
6426 <listitem><para>
6427 <emphasis>Not using $D in front of absolute
6428 paths:</emphasis>
6429 The build system defines
6430 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
6431 when the root filesystem is created.
6432 Furthermore, <filename>$D</filename> is blank when the
6433 script is run on the target device.
6434 This implies two purposes for <filename>$D</filename>:
6435 ensuring paths are valid in both the host and target
6436 environments, and checking to determine which
6437 environment is being used as a method for taking
6438 appropriate actions.
6439 </para></listitem>
6440 <listitem><para>
6441 <emphasis>Attempting to run processes that are
6442 specific to or dependent on the target
6443 architecture:</emphasis>
6444 You can work around these attempts by using native
6445 tools to accomplish the same tasks, or
6446 by alternatively running the processes under QEMU,
6447 which has the <filename>qemu_run_binary</filename>
6448 function.
6449 For more information, see the
6450 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
6451 class.</para></listitem>
6452 </itemizedlist>
6453 </para>
6454 </section>
6455
6456 <section id='areas-with-write-access'>
6457 <title>Areas With Write Access</title>
6458
6459 <para>
6460 With the "read-only-rootfs" feature enabled,
6461 any attempt by the target to write to the root filesystem at
6462 runtime fails.
6463 Consequently, you must make sure that you configure processes
6464 and applications that attempt these types of writes do so
6465 to directories with write access (e.g.
6466 <filename>/tmp</filename> or <filename>/var/run</filename>).
6467 </para>
6468 </section>
6469 </section>
6470
6471 <section id="performing-automated-runtime-testing">
6472 <title>Performing Automated Runtime Testing</title>
6473
6474 <para>
6475 The OpenEmbedded build system makes available a series of automated
6476 tests for images to verify runtime functionality.
6477 You can run these tests on either QEMU or actual target hardware.
6478 Tests are written in Python making use of the
6479 <filename>unittest</filename> module, and the majority of them
6480 run commands on the target system over SSH.
6481 This section describes how you set up the environment to use these
6482 tests, run available tests, and write and add your own tests.
6483 </para>
6484
6485 <section id='enabling-tests'>
6486 <title>Enabling Tests</title>
6487
6488 <para>
6489 Depending on whether you are planning on running tests using
6490 QEMU or on running them on the hardware, you have to take
6491 different steps to enable the tests.
6492 See the following subsections for information on how to
6493 enable both types of tests.
6494 </para>
6495
6496 <section id='qemu-image-enabling-tests'>
6497 <title>Enabling Runtime Tests on QEMU</title>
6498
6499 <para>
6500 In order to run tests, you need to do the following:
6501 <itemizedlist>
6502 <listitem><para><emphasis>Set up to avoid interaction
6503 with <filename>sudo</filename> for networking:</emphasis>
6504 To accomplish this, you must do one of the
6505 following:
6506 <itemizedlist>
6507 <listitem><para>Add
6508 <filename>NOPASSWD</filename> for your user
6509 in <filename>/etc/sudoers</filename> either for
6510 ALL commands or just for
6511 <filename>runqemu-ifup</filename>.
6512 You must provide the full path as that can
6513 change if you are using multiple clones of the
6514 source repository.
6515 <note>
6516 On some distributions, you also need to
6517 comment out "Defaults requiretty" in
6518 <filename>/etc/sudoers</filename>.
6519 </note></para></listitem>
6520 <listitem><para>Manually configure a tap interface
6521 for your system.</para></listitem>
6522 <listitem><para>Run as root the script in
6523 <filename>scripts/runqemu-gen-tapdevs</filename>,
6524 which should generate a list of tap devices.
6525 This is the option typically chosen for
6526 Autobuilder-type environments.
6527 </para></listitem>
6528 </itemizedlist></para></listitem>
6529 <listitem><para><emphasis>Set the
6530 <filename>DISPLAY</filename> variable:</emphasis>
6531 You need to set this variable so that you have an X
6532 server available (e.g. start
6533 <filename>vncserver</filename> for a headless machine).
6534 </para></listitem>
6535 <listitem><para><emphasis>Be sure your host's firewall
6536 accepts incoming connections from
6537 192.168.7.0/24:</emphasis>
6538 Some of the tests (in particular smart tests) start an
6539 HTTP server on a random high number port, which is
6540 used to serve files to the target.
6541 The smart module serves
6542 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
6543 smart channel commands. That means your host's firewall
6544 must accept incoming connections from 192.168.7.0/24,
6545 which is the default IP range used for tap devices
6546 by <filename>runqemu</filename>.</para></listitem>
6547 </itemizedlist>
6548 </para>
6549
6550 <para>
6551 Once you start running the tests, the following happens:
6552 <itemizedlist>
6553 <listitem><para>A copy of the root filesystem is written
6554 to <filename>${WORKDIR}/testimage</filename>.
6555 </para></listitem>
6556 <listitem><para>The image is booted under QEMU using the
6557 standard <filename>runqemu</filename> script.
6558 </para></listitem>
6559 <listitem><para>A default timeout of 500 seconds occurs
6560 to allow for the boot process to reach the login prompt.
6561 You can change the timeout period by setting
6562 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
6563 in the <filename>local.conf</filename> file.
6564 </para></listitem>
6565 <listitem><para>Once the boot process is reached and the
6566 login prompt appears, the tests run.
6567 The full boot log is written to
6568 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
6569 </para></listitem>
6570 <listitem><para>Each test module loads in the order found
6571 in <filename>TEST_SUITES</filename>.
6572 You can find the full output of the commands run over
6573 SSH in
6574 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
6575 </para></listitem>
6576 <listitem><para>If no failures occur, the task running the
6577 tests ends successfully.
6578 You can find the output from the
6579 <filename>unittest</filename> in the task log at
6580 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
6581 </para></listitem>
6582 </itemizedlist>
6583 </para>
6584 </section>
6585
6586 <section id='hardware-image-enabling-tests'>
6587 <title>Enabling Runtime Tests on Hardware</title>
6588
6589 <para>
6590 The OpenEmbedded build system can run tests on real
6591 hardware, and for certain devices it can also deploy
6592 the image to be tested onto the device beforehand.
6593 </para>
6594
6595 <para>
6596 For automated deployment, a "master image" is installed
6597 onto the hardware once as part of setup.
6598 Then, each time tests are to be run, the following
6599 occurs:
6600 <orderedlist>
6601 <listitem><para>The master image is booted into and
6602 used to write the image to be tested to
6603 a second partition.
6604 </para></listitem>
6605 <listitem><para>The device is then rebooted using an
6606 external script that you need to provide.
6607 </para></listitem>
6608 <listitem><para>The device boots into the image to be
6609 tested.
6610 </para></listitem>
6611 </orderedlist>
6612 </para>
6613
6614 <para>
6615 When running tests (independent of whether the image
6616 has been deployed automatically or not), the device is
6617 expected to be connected to a network on a
6618 pre-determined IP address.
6619 You can either use static IP addresses written into
6620 the image, or set the image to use DHCP and have your
6621 DHCP server on the test network assign a known IP address
6622 based on the MAC address of the device.
6623 </para>
6624
6625 <para>
6626 In order to run tests on hardware, you need to set
6627 <filename>TEST_TARGET</filename> to an appropriate value.
6628 For QEMU, you do not have to change anything, the default
6629 value is "QemuTarget".
6630 For running tests on hardware, two options exist:
6631 "SimpleRemoteTarget" and "GummibootTarget".
6632 <itemizedlist>
6633 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
6634 Choose "SimpleRemoteTarget" if you are going to
6635 run tests on a target system that is already
6636 running the image to be tested and is available
6637 on the network.
6638 You can use "SimpleRemoteTarget" in conjunction
6639 with either real hardware or an image running
6640 within a separately started QEMU or any
6641 other virtual machine manager.
6642 </para></listitem>
6643 <listitem><para><emphasis>"GummibootTarget":</emphasis>
6644 Choose "GummibootTarget" if your hardware is
6645 an EFI-based machine with
6646 <filename>gummiboot</filename> as bootloader and
6647 <filename>core-image-testmaster</filename>
6648 (or something similar) is installed.
6649 Also, your hardware under test must be in a
6650 DHCP-enabled network that gives it the same IP
6651 address for each reboot.</para>
6652 <para>If you choose "GummibootTarget", there are
6653 additional requirements and considerations.
6654 See the
6655 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
6656 section, which follows, for more information.
6657 </para></listitem>
6658 </itemizedlist>
6659 </para>
6660 </section>
6661
6662 <section id='selecting-gummiboottarget'>
6663 <title>Selecting GummibootTarget</title>
6664
6665 <para>
6666 If you did not set <filename>TEST_TARGET</filename> to
6667 "GummibootTarget", then you do not need any information
6668 in this section.
6669 You can skip down to the
6670 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
6671 section.
6672 </para>
6673
6674 <para>
6675 If you did set <filename>TEST_TARGET</filename> to
6676 "GummibootTarget", you also need to perform a one-time
6677 setup of your master image by doing the following:
6678 <orderedlist>
6679 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
6680 Be sure that <filename>EFI_PROVIDER</filename>
6681 is as follows:
6682 <literallayout class='monospaced'>
6683 EFI_PROVIDER = "gummiboot"
6684 </literallayout>
6685 </para></listitem>
6686 <listitem><para><emphasis>Build the master image:</emphasis>
6687 Build the <filename>core-image-testmaster</filename>
6688 image.
6689 The <filename>core-image-testmaster</filename>
6690 recipe is provided as an example for a
6691 "master" image and you can customize the image
6692 recipe as you would any other recipe.
6693 </para>
6694 <para>Here are the image recipe requirements:
6695 <itemizedlist>
6696 <listitem><para>Inherits
6697 <filename>core-image</filename>
6698 so that kernel modules are installed.
6699 </para></listitem>
6700 <listitem><para>Installs normal linux utilities
6701 not busybox ones (e.g.
6702 <filename>bash</filename>,
6703 <filename>coreutils</filename>,
6704 <filename>tar</filename>,
6705 <filename>gzip</filename>, and
6706 <filename>kmod</filename>).
6707 </para></listitem>
6708 <listitem><para>Uses a custom
6709 initramfs image with a custom installer.
6710 A normal image that you can install usually
6711 creates a single rootfs partition.
6712 This image uses another installer that
6713 creates a specific partition layout.
6714 Not all Board Support Packages (BSPs)
6715 can use an installer.
6716 For such cases, you need to manually create
6717 the following partition layout on the
6718 target:
6719 <itemizedlist>
6720 <listitem><para>First partition mounted
6721 under <filename>/boot</filename>,
6722 labeled "boot".
6723 </para></listitem>
6724 <listitem><para>The main rootfs
6725 partition where this image gets
6726 installed, which is mounted under
6727 <filename>/</filename>.
6728 </para></listitem>
6729 <listitem><para>Another partition
6730 labeled "testrootfs" where test
6731 images get deployed.
6732 </para></listitem>
6733 </itemizedlist>
6734 </para></listitem>
6735 </itemizedlist>
6736 </para></listitem>
6737 <listitem><para><emphasis>Install image:</emphasis>
6738 Install the image that you just built on the target
6739 system.
6740 </para></listitem>
6741 </orderedlist>
6742 </para>
6743
6744 <para>
6745 The final thing you need to do when setting
6746 <filename>TEST_TARGET</filename> to "GummibootTarget" is
6747 to set up the test image:
6748 <orderedlist>
6749 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
6750 Make sure you have the following statements in
6751 your <filename>local.conf</filename> file:
6752 <literallayout class='monospaced'>
6753 IMAGE_FSTYPES += "tar.gz"
6754 INHERIT += "testimage"
6755 TEST_TARGET = "GummibootTarget"
6756 TEST_TARGET_IP = "192.168.2.3"
6757 </literallayout>
6758 </para></listitem>
6759 <listitem><para><emphasis>Build your test image:</emphasis>
6760 Use BitBake to build the image:
6761 <literallayout class='monospaced'>
6762 $ bitbake core-image-sato
6763 </literallayout>
6764 </para></listitem>
6765 </orderedlist>
6766 </para>
6767
6768 <para>
6769 Here is some additional information regarding running
6770 "GummibootTarget" as your test target:
6771 <itemizedlist>
6772 <listitem><para>
6773 You can use
6774 <filename>TEST_POWERCONTROL_CMD</filename>
6775 together with
6776 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
6777 as a command that runs on the host and does power
6778 cycling.
6779 The test code passes one argument to that command:
6780 off, on or cycle (off then on).
6781 Here is an example that could appear in your
6782 <filename>local.conf</filename> file:
6783 <literallayout class='monospaced'>
6784 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
6785 </literallayout>
6786 In this example, the expect script does the
6787 following:
6788 <literallayout class='monospaced'>
6789 ssh test@10.11.12.1 "pyctl nuc1 &lt;arg&gt;"
6790 </literallayout>
6791 It then runs a Python script that controls power
6792 for a label called <filename>nuc1</filename>.
6793 <note>
6794 You need to customize
6795 <filename>TEST_POWERCONTROL_CMD</filename>
6796 and
6797 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
6798 for your own setup.
6799 The one requirement is that it accepts
6800 "on", "off", and "cycle" as the last argument.
6801 </note>
6802 </para></listitem>
6803 <listitem><para>
6804 When no command is defined, it connects to the
6805 device over SSH and uses the classic reboot command
6806 to reboot the device.
6807 Classic reboot is fine as long as the machine
6808 actually reboots (i.e. the SSH test has not
6809 failed).
6810 It is useful for scenarios where you have a simple
6811 setup, typically with a single board, and where
6812 some manual interaction is okay from time to time.
6813 </para></listitem>
6814 </itemizedlist>
6815 </para>
6816 </section>
6817 </section>
6818
6819 <section id="qemu-image-running-tests">
6820 <title>Running Tests</title>
6821
6822 <para>
6823 You can start the tests automatically or manually:
6824 <itemizedlist>
6825 <listitem><para><emphasis>Automatically running tests:</emphasis>
6826 To run the tests automatically after the
6827 OpenEmbedded build system successfully creates an image,
6828 first set the
6829 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
6830 variable to "1" in your <filename>local.conf</filename>
6831 file in the
6832 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6833 <literallayout class='monospaced'>
6834 TEST_IMAGE = "1"
6835 </literallayout>
6836 Next, build your image.
6837 If the image successfully builds, the tests will be
6838 run:
6839 <literallayout class='monospaced'>
6840 bitbake core-image-sato
6841 </literallayout></para></listitem>
6842 <listitem><para><emphasis>Manually running tests:</emphasis>
6843 To manually run the tests, first globally inherit the
6844 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
6845 class by editing your <filename>local.conf</filename>
6846 file:
6847 <literallayout class='monospaced'>
6848 INHERIT += "testimage"
6849 </literallayout>
6850 Next, use BitBake to run the tests:
6851 <literallayout class='monospaced'>
6852 bitbake -c testimage &lt;image&gt;
6853 </literallayout></para></listitem>
6854 </itemizedlist>
6855 </para>
6856
6857 <para>
6858 All test files reside in
6859 <filename>meta/lib/oeqa/runtime</filename> in the
6860 <link linkend='source-directory'>Source Directory</link>.
6861 A test name maps directly to a Python module.
6862 Each test module may contain a number of individual tests.
6863 Tests are usually grouped together by the area
6864 tested (e.g tests for systemd reside in
6865 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
6866 </para>
6867
6868 <para>
6869 You can add tests to any layer provided you place them in the
6870 proper area and you extend
6871 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6872 in the <filename>local.conf</filename> file as normal.
6873 Be sure that tests reside in
6874 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
6875 <note>
6876 Be sure that module names do not collide with module names
6877 used in the default set of test modules in
6878 <filename>meta/lib/oeqa/runtime</filename>.
6879 </note>
6880 </para>
6881
6882 <para>
6883 You can change the set of tests run by appending or overriding
6884 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
6885 variable in <filename>local.conf</filename>.
6886 Each name in <filename>TEST_SUITES</filename> represents a
6887 required test for the image.
6888 Test modules named within <filename>TEST_SUITES</filename>
6889 cannot be skipped even if a test is not suitable for an image
6890 (e.g. running the RPM tests on an image without
6891 <filename>rpm</filename>).
6892 Appending "auto" to <filename>TEST_SUITES</filename> causes the
6893 build system to try to run all tests that are suitable for the
6894 image (i.e. each test module may elect to skip itself).
6895 </para>
6896
6897 <para>
6898 The order you list tests in <filename>TEST_SUITES</filename>
6899 is important and influences test dependencies.
6900 Consequently, tests that depend on other tests should be added
6901 after the test on which they depend.
6902 For example, since the <filename>ssh</filename> test
6903 depends on the
6904 <filename>ping</filename> test, "ssh" needs to come after
6905 "ping" in the list.
6906 The test class provides no re-ordering or dependency handling.
6907 <note>
6908 Each module can have multiple classes with multiple test
6909 methods.
6910 And, Python <filename>unittest</filename> rules apply.
6911 </note>
6912 </para>
6913
6914 <para>
6915 Here are some things to keep in mind when running tests:
6916 <itemizedlist>
6917 <listitem><para>The default tests for the image are defined
6918 as:
6919 <literallayout class='monospaced'>
6920 DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
6921 </literallayout></para></listitem>
6922 <listitem><para>Add your own test to the list of the
6923 by using the following:
6924 <literallayout class='monospaced'>
6925 TEST_SUITES_append = " mytest"
6926 </literallayout></para></listitem>
6927 <listitem><para>Run a specific list of tests as follows:
6928 <literallayout class='monospaced'>
6929 TEST_SUITES = "test1 test2 test3"
6930 </literallayout>
6931 Remember, order is important.
6932 Be sure to place a test that is dependent on another test
6933 later in the order.</para></listitem>
6934 </itemizedlist>
6935 </para>
6936 </section>
6937
6938 <section id="exporting-tests">
6939 <title>Exporting Tests</title>
6940
6941 <para>
6942 You can export tests so that they can run independently of
6943 the build system.
6944 Exporting tests is required if you want to be able to hand
6945 the test execution off to a scheduler.
6946 You can only export tests that are defined in
6947 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
6948 </para>
6949
6950 <para>
6951 If you image is already built, make sure the following are set
6952 in your <filename>local.conf</filename> file.
6953 Be sure to provide the IP address you need:
6954 <literallayout class='monospaced'>
6955 TEST_EXPORT_ONLY = "1"
6956 TEST_TARGET = "simpleremote"
6957 TEST_TARGET_IP = "192.168.7.2"
6958 TEST_SERVER_IP = "192.168.7.1"
6959 </literallayout>
6960 You can then export the tests with the following:
6961 <literallayout class='monospaced'>
6962 $ bitbake core-image-sato -c testimage
6963 </literallayout>
6964 Exporting the tests places them in the
6965 <link linkend='build-directory'>Build Directory</link> in
6966 <filename>tmp/testimage/core-image-sato</filename>, which
6967 is controlled by the
6968 <filename>TEST_EXPORT_DIR</filename> variable.
6969 </para>
6970
6971 <para>
6972 The exported data (i.e. <filename>testdata.json</filename>)
6973 contains paths to the Build Directory.
6974 Thus, the contents of the directory can be moved
6975 to another machine as long as you update some paths in the
6976 JSON.
6977 Usually you only care about the
6978 ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests
6979 are enabled).
6980 Consequently, running the tests on other machine
6981 means that you have to move the contents and call
6982 <filename>runexported</filename> with "--deploy-dir PATH:
6983 ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json
6984 runexported.py accepts other arguments as well, see --help.
6985 </para>
6986
6987 <para>
6988 You can now run the tests outside of the build environment:
6989 <literallayout class='monospaced'>
6990 $ cd tmp/testimage/core-image-sato
6991 $ ./runexported.py testdata.json
6992 </literallayout>
6993 <note>
6994 This "export" feature does not deploy or boot the target
6995 image.
6996 Your target (be it a Qemu or hardware one)
6997 has to already be up and running when you call
6998 <filename>runexported.py</filename>
6999 </note>
7000 </para>
7001 </section>
7002
7003 <section id="qemu-image-writing-new-tests">
7004 <title>Writing New Tests</title>
7005
7006 <para>
7007 As mentioned previously, all new test files need to be in the
7008 proper place for the build system to find them.
7009 New tests for additional functionality outside of the core
7010 should be added to the layer that adds the functionality, in
7011 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
7012 long as
7013 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
7014 is extended in the layer's
7015 <filename>layer.conf</filename> file as normal).
7016 Just remember that filenames need to map directly to test
7017 (module) names and that you do not use module names that
7018 collide with existing core tests.
7019 </para>
7020
7021 <para>
7022 To create a new test, start by copying an existing module
7023 (e.g. <filename>syslog.py</filename> or
7024 <filename>gcc.py</filename> are good ones to use).
7025 Test modules can use code from
7026 <filename>meta/lib/oeqa/utils</filename>, which are helper
7027 classes.
7028 </para>
7029
7030 <note>
7031 Structure shell commands such that you rely on them and they
7032 return a single code for success.
7033 Be aware that sometimes you will need to parse the output.
7034 See the <filename>df.py</filename> and
7035 <filename>date.py</filename> modules for examples.
7036 </note>
7037
7038 <para>
7039 You will notice that all test classes inherit
7040 <filename>oeRuntimeTest</filename>, which is found in
7041 <filename>meta/lib/oetest.py</filename>.
7042 This base class offers some helper attributes, which are
7043 described in the following sections:
7044 </para>
7045
7046 <section id='qemu-image-writing-tests-class-methods'>
7047 <title>Class Methods</title>
7048
7049 <para>
7050 Class methods are as follows:
7051 <itemizedlist>
7052 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
7053 Returns "True" if <filename>pkg</filename> is in the
7054 installed package list of the image, which is based
7055 on the manifest file that is generated during the
7056 <filename>do_rootfs</filename> task.
7057 </para></listitem>
7058 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
7059 Returns "True" if the feature is in
7060 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
7061 or
7062 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
7063 </para></listitem>
7064 </itemizedlist>
7065 </para>
7066 </section>
7067
7068 <section id='qemu-image-writing-tests-class-attributes'>
7069 <title>Class Attributes</title>
7070
7071 <para>
7072 Class attributes are as follows:
7073 <itemizedlist>
7074 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
7075 Equals "ps -ef" if <filename>procps</filename> is
7076 installed in the image.
7077 Otherwise, <filename>pscmd</filename> equals
7078 "ps" (busybox).
7079 </para></listitem>
7080 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
7081 The called text context, which gives access to the
7082 following attributes:
7083 <itemizedlist>
7084 <listitem><para><emphasis><filename>d</filename>:</emphasis>
7085 The BitBake datastore, which allows you to
7086 use stuff such as
7087 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
7088 </para></listitem>
7089 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
7090 Used internally.
7091 The tests do not need these.
7092 </para></listitem>
7093 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
7094 The absolute path to
7095 <filename>meta/lib/oeqa/runtime/files</filename>,
7096 which contains helper files for tests meant
7097 for copying on the target such as small
7098 files written in C for compilation.
7099 </para></listitem>
7100 <listitem><para><emphasis><filename>target</filename>:</emphasis>
7101 The target controller object used to deploy
7102 and start an image on a particular target
7103 (e.g. QemuTarget, SimpleRemote, and
7104 GummibootTarget).
7105 Tests usually use the following:
7106 <itemizedlist>
7107 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
7108 The target's IP address.
7109 </para></listitem>
7110 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
7111 The host's IP address, which is
7112 usually used by the "smart" test
7113 suite.
7114 </para></listitem>
7115 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
7116 The single, most used method.
7117 This command is a wrapper for:
7118 <filename>ssh root@host "cmd"</filename>.
7119 The command returns a tuple:
7120 (status, output), which are what
7121 their names imply - the return code
7122 of 'cmd' and whatever output
7123 it produces.
7124 The optional timeout argument
7125 represents the number of seconds the
7126 test should wait for 'cmd' to
7127 return.
7128 If the argument is "None", the
7129 test uses the default instance's
7130 timeout period, which is 300
7131 seconds.
7132 If the argument is "0", the test
7133 runs until the command returns.
7134 </para></listitem>
7135 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
7136 <filename>scp localpath root@ip:remotepath</filename>.
7137 </para></listitem>
7138 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
7139 <filename>scp root@host:remotepath localpath</filename>.
7140 </para></listitem>
7141 </itemizedlist></para></listitem>
7142 </itemizedlist></para></listitem>
7143 </itemizedlist>
7144 </para>
7145 </section>
7146
7147 <section id='qemu-image-writing-tests-instance-attributes'>
7148 <title>Instance Attributes</title>
7149
7150 <para>
7151 A single instance attribute exists, which is
7152 <filename>target</filename>.
7153 The <filename>target</filename> instance attribute is
7154 identical to the class attribute of the same name, which
7155 is described in the previous section.
7156 This attribute exists as both an instance and class
7157 attribute so tests can use
7158 <filename>self.target.run(cmd)</filename> in instance
7159 methods instead of
7160 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
7161 </para>
7162 </section>
7163 </section>
7164 </section>
7165
7166 <section id="platdev-gdb-remotedebug">
7167 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
7168
7169 <para>
7170 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
7171 It also allows you to perform post-mortem style analysis of program crashes.
7172 GDB is available as a package within the Yocto Project and is
7173 installed in SDK images by default.
7174 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
7175 in the Yocto Project Reference Manual for a description of these images.
7176 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
7177 </para>
7178
7179 <tip>
7180 For best results, install DBG (<filename>-dbg</filename>) packages
7181 for the applications you are going to debug.
7182 Doing so makes extra debug symbols available that give you more
7183 meaningful output.
7184 </tip>
7185
7186 <para>
7187 Sometimes, due to memory or disk space constraints, it is not possible
7188 to use GDB directly on the remote target to debug applications.
7189 These constraints arise because GDB needs to load the debugging information and the
7190 binaries of the process being debugged.
7191 Additionally, GDB needs to perform many computations to locate information such as function
7192 names, variable names and values, stack traces and so forth - even before starting the
7193 debugging process.
7194 These extra computations place more load on the target system and can alter the
7195 characteristics of the program being debugged.
7196 </para>
7197
7198 <para>
7199 To help get past the previously mentioned constraints, you can use Gdbserver.
7200 Gdbserver runs on the remote target and does not load any debugging information
7201 from the debugged process.
7202 Instead, a GDB instance processes the debugging information that is run on a
7203 remote computer - the host GDB.
7204 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
7205 program, as well as read or write memory regions of that debugged program.
7206 All the debugging information loaded and processed as well
7207 as all the heavy debugging is done by the host GDB.
7208 Offloading these processes gives the Gdbserver running on the target a chance to remain
7209 small and fast.
7210 </para>
7211
7212 <para>
7213 Because the host GDB is responsible for loading the debugging information and
7214 for doing the necessary processing to make actual debugging happen, the
7215 user has to make sure the host can access the unstripped binaries complete
7216 with their debugging information and also be sure the target is compiled with no optimizations.
7217 The host GDB must also have local access to all the libraries used by the
7218 debugged program.
7219 Because Gdbserver does not need any local debugging information, the binaries on
7220 the remote target can remain stripped.
7221 However, the binaries must also be compiled without optimization
7222 so they match the host's binaries.
7223 </para>
7224
7225 <para>
7226 To remain consistent with GDB documentation and terminology, the binary being debugged
7227 on the remote target machine is referred to as the "inferior" binary.
7228 For documentation on GDB see the
7229 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
7230 </para>
7231
7232 <para>
7233 The remainder of this section describes the steps you need to take
7234 to debug using the GNU project debugger.
7235 </para>
7236
7237 <section id='platdev-gdb-remotedebug-setup'>
7238 <title>Set Up the Cross-Development Debugging Environment</title>
7239
7240 <para>
7241 Before you can initiate a remote debugging session, you need
7242 to be sure you have set up the cross-development environment,
7243 toolchain, and sysroot.
7244 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
7245 chapter of the Yocto Project Application Developer's Guide
7246 describes this process.
7247 Be sure you have read that chapter and have set up
7248 your environment.
7249 </para>
7250 </section>
7251
7252 <section id="platdev-gdb-remotedebug-launch-gdbserver">
7253 <title>Launch Gdbserver on the Target</title>
7254
7255 <para>
7256 Make sure Gdbserver is installed on the target.
7257 If it is not, install the package
7258 <filename>gdbserver</filename>, which needs the
7259 <filename>libthread-db1</filename> package.
7260 </para>
7261
7262 <para>
7263 Here is an example that when entered from the host
7264 connects to the target and launches Gdbserver in order to
7265 "debug" a binary named <filename>helloworld</filename>:
7266 <literallayout class='monospaced'>
7267 $ gdbserver localhost:2345 /usr/bin/helloworld
7268 </literallayout>
7269 Gdbserver should now be listening on port 2345 for debugging
7270 commands coming from a remote GDB process that is running on
7271 the host computer.
7272 Communication between Gdbserver and the host GDB are done
7273 using TCP.
7274 To use other communication protocols, please refer to the
7275 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
7276 </para>
7277 </section>
7278
7279 <section id="platdev-gdb-remotedebug-launch-gdb">
7280 <title>Launch GDB on the Host Computer</title>
7281
7282 <para>
7283 Running GDB on the host computer takes a number of stages, which
7284 this section describes.
7285 </para>
7286
7287 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
7288 <title>Build the Cross-GDB Package</title>
7289 <para>
7290 A suitable GDB cross-binary is required that runs on your
7291 host computer but also knows about the the ABI of the
7292 remote target.
7293 You can get this binary from the
7294 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
7295 Here is an example where the toolchain has been installed
7296 in the default directory
7297 <filename>/opt/poky/&DISTRO;</filename>:
7298 <literallayout class='monospaced'>
7299 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
7300 </literallayout>
7301 where <filename>arm</filename> is the target architecture
7302 and <filename>linux-gnueabi</filename> is the target ABI.
7303 </para>
7304
7305 <para>
7306 Alternatively, you can use BitBake to build the
7307 <filename>gdb-cross</filename> binary.
7308 Here is an example:
7309 <literallayout class='monospaced'>
7310 $ bitbake gdb-cross
7311 </literallayout>
7312 Once the binary is built, you can find it here:
7313 <literallayout class='monospaced'>
7314 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
7315 </literallayout>
7316 </para>
7317 </section>
7318
7319 <section id='create-the-gdb-initialization-file'>
7320 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
7321
7322 <para>
7323 Aside from the GDB cross-binary, you also need a GDB
7324 initialization file in the same top directory in which
7325 your binary resides.
7326 When you start GDB on your host development system, GDB
7327 finds this initialization file and executes all the
7328 commands within.
7329 For information on the <filename>.gdbinit</filename>, see
7330 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
7331 which is maintained by
7332 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
7333 </para>
7334
7335 <para>
7336 You need to add a statement in the
7337 <filename>.gdbinit</filename> file that points to your
7338 root filesystem.
7339 Here is an example that points to the root filesystem for
7340 an ARM-based target device:
7341 <literallayout class='monospaced'>
7342 set sysroot /home/jzhang/sysroot_arm
7343 </literallayout>
7344 </para>
7345 </section>
7346
7347 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
7348 <title>Launch the Host GDB</title>
7349
7350 <para>
7351 Before launching the host GDB, you need to be sure
7352 you have sourced the cross-debugging environment script,
7353 which if you installed the root filesystem in the default
7354 location is at <filename>/opt/poky/&DISTRO;</filename>
7355 and begins with the string "environment-setup".
7356 For more information, see the
7357 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
7358 section in the Yocto Project Application Developer's
7359 Guide.
7360 </para>
7361
7362 <para>
7363 Finally, switch to the directory where the binary resides
7364 and run the <filename>cross-gdb</filename> binary.
7365 Provide the binary file you are going to debug.
7366 For example, the following command continues with the
7367 example used in the previous section by loading
7368 the <filename>helloworld</filename> binary as well as the
7369 debugging information:
7370 <literallayout class='monospaced'>
7371 $ arm-poky-linux-gnuabi-gdb helloworld
7372 </literallayout>
7373 The commands in your <filename>.gdbinit</filename> execute
7374 and the GDB prompt appears.
7375 </para>
7376 </section>
7377 </section>
7378
7379 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
7380 <title>Connect to the Remote GDB Server</title>
7381
7382 <para>
7383 From the target, you need to connect to the remote GDB
7384 server that is running on the host.
7385 You need to specify the remote host and port.
7386 Here is the command continuing with the example:
7387 <literallayout class='monospaced'>
7388 target remote 192.168.7.2:2345
7389 </literallayout>
7390 </para>
7391 </section>
7392
7393 <section id="platdev-gdb-remotedebug-launch-gdb-using">
7394 <title>Use the Debugger</title>
7395
7396 <para>
7397 You can now proceed with debugging as normal - as if you were debugging
7398 on the local machine.
7399 For example, to instruct GDB to break in the "main" function and then
7400 continue with execution of the inferior binary use the following commands
7401 from within GDB:
7402 <literallayout class='monospaced'>
7403 (gdb) break main
7404 (gdb) continue
7405 </literallayout>
7406 </para>
7407
7408 <para>
7409 For more information about using GDB, see the project's online documentation at
7410 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
7411 </para>
7412 </section>
7413 </section>
7414
7415 <section id='debugging-parallel-make-races'>
7416 <title>Debugging Parallel Make Races</title>
7417
7418 <para>
7419 A parallel <filename>make</filename> race occurs when the build
7420 consists of several parts that are run simultaneously and
7421 a situation occurs when the output or result of one
7422 part is not ready for use with a different part of the build that
7423 depends on that output.
7424 Parallel make races are annoying and can sometimes be difficult
7425 to reproduce and fix.
7426 However, some simple tips and tricks exist that can help
7427 you debug and fix them.
7428 This section presents a real-world example of an error encountered
7429 on the Yocto Project autobuilder and the process used to fix it.
7430 </para>
7431
7432 <section id='the-failure'>
7433 <title>The Failure</title>
7434
7435 <para>
7436 For this example, assume that you are building an image that
7437 depends on the "neard" package.
7438 And, during the build, BitBake runs into problems and
7439 creates the following output.
7440 <note>
7441 This example log file has longer lines artificially
7442 broken to make the listing easier to read.
7443 </note>
7444 If you examine the output or the log file, you see the
7445 failure during <filename>make</filename>:
7446 <literallayout class='monospaced'>
7447 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
7448 | DEBUG: Executing shell function do_compile
7449 | NOTE: make -j 16
7450 | make --no-print-directory all-am
7451 | /bin/mkdir -p include/near
7452 | /bin/mkdir -p include/near
7453 | /bin/mkdir -p include/near
7454 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7455 0.14-r0/neard-0.14/include/types.h include/near/types.h
7456 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7457 0.14-r0/neard-0.14/include/log.h include/near/log.h
7458 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7459 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h
7460 | /bin/mkdir -p include/near
7461 | /bin/mkdir -p include/near
7462 | /bin/mkdir -p include/near
7463 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7464 0.14-r0/neard-0.14/include/tag.h include/near/tag.h
7465 | /bin/mkdir -p include/near
7466 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7467 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h
7468 | /bin/mkdir -p include/near
7469 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7470 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h
7471 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7472 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h
7473 | /bin/mkdir -p include/near
7474 | /bin/mkdir -p include/near
7475 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7476 0.14-r0/neard-0.14/include/setting.h include/near/setting.h
7477 | /bin/mkdir -p include/near
7478 | /bin/mkdir -p include/near
7479 | /bin/mkdir -p include/near
7480 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7481 0.14-r0/neard-0.14/include/device.h include/near/device.h
7482 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7483 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h
7484 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7485 0.14-r0/neard-0.14/include/snep.h include/near/snep.h
7486 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7487 0.14-r0/neard-0.14/include/version.h include/near/version.h
7488 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
7489 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h
7490 | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h
7491 | i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/
7492 build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/
7493 yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0
7494 -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/
7495 lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/
7496 tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/
7497 nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/
7498 yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3
7499 -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\"
7500 -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c
7501 -o tools/snep-send.o tools/snep-send.c
7502 | In file included from tools/snep-send.c:16:0:
7503 | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
7504 | #include &lt;near/dbus.h&gt;
7505 | ^
7506 | compilation terminated.
7507 | make[1]: *** [tools/snep-send.o] Error 1
7508 | make[1]: *** Waiting for unfinished jobs....
7509 | make: *** [all] Error 2
7510 | ERROR: oe_runmake failed
7511 </literallayout>
7512 </para>
7513 </section>
7514
7515 <section id='reproducing-the-error'>
7516 <title>Reproducing the Error</title>
7517
7518 <para>
7519 Because race conditions are intermittent, they do not
7520 manifest themselves every time you do the build.
7521 In fact, most times the build will complete without problems
7522 even though the potential race condition exists.
7523 Thus, once the error surfaces, you need a way to reproduce it.
7524 </para>
7525
7526 <para>
7527 In this example, compiling the "neard" package is causing the
7528 problem.
7529 So the first thing to do is build "neard" locally.
7530 Before you start the build, set the
7531 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
7532 variable in your <filename>local.conf</filename> file to
7533 a high number (e.g. "-j 20").
7534 Using a high value for <filename>PARALLEL_MAKE</filename>
7535 increases the chances of the race condition showing up:
7536 <literallayout class='monospaced'>
7537 $ bitbake neard
7538 </literallayout>
7539 </para>
7540
7541 <para>
7542 Once the local build for "neard" completes, start a
7543 <filename>devshell</filename> build:
7544 <literallayout class='monospaced'>
7545 $ bitbake neard -c devshell
7546 </literallayout>
7547 For information on how to use a
7548 <filename>devshell</filename>, see the
7549 "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
7550 section.
7551 </para>
7552
7553 <para>
7554 In the <filename>devshell</filename>, do the following:
7555 <literallayout class='monospaced'>
7556 $ make clean
7557 $ make tools/snep-send.o
7558 </literallayout>
7559 The <filename>devshell</filename> commands cause the failure
7560 to clearly be visible.
7561 In this case, a missing dependency exists for the "neard"
7562 Makefile target.
7563 Here is some abbreviated, sample output with the
7564 missing dependency clearly visible at the end:
7565 <literallayout class='monospaced'>
7566 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
7567 .
7568 .
7569 .
7570 tools/snep-send.c
7571 In file included from tools/snep-send.c:16:0:
7572 tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
7573 #include &lt;near/dbus.h&gt;
7574 ^
7575 compilation terminated.
7576 make: *** [tools/snep-send.o] Error 1
7577 $
7578 </literallayout>
7579 </para>
7580 </section>
7581
7582 <section id='creating-a-patch-for-the-fix'>
7583 <title>Creating a Patch for the Fix</title>
7584
7585 <para>
7586 Because there is a missing dependency for the Makefile
7587 target, you need to patch the
7588 <filename>Makefile.am</filename> file, which is generated
7589 from <filename>Makefile.in</filename>.
7590 You can use Quilt to create the patch:
7591 <literallayout class='monospaced'>
7592 $ quilt new parallelmake.patch
7593 Patch patches/parallelmake.patch is now on top
7594 $ quilt add Makefile.am
7595 File Makefile.am added to patch patches/parallelmake.patch
7596 </literallayout>
7597 For more information on using Quilt, see the
7598 "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>"
7599 section.
7600 </para>
7601
7602 <para>
7603 At this point you need to make the edits to
7604 <filename>Makefile.am</filename> to add the missing
7605 dependency.
7606 For our example, you have to add the following line
7607 to the file:
7608 <literallayout class='monospaced'>
7609 tools/snep-send.$(OBJEXT): include/near/dbus.h
7610 </literallayout>
7611 </para>
7612
7613 <para>
7614 Once you have edited the file, use the
7615 <filename>refresh</filename> command to create the patch:
7616 <literallayout class='monospaced'>
7617 $ quilt refresh
7618 Refreshed patch patches/parallelmake.patch
7619 </literallayout>
7620 Once the patch file exists, you need to add it back to the
7621 originating recipe folder.
7622 Here is an example assuming a top-level
7623 <link linkend='source-directory'>Source Directory</link>
7624 named <filename>poky</filename>:
7625 <literallayout class='monospaced'>
7626 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
7627 </literallayout>
7628 The final thing you need to do to implement the fix in the
7629 build is to update the "neard" recipe (i.e.
7630 <filename>neard-0.14.bb</filename> so that the
7631 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7632 statement includes the patch file.
7633 The recipe file is in the folder above the patch.
7634 Here is what the edited <filename>SRC_URI</filename>
7635 statement would look like:
7636 <literallayout class='monospaced'>
7637 SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
7638 file://neard.in \
7639 file://neard.service.in \
7640 file://parallelmake.patch \
7641 "
7642 </literallayout>
7643 </para>
7644
7645 <para>
7646 With the patch complete and moved to the correct folder and
7647 the <filename>SRC_URI</filename> statement updated, you can
7648 exit the <filename>devshell</filename>:
7649 <literallayout class='monospaced'>
7650 $ exit
7651 </literallayout>
7652 </para>
7653 </section>
7654
7655 <section id='testing-the-build'>
7656 <title>Testing the Build</title>
7657
7658 <para>
7659 With everything in place, you can get back to trying the
7660 build again locally:
7661 <literallayout class='monospaced'>
7662 $ bitbake neard
7663 </literallayout>
7664 This build should succeed.
7665 </para>
7666
7667 <para>
7668 Now you can open up a <filename>devshell</filename> again
7669 and repeat the clean and make operations as follows:
7670 <literallayout class='monospaced'>
7671 $ bitbake neard -c devshell
7672 $ make clean
7673 $ make tools/snep-send.o
7674 </literallayout>
7675 The build should work without issue.
7676 </para>
7677
7678 <para>
7679 As with all solved problems, if they originated upstream, you
7680 need to submit the fix for the recipe in OE-Core and upstream
7681 so that the problem is taken care of at its source.
7682 See the
7683 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
7684 section for more information.
7685 </para>
7686 </section>
7687 </section>
7688
7689 <section id="examining-builds-using-toaster">
7690 <title>Examining Builds Using the Toaster API</title>
7691
7692 <para>
7693 Toaster is an Application Programming Interface (API) and
7694 web-based interface to the OpenEmbedded build system, which uses
7695 BitBake.
7696 Both interfaces are based on a Representational State Transfer
7697 (REST) API that queries for and returns build information using
7698 <filename>GET</filename> and <filename>JSON</filename>.
7699 These types of search operations retrieve sets of objects from
7700 a datastore used to collect build information.
7701 The results contain all the data for the objects being returned.
7702 You can order the results of the search by key and the search
7703 parameters are consistent for all object types.
7704 </para>
7705
7706 <para>
7707 Using the interfaces you can do the following:
7708 <itemizedlist>
7709 <listitem><para>See information about the tasks executed
7710 and reused during the build.</para></listitem>
7711 <listitem><para>See what is built (recipes and
7712 packages) and what packages were installed into the final
7713 image.</para></listitem>
7714 <listitem><para>See performance-related information such
7715 as build time, CPU usage, and disk I/O.</para></listitem>
7716 <listitem><para>Examine error, warning and trace messages
7717 to aid in debugging.</para></listitem>
7718 </itemizedlist>
7719 </para>
7720
7721 <note>
7722 <para>This release of Toaster provides you with information
7723 about a BitBake run.
7724 The tool does not allow you to configure and launch a build.
7725 However, future development includes plans to integrate the
7726 configuration and build launching capabilities of
7727 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
7728 </para>
7729 <para>For more information on using Hob to build an image,
7730 see the
7731 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
7732 section.</para>
7733 </note>
7734
7735 <para>
7736 The remainder of this section describes what you need to have in
7737 place to use Toaster, how to start it, use it, and stop it.
7738 For additional information on installing and running Toaster, see the
7739 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
7740 section of the "Toaster" wiki page.
7741 For complete information on the API and its search operation
7742 URI, parameters, and responses, see the
7743 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
7744 Wiki page.
7745 </para>
7746
7747 <section id='starting-toaster'>
7748 <title>Starting Toaster</title>
7749
7750 <para>
7751 Getting set up to use and start Toaster is simple.
7752 First, be sure you have met the following requirements:
7753 <itemizedlist>
7754 <listitem><para>You have set up your
7755 <link linkend='source-directory'>Source Directory</link>
7756 by cloning the upstream <filename>poky</filename>
7757 repository.
7758 See the
7759 <link linkend='local-yp-release'>Yocto Project Release</link>
7760 item for information on how to set up the Source
7761 Directory.</para></listitem>
7762 <listitem><para>Be sure your build machine has
7763 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
7764 version 1.5 installed.</para></listitem>
7765 <listitem><para>Make sure that port 8000 and 8200 are
7766 free (i.e. they have no servers on them).
7767 </para></listitem>
7768 </itemizedlist>
7769 </para>
7770
7771 <para>
7772 Once you have met the requirements, follow these steps to
7773 start Toaster running in the background of your shell:
7774 <orderedlist>
7775 <listitem><para><emphasis>Set up your build environment:</emphasis>
7776 Source a build environment script (i.e.
7777 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
7778 or
7779 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
7780 </para></listitem>
7781 <listitem><para><emphasis>Start Toaster:</emphasis>
7782 Start the Toaster service using this
7783 command from within your
7784 <link linkend='build-directory'>Build Directory</link>:
7785 <literallayout class='monospaced'>
7786 $ source toaster start
7787 </literallayout></para></listitem>
7788 <note>
7789 The Toaster must be started and running in order
7790 for it to collect data.
7791 </note>
7792 </orderedlist>
7793 </para>
7794
7795 <para>
7796 When Toaster starts, it creates some additional files in your
7797 Build Directory.
7798 Deleting these files will cause you to lose data or interrupt
7799 Toaster:
7800 <itemizedlist>
7801 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
7802 Toaster's database file.</para></listitem>
7803 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
7804 The log file of the web server.</para></listitem>
7805 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
7806 The log file of the user interface component.
7807 </para></listitem>
7808 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
7809 The PID of the web server.</para></listitem>
7810 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
7811 The PID of the DSI data bridge.</para></listitem>
7812 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
7813 The BitBake server's log file.</para></listitem>
7814 </itemizedlist>
7815 </para>
7816 </section>
7817
7818 <section id='using-toaster'>
7819 <title>Using Toaster</title>
7820
7821 <para>
7822 Once Toaster is running, it logs information for any BitBake
7823 run from your Build Directory.
7824 This logging is automatic.
7825 All you need to do is access and use the information.
7826 </para>
7827
7828 <para>
7829 You access the information one of two ways:
7830 <itemizedlist>
7831 <listitem><para>Open a Browser and enter
7832 <filename>http://localhost:8000</filename>
7833 for the URL.
7834 </para></listitem>
7835 <listitem><para>Use the <filename>xdg-open</filename>
7836 tool from the shell and pass it the same URL.
7837 </para></listitem>
7838 </itemizedlist>
7839 Either method opens the home page for the Toaster interface.
7840 </para>
7841
7842 <note><title>Notes</title>
7843 <para>
7844 For information on how to delete information from the Toaster
7845 database, see the
7846 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
7847 wiki page.
7848 </para>
7849
7850 <para>
7851 For information on how to set up an instance of Toaster on
7852 a remote host, see the
7853 <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>
7854 wiki page.
7855 </para>
7856 </note>
7857 </section>
7858
7859 <section id='examining-toaster-data'>
7860 <title>Examining Toaster Data</title>
7861
7862 <para>
7863 The Toaster database is persistent regardless of whether you
7864 start or stop the service.
7865 </para>
7866
7867 <para>
7868 Toaster's interface shows you a list of builds
7869 (successful and unsuccessful) for which it has data.
7870 You can click on any build to see related information.
7871 This information includes configuration details, information
7872 about tasks, all recipes and packages built and their
7873 dependencies, packages and their directory structure as
7874 installed in your final image,
7875 execution time, CPU usage and disk I/O per task.
7876 </para>
7877
7878 <para>
7879 For details on the interface, see the
7880 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
7881 </para>
7882 </section>
7883
7884 <section id='stopping-toaster'>
7885 <title>Stopping Toaster</title>
7886
7887 <para>
7888 Stop the Toaster service with the following command
7889 from with the
7890 <link linkend='build-directory'>Build Directory</link>:
7891 <literallayout class='monospaced'>
7892 $ source toaster stop
7893 </literallayout>
7894 The service stops but the Toaster database remains persistent.
7895 </para>
7896 </section>
7897 </section>
7898
7899 <section id="platdev-oprofile">
7900 <title>Profiling with OProfile</title>
7901
7902 <para>
7903 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
7904 statistical profiler well suited for finding performance
7905 bottlenecks in both user-space software and in the kernel.
7906 This profiler provides answers to questions like "Which functions does my application spend
7907 the most time in when doing X?"
7908 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
7909 applications on target hardware straight forward.
7910 <note>
7911 For more information on how to set up and run OProfile, see the
7912 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
7913 section in the Yocto Project Profiling and Tracing Manual.
7914 </note>
7915 </para>
7916
7917 <para>
7918 To use OProfile, you need an image that has OProfile installed.
7919 The easiest way to do this is with "tools-profile" in the
7920 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
7921 You also need debugging symbols to be available on the system where the analysis
7922 takes place.
7923 You can gain access to the symbols by using "dbg-pkgs" in the
7924 <filename>IMAGE_FEATURES</filename> variable or by
7925 installing the appropriate DBG (<filename>-dbg</filename>) packages.
7926 </para>
7927
7928 <para>
7929 For successful call graph analysis, the binaries must preserve the frame
7930 pointer register and should also be compiled with the
7931 <filename>-fno-omit-framepointer</filename> flag.
7932 You can achieve this by setting the
7933 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
7934 variable with the following options:
7935 <literallayout class='monospaced'>
7936 -fexpensive-optimizations
7937 -fno-omit-framepointer
7938 -frename-registers
7939 -O2
7940 </literallayout>
7941 You can also achieve it by setting the
7942 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
7943 variable to "1" in the <filename>local.conf</filename> configuration file.
7944 If you use the <filename>DEBUG_BUILD</filename> variable,
7945 you also add extra debugging information that can make the debug
7946 packages large.
7947 </para>
7948
7949 <section id="platdev-oprofile-target">
7950 <title>Profiling on the Target</title>
7951
7952 <para>
7953 Using OProfile, you can perform all the profiling work on the target device.
7954 A simple OProfile session might look like the following:
7955 </para>
7956
7957 <para>
7958 <literallayout class='monospaced'>
7959 # opcontrol --reset
7960 # opcontrol --start --separate=lib --no-vmlinux -c 5
7961 .
7962 .
7963 [do whatever is being profiled]
7964 .
7965 .
7966 # opcontrol --stop
7967 $ opreport -cl
7968 </literallayout>
7969 </para>
7970
7971 <para>
7972 In this example, the <filename>reset</filename> command clears any previously profiled data.
7973 The next command starts OProfile.
7974 The options used when starting the profiler separate dynamic library data
7975 within applications, disable kernel profiling, and enable callgraphing up to
7976 five levels deep.
7977 <note>
7978 To profile the kernel, you would specify the
7979 <filename>--vmlinux=/path/to/vmlinux</filename> option.
7980 The <filename>vmlinux</filename> file is usually in the source directory in the
7981 <filename>/boot/</filename> directory and must match the running kernel.
7982 </note>
7983 </para>
7984
7985 <para>
7986 After you perform your profiling tasks, the next command stops the profiler.
7987 After that, you can view results with the <filename>opreport</filename> command with options
7988 to see the separate library symbols and callgraph information.
7989 </para>
7990
7991 <para>
7992 Callgraphing logs information about time spent in functions and about a function's
7993 calling function (parent) and called functions (children).
7994 The higher the callgraphing depth, the more accurate the results.
7995 However, higher depths also increase the logging overhead.
7996 Consequently, you should take care when setting the callgraphing depth.
7997 <note>
7998 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
7999 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
8000 with <filename>gcc</filename>.
8001 </note>
8002 </para>
8003
8004 <para>
8005 For more information on using OProfile, see the OProfile
8006 online documentation at
8007 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
8008 </para>
8009 </section>
8010
8011 <section id="platdev-oprofile-oprofileui">
8012 <title>Using OProfileUI</title>
8013
8014 <para>
8015 A graphical user interface for OProfile is also available.
8016 You can download and build this interface from the Yocto Project at
8017 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
8018 If the "tools-profile" image feature is selected, all necessary binaries
8019 are installed onto the target device for OProfileUI interaction.
8020 For a list of image features that ship with the Yocto Project,
8021 see the
8022 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
8023 section in the Yocto Project Reference Manual.
8024 </para>
8025
8026 <para>
8027 Even though the source directory usually includes all needed patches on the target device, you
8028 might find you need other OProfile patches for recent OProfileUI features.
8029 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
8030 OProfileUI README</ulink> for the most recent information.
8031 </para>
8032
8033 <section id="platdev-oprofile-oprofileui-online">
8034 <title>Online Mode</title>
8035
8036 <para>
8037 Using OProfile in online mode assumes a working network connection with the target
8038 hardware.
8039 With this connection, you just need to run "oprofile-server" on the device.
8040 By default, OProfile listens on port 4224.
8041 <note>
8042 You can change the port using the <filename>--port</filename> command-line
8043 option.
8044 </note>
8045 </para>
8046
8047 <para>
8048 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
8049 straight forward.
8050 You access key functionality through the buttons on the toolbar, which
8051 are duplicated in the menus.
8052 Here are the buttons:
8053 <itemizedlist>
8054 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
8055 You can also supply the IP address or hostname.</para></listitem>
8056 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
8057 </para></listitem>
8058 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
8059 </para></listitem>
8060 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
8061 downloads the data to the local host.
8062 Stopping the profiler generates the profile and displays it in the viewer.
8063 </para></listitem>
8064 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
8065 target and generates the profile, which appears in the viewer.</para></listitem>
8066 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
8067 Resetting the data removes sample information collected from previous
8068 sampling runs.
8069 Be sure you reset the data if you do not want to include old sample information.
8070 </para></listitem>
8071 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
8072 target to another directory for later examination.</para></listitem>
8073 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
8074 </para></listitem>
8075 </itemizedlist>
8076 </para>
8077
8078 <para>
8079 The client downloads the complete profile archive from
8080 the target to the host for processing.
8081 This archive is a directory that contains the sample data, the object files,
8082 and the debug information for the object files.
8083 The archive is then converted using the <filename>oparchconv</filename> script, which is
8084 included in this distribution.
8085 The script uses <filename>opimport</filename> to convert the archive from
8086 the target to something that can be processed on the host.
8087 </para>
8088
8089 <para>
8090 Downloaded archives reside in the
8091 <link linkend='build-directory'>Build Directory</link> in
8092 <filename>tmp</filename> and are cleared up when they are no longer in use.
8093 </para>
8094
8095 <para>
8096 If you wish to perform kernel profiling, you need to be sure
8097 a <filename>vmlinux</filename> file that matches the running kernel is available.
8098 In the source directory, that file is usually located in
8099 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
8100 <filename>KERNEL-version</filename> is the version of the kernel.
8101 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
8102 packages for each kernel it builds.
8103 Thus, it should just be a question of making sure a matching package is
8104 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
8105 The files are automatically installed into development and profiling images
8106 alongside OProfile.
8107 A configuration option exists within the OProfileUI settings page that you can use to
8108 enter the location of the <filename>vmlinux</filename> file.
8109 </para>
8110
8111 <para>
8112 Waiting for debug symbols to transfer from the device can be slow, and it
8113 is not always necessary to actually have them on the device for OProfile use.
8114 All that is needed is a copy of the filesystem with the debug symbols present
8115 on the viewer system.
8116 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
8117 section covers how to create such a directory within
8118 the source directory and how to use the OProfileUI Settings
8119 Dialog to specify the location.
8120 If you specify the directory, it will be used when the file checksums
8121 match those on the system you are profiling.
8122 </para>
8123 </section>
8124
8125 <section id="platdev-oprofile-oprofileui-offline">
8126 <title>Offline Mode</title>
8127
8128 <para>
8129 If network access to the target is unavailable, you can generate
8130 an archive for processing in <filename>oprofile-viewer</filename> as follows:
8131 <literallayout class='monospaced'>
8132 # opcontrol --reset
8133 # opcontrol --start --separate=lib --no-vmlinux -c 5
8134 .
8135 .
8136 [do whatever is being profiled]
8137 .
8138 .
8139 # opcontrol --stop
8140 # oparchive -o my_archive
8141 </literallayout>
8142 </para>
8143
8144 <para>
8145 In the above example, <filename>my_archive</filename> is the name of the
8146 archive directory where you would like the profile archive to be kept.
8147 After the directory is created, you can copy it to another host and load it
8148 using <filename>oprofile-viewer</filename> open functionality.
8149 If necessary, the archive is converted.
8150 </para>
8151 </section>
8152 </section>
8153 </section>
8154
8155 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
8156 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
8157
8158 <para>
8159 One of the concerns for a development organization using open source
8160 software is how to maintain compliance with various open source
8161 licensing during the lifecycle of the product.
8162 While this section does not provide legal advice or
8163 comprehensively cover all scenarios, it does
8164 present methods that you can use to
8165 assist you in meeting the compliance requirements during a software
8166 release.
8167 </para>
8168
8169 <para>
8170 With hundreds of different open source licenses that the Yocto
8171 Project tracks, it is difficult to know the requirements of each
8172 and every license.
8173 However, the requirements of the major FLOSS licenses can begin
8174 to be covered by
8175 assuming that three main areas of concern exist:
8176 <itemizedlist>
8177 <listitem><para>Source code must be provided.</para></listitem>
8178 <listitem><para>License text for the software must be
8179 provided.</para></listitem>
8180 <listitem><para>Compilation scripts and modifications to the
8181 source code must be provided.
8182 </para></listitem>
8183 </itemizedlist>
8184 There are other requirements beyond the scope of these
8185 three and the methods described in this section
8186 (e.g. the mechanism through which source code is distributed).
8187 </para>
8188
8189 <para>
8190 As different organizations have different methods of complying with
8191 open source licensing, this section is not meant to imply that
8192 there is only one single way to meet your compliance obligations,
8193 but rather to describe one method of achieving compliance.
8194 The remainder of this section describes methods supported to meet the
8195 previously mentioned three requirements.
8196 Once you take steps to meet these requirements,
8197 and prior to releasing images, sources, and the build system,
8198 you should audit all artifacts to ensure completeness.
8199 <note>
8200 The Yocto Project generates a license manifest during
8201 image creation that is located
8202 in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
8203 to assist with any audits.
8204 </note>
8205 </para>
8206
8207 <section id='providing-the-source-code'>
8208 <title>Providing the Source Code</title>
8209
8210 <para>
8211 Compliance activities should begin before you generate the
8212 final image.
8213 The first thing you should look at is the requirement that
8214 tops the list for most compliance groups - providing
8215 the source.
8216 The Yocto Project has a few ways of meeting this
8217 requirement.
8218 </para>
8219
8220 <para>
8221 One of the easiest ways to meet this requirement is
8222 to provide the entire
8223 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
8224 used by the build.
8225 This method, however, has a few issues.
8226 The most obvious is the size of the directory since it includes
8227 all sources used in the build and not just the source used in
8228 the released image.
8229 It will include toolchain source, and other artifacts, which
8230 you would not generally release.
8231 However, the more serious issue for most companies is accidental
8232 release of proprietary software.
8233 The Yocto Project provides an
8234 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
8235 class to help avoid some of these concerns.
8236 </para>
8237
8238 <para>
8239 Before you employ <filename>DL_DIR</filename> or the
8240 archiver class, you need to decide how you choose to
8241 provide source.
8242 The source archiver class can generate tarballs and SRPMs
8243 and can create them with various levels of compliance in mind.
8244 </para>
8245
8246 <para>
8247 One way of doing this (but certainly not the only way) is to
8248 release just the source as a tarball.
8249 You can do this by adding the following to the
8250 <filename>local.conf</filename> file found in the
8251 <link linkend='build-directory'>Build Directory</link>:
8252 <literallayout class='monospaced'>
8253 INHERIT += "archiver"
8254 ARCHIVER_MODE[src] = "original"
8255 </literallayout>
8256 During the creation of your image, the source from all
8257 recipes that deploy packages to the image is placed within
8258 subdirectories of
8259 <filename>DEPLOY_DIR/sources</filename> based on the
8260 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
8261 for each recipe.
8262 Releasing the entire directory enables you to comply with
8263 requirements concerning providing the unmodified source.
8264 It is important to note that the size of the directory can
8265 get large.
8266 </para>
8267
8268 <para>
8269 A way to help mitigate the size issue is to only release
8270 tarballs for licenses that require the release of
8271 source.
8272 Let us assume you are only concerned with GPL code as
8273 identified with the following:
8274 <literallayout class='monospaced'>
8275 $ cd poky/build/tmp/deploy/sources
8276 $ mkdir ~/gpl_source_release
8277 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
8278 </literallayout>
8279 At this point, you could create a tarball from the
8280 <filename>gpl_source_release</filename> directory and
8281 provide that to the end user.
8282 This method would be a step toward achieving compliance
8283 with section 3a of GPLv2 and with section 6 of GPLv3.
8284 </para>
8285 </section>
8286
8287 <section id='providing-license-text'>
8288 <title>Providing License Text</title>
8289
8290 <para>
8291 One requirement that is often overlooked is inclusion
8292 of license text.
8293 This requirement also needs to be dealt with prior to
8294 generating the final image.
8295 Some licenses require the license text to accompany
8296 the binary.
8297 You can achieve this by adding the following to your
8298 <filename>local.conf</filename> file:
8299 <literallayout class='monospaced'>
8300 COPY_LIC_MANIFEST = "1"
8301 COPY_LIC_DIRS = "1"
8302 </literallayout>
8303 Adding these statements to the configuration file ensures
8304 that the licenses collected during package generation
8305 are included on your image.
8306 As the source archiver has already archived the original
8307 unmodified source that contains the license files,
8308 you would have already met the requirements for inclusion
8309 of the license information with source as defined by the GPL
8310 and other open source licenses.
8311 </para>
8312 </section>
8313
8314 <section id='providing-compilation-scripts-and-source-code-modifications'>
8315 <title>Providing Compilation Scripts and Source Code Modifications</title>
8316
8317 <para>
8318 At this point, we have addressed all we need to address
8319 prior to generating the image.
8320 The next two requirements are addressed during the final
8321 packaging of the release.
8322 </para>
8323
8324 <para>
8325 By releasing the version of the OpenEmbedded build system
8326 and the layers used during the build, you will be providing both
8327 compilation scripts and the source code modifications in one
8328 step.
8329 </para>
8330
8331 <para>
8332 If the deployment team has a
8333 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
8334 and a distro layer, and those those layers are used to patch,
8335 compile, package, or modify (in any way) any open source
8336 software included in your released images, you
8337 might be required to to release those layers under section 3 of
8338 GPLv2 or section 1 of GPLv3.
8339 One way of doing that is with a clean
8340 checkout of the version of the Yocto Project and layers used
8341 during your build.
8342 Here is an example:
8343 <literallayout class='monospaced'>
8344 # We built using the &DISTRO_NAME; branch of the poky repo
8345 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
8346 $ cd poky
8347 # We built using the release_branch for our layers
8348 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
8349 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
8350 # clean up the .git repos
8351 $ find . -name ".git" -type d -exec rm -rf {} \;
8352 </literallayout>
8353 One thing a development organization might want to consider
8354 for end-user convenience is to modify
8355 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
8356 ensure that when the end user utilizes the released build
8357 system to build an image, the development organization's
8358 layers are included in the <filename>bblayers.conf</filename>
8359 file automatically:
8360 <literallayout class='monospaced'>
8361 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
8362 # changes incompatibly
8363 LCONF_VERSION = "6"
8364
8365 BBPATH = "${TOPDIR}"
8366 BBFILES ?= ""
8367
8368 BBLAYERS ?= " \
8369 ##OEROOT##/meta \
8370 ##OEROOT##/meta-yocto \
8371 ##OEROOT##/meta-yocto-bsp \
8372 ##OEROOT##/meta-mylayer \
8373 "
8374
8375 BBLAYERS_NON_REMOVABLE ?= " \
8376 ##OEROOT##/meta \
8377 ##OEROOT##/meta-yocto \
8378 "
8379 </literallayout>
8380 Creating and providing an archive of the
8381 <link linkend='metadata'>Metadata</link> layers
8382 (recipes, configuration files, and so forth)
8383 enables you to meet your
8384 requirements to include the scripts to control compilation
8385 as well as any modifications to the original source.
8386 </para>
8387 </section>
8388 </section>
8389
8390 <section id='using-the-error-reporting-tool'>
8391 <title>Using the Error Reporting Tool</title>
8392
8393 <para>
8394 The error reporting tool allows you to
8395 submit errors encountered during builds to a central database.
8396 Outside of the build environment, you can use a web interface to
8397 browse errors, view statistics, and query for errors.
8398 The tool works using a client-server system where the client
8399 portion is integrated with the installed Yocto Project
8400 <link linkend='source-directory'>Source Directory</link>
8401 (e.g. <filename>poky</filename>).
8402 The server receives the information collected and saves it in a
8403 database.
8404 </para>
8405
8406 <para>
8407 A live instance of the error reporting server exists at
8408 <ulink url='http://errors.yoctoproject.org'></ulink>.
8409 This server exists so that when you want to get help with
8410 build failures, you can submit all of the information on the
8411 failure easily and then point to the URL in your bug report
8412 or send an email to the mailing list.
8413 <note>
8414 If you send error reports to this server, the reports become
8415 publicly visible.
8416 </note>
8417 </para>
8418
8419 <section id='enabling-and-using-the-tool'>
8420 <title>Enabling and Using the Tool</title>
8421
8422 <para>
8423 By default, the error reporting tool is disabled.
8424 You can enable it by inheriting the
8425 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
8426 class by adding the following statement to the end of
8427 your <filename>local.conf</filename> file in your
8428 <link linkend='build-directory'>Build Directory</link>.
8429 <literallayout class='monospaced'>
8430 INHERIT += "report-error"
8431 </literallayout>
8432 </para>
8433
8434 <para>
8435 By default, the error reporting feature stores information in
8436 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
8437 However, you can specify a directory to use by adding the following
8438 to your <filename>local.conf</filename> file:
8439 <literallayout class='monospaced'>
8440 ERR_REPORT_DIR = "path"
8441 </literallayout>
8442 Enabling error reporting causes the build process to collect
8443 the errors and store them in a file as previously described.
8444 When the build system encounters an error, it includes a command
8445 as part of the console output.
8446 You can run the command to send the error file to the server.
8447 For example, the following command sends the errors to an upstream
8448 server:
8449 <literallayout class='monospaced'>
8450 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
8451 </literallayout>
8452 In the above example, the <filename>server</filename> parameter is
8453 optional.
8454 By default, the errors are sent to a database used by the entire
8455 community.
8456 If you specify a particular server, you can send them to a different
8457 database.
8458 </para>
8459
8460 <para>
8461 When sending the error file, you receive a link that corresponds
8462 to your entry in the database.
8463 For example, here is a typical link:
8464 <literallayout class='monospaced'>
8465 http://localhost:8000/Errors/Search/1/158
8466 </literallayout>
8467 Following the link takes you to a web interface where you can
8468 browse, query the errors, and view statistics.
8469 </para>
8470 </section>
8471
8472 <section id='disabling-the-tool'>
8473 <title>Disabling the Tool</title>
8474
8475 <para>
8476 To disable the error reporting feature, simply remove or comment
8477 out the following statement from the end of your
8478 <filename>local.conf</filename> file in your
8479 <link linkend='build-directory'>Build Directory</link>.
8480 <literallayout class='monospaced'>
8481 INHERIT += "report-error"
8482 </literallayout>
8483 </para>
8484 </section>
8485
8486 <section id='setting-up-your-own-error-reporting-server'>
8487 <title>Setting Up Your Own Error Reporting Server</title>
8488
8489 <para>
8490 If you want to set up your own error reporting server, you
8491 can obtain the code from the Git repository at
8492 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
8493 Instructions on how to set it up are in the README document.
8494 </para>
8495 </section>
8496 </section>
8497</chapter>
8498
8499<!--
8500vim: expandtab tw=80 ts=4
8501-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 07:17:08 +0000