summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorTudor Florea <tudor.florea@enea.com>2015-10-09 22:59:03 +0200
committerTudor Florea <tudor.florea@enea.com>2015-10-09 22:59:03 +0200
commit972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch)
tree97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /documentation/dev-manual/dev-manual-common-tasks.xml
downloadpoky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml9738
1 files changed, 9738 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 0000000000..64504299cc
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,9738 @@
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-selftest</filename>,
75 <filename>meta-yocto</filename>, and
76 <filename>meta-yocto-bsp</filename>.
77 Each of these folders represents a distinct layer.
78 </para>
79
80 <para>
81 As another example, if you set up a local copy of the
82 <filename>meta-intel</filename> Git repository
83 and then explore the folder of that general layer,
84 you will discover many Intel-specific BSP layers inside.
85 For more information on BSP layers, see the
86 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
87 section in the Yocto Project Board Support Package (BSP)
88 Developer's Guide.
89 </para>
90 </section>
91
92 <section id='creating-your-own-layer'>
93 <title>Creating Your Own Layer</title>
94
95 <para>
96 It is very easy to create your own layers to use with the
97 OpenEmbedded build system.
98 The Yocto Project ships with scripts that speed up creating
99 general layers and BSP layers.
100 This section describes the steps you perform by hand to create
101 a layer so that you can better understand them.
102 For information about the layer-creation scripts, see the
103 "<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>"
104 section in the Yocto Project Board Support Package (BSP)
105 Developer's Guide and the
106 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
107 section further down in this manual.
108 </para>
109
110 <para>
111 Follow these general steps to create your layer:
112 <orderedlist>
113 <listitem><para><emphasis>Check Existing Layers:</emphasis>
114 Before creating a new layer, you should be sure someone
115 has not already created a layer containing the Metadata
116 you need.
117 You can see the
118 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
119 for a list of layers from the OpenEmbedded community
120 that can be used in the Yocto Project.
121 </para></listitem>
122 <listitem><para><emphasis>Create a Directory:</emphasis>
123 Create the directory for your layer.
124 While not strictly required, prepend the name of the
125 folder with the string <filename>meta-</filename>.
126 For example:
127 <literallayout class='monospaced'>
128 meta-mylayer
129 meta-GUI_xyz
130 meta-mymachine
131 </literallayout>
132 </para></listitem>
133 <listitem><para><emphasis>Create a Layer Configuration
134 File:</emphasis>
135 Inside your new layer folder, you need to create a
136 <filename>conf/layer.conf</filename> file.
137 It is easiest to take an existing layer configuration
138 file and copy that to your layer's
139 <filename>conf</filename> directory and then modify the
140 file as needed.</para>
141 <para>The
142 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
143 demonstrates the required syntax:
144 <literallayout class='monospaced'>
145 # We have a conf and classes directory, add to BBPATH
146 BBPATH .= ":${LAYERDIR}"
147
148 # We have recipes-* directories, add to BBFILES
149 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
150 ${LAYERDIR}/recipes-*/*/*.bbappend"
151
152 BBFILE_COLLECTIONS += "yoctobsp"
153 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
154 BBFILE_PRIORITY_yoctobsp = "5"
155 LAYERVERSION_yoctobsp = "3"
156 </literallayout></para>
157 <para>Here is an explanation of the example:
158 <itemizedlist>
159 <listitem><para>The configuration and
160 classes directory is appended to
161 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
162 <note>
163 All non-distro layers, which include all BSP
164 layers, are expected to append the layer
165 directory to the
166 <filename>BBPATH</filename>.
167 On the other hand, distro layers, such as
168 <filename>meta-yocto</filename>, can choose
169 to enforce their own precedence over
170 <filename>BBPATH</filename>.
171 For an example of that syntax, see the
172 <filename>layer.conf</filename> file for
173 the <filename>meta-yocto</filename> layer.
174 </note></para></listitem>
175 <listitem><para>The recipes for the layers are
176 appended to
177 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
178 </para></listitem>
179 <listitem><para>The
180 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
181 variable is then appended with the layer name.
182 </para></listitem>
183 <listitem><para>The
184 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
185 variable is set to a regular expression and is
186 used to match files from
187 <filename>BBFILES</filename> into a particular
188 layer.
189 In this case,
190 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
191 is used to make <filename>BBFILE_PATTERN</filename> match within the
192 layer's path.</para></listitem>
193 <listitem><para>The
194 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
195 variable then assigns a priority to the layer.
196 Applying priorities is useful in situations
197 where the same recipe might appear in multiple
198 layers and allows you to choose the layer
199 that takes precedence.</para></listitem>
200 <listitem><para>The
201 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
202 variable optionally specifies the version of a
203 layer as a single number.</para></listitem>
204 </itemizedlist></para>
205 <para>Note the use of the
206 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
207 variable, which expands to the directory of the current
208 layer.</para>
209 <para>Through the use of the <filename>BBPATH</filename>
210 variable, BitBake locates class files
211 (<filename>.bbclass</filename>),
212 configuration files, and files that are included
213 with <filename>include</filename> and
214 <filename>require</filename> statements.
215 For these cases, BitBake uses the first file that
216 matches the name found in <filename>BBPATH</filename>.
217 This is similar to the way the <filename>PATH</filename>
218 variable is used for binaries.
219 It is recommended, therefore, that you use unique
220 class and configuration
221 filenames in your custom layer.</para></listitem>
222 <listitem><para><emphasis>Add Content:</emphasis> Depending
223 on the type of layer, add the content.
224 If the layer adds support for a machine, add the machine
225 configuration in a <filename>conf/machine/</filename>
226 file within the layer.
227 If the layer adds distro policy, add the distro
228 configuration in a <filename>conf/distro/</filename>
229 file within the layer.
230 If the layer introduces new recipes, put the recipes
231 you need in <filename>recipes-*</filename>
232 subdirectories within the layer.
233 <note>In order to be compliant with the Yocto Project,
234 a layer must contain a
235 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
236 </note></para></listitem>
237 </orderedlist>
238 </para>
239 </section>
240
241 <section id='best-practices-to-follow-when-creating-layers'>
242 <title>Best Practices to Follow When Creating Layers</title>
243
244 <para>
245 To create layers that are easier to maintain and that will
246 not impact builds for other machines, you should consider the
247 information in the following sections.
248 </para>
249
250 <section id='avoid-overlaying-entire-recipes'>
251 <title>Avoid "Overlaying" Entire Recipes</title>
252
253 <para>
254 Avoid "overlaying" entire recipes from other layers in your
255 configuration.
256 In other words, do not copy an entire recipe into your
257 layer and then modify it.
258 Rather, use an append file (<filename>.bbappend</filename>)
259 to override
260 only those parts of the original recipe you need to modify.
261 </para>
262 </section>
263
264 <section id='avoid-duplicating-include-files'>
265 <title>Avoid Duplicating Include Files</title>
266
267 <para>
268 Avoid duplicating include files.
269 Use append files (<filename>.bbappend</filename>)
270 for each recipe
271 that uses an include file.
272 Or, if you are introducing a new recipe that requires
273 the included file, use the path relative to the original
274 layer directory to refer to the file.
275 For example, use
276 <filename>require recipes-core/somepackage/somefile.inc</filename>
277 instead of <filename>require somefile.inc</filename>.
278 If you're finding you have to overlay the include file,
279 it could indicate a deficiency in the include file in
280 the layer to which it originally belongs.
281 If this is the case, you need to address that deficiency
282 instead of overlaying the include file.
283 </para>
284
285 <para>
286 For example, consider how support plug-ins for the Qt 4
287 database are configured.
288 The Source Directory does not have MySQL or PostgreSQL.
289 However, OpenEmbedded's layer <filename>meta-oe</filename>
290 does.
291 Consequently, <filename>meta-oe</filename> uses
292 append files to modify the
293 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
294 enable the appropriate plug-ins.
295 This variable was added to the <filename>qt4.inc</filename>
296 include file in the Source Directory specifically to allow
297 the <filename>meta-oe</filename> layer to be able to control
298 which plug-ins are built.
299 </para>
300 </section>
301
302 <section id='structure-your-layers'>
303 <title>Structure Your Layers</title>
304
305 <para>
306 Proper use of overrides within append files and placement
307 of machine-specific files within your layer can ensure that
308 a build is not using the wrong Metadata and negatively
309 impacting a build for a different machine.
310 Following are some examples:
311 <itemizedlist>
312 <listitem><para><emphasis>Modifying Variables to Support
313 a Different Machine:</emphasis>
314 Suppose you have a layer named
315 <filename>meta-one</filename> that adds support
316 for building machine "one".
317 To do so, you use an append file named
318 <filename>base-files.bbappend</filename> and
319 create a dependency on "foo" by altering the
320 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
321 variable:
322 <literallayout class='monospaced'>
323 DEPENDS = "foo"
324 </literallayout>
325 The dependency is created during any build that
326 includes the layer
327 <filename>meta-one</filename>.
328 However, you might not want this dependency
329 for all machines.
330 For example, suppose you are building for
331 machine "two" but your
332 <filename>bblayers.conf</filename> file has the
333 <filename>meta-one</filename> layer included.
334 During the build, the
335 <filename>base-files</filename> for machine
336 "two" will also have the dependency on
337 <filename>foo</filename>.</para>
338 <para>To make sure your changes apply only when
339 building machine "one", use a machine override
340 with the <filename>DEPENDS</filename> statement:
341 <literallayout class='monospaced'>
342 DEPENDS_one = "foo"
343 </literallayout>
344 You should follow the same strategy when using
345 <filename>_append</filename> and
346 <filename>_prepend</filename> operations:
347 <literallayout class='monospaced'>
348 DEPENDS_append_one = " foo"
349 DEPENDS_prepend_one = "foo "
350 </literallayout>
351 As an actual example, here's a line from the recipe for
352 the OProfile profiler, which lists an extra build-time
353 dependency when building specifically for 64-bit PowerPC:
354 <literallayout class='monospaced'>
355 DEPENDS_append_powerpc64 = " libpfm4"
356 </literallayout>
357 <note>
358 Avoiding "+=" and "=+" and using
359 machine-specific
360 <filename>_append</filename>
361 and <filename>_prepend</filename> operations
362 is recommended as well.
363 </note></para></listitem>
364 <listitem><para><emphasis>Place Machine-Specific Files
365 in Machine-Specific Locations:</emphasis>
366 When you have a base recipe, such as
367 <filename>base-files.bb</filename>, that
368 contains a
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
370 statement to a file, you can use an append file
371 to cause the build to use your own version of
372 the file.
373 For example, an append file in your layer at
374 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
375 could extend
376 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
377 using
378 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
379 as follows:
380 <literallayout class='monospaced'>
381 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
382 </literallayout>
383 The build for machine "one" will pick up your
384 machine-specific file as long as you have the
385 file in
386 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
387 However, if you are building for a different
388 machine and the
389 <filename>bblayers.conf</filename> file includes
390 the <filename>meta-one</filename> layer and
391 the location of your machine-specific file is
392 the first location where that file is found
393 according to <filename>FILESPATH</filename>,
394 builds for all machines will also use that
395 machine-specific file.</para>
396 <para>You can make sure that a machine-specific
397 file is used for a particular machine by putting
398 the file in a subdirectory specific to the
399 machine.
400 For example, rather than placing the file in
401 <filename>meta-one/recipes-core/base-files/base-files/</filename>
402 as shown above, put it in
403 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
404 Not only does this make sure the file is used
405 only when building for machine "one", but the
406 build process locates the file more quickly.</para>
407 <para>In summary, you need to place all files
408 referenced from <filename>SRC_URI</filename>
409 in a machine-specific subdirectory within the
410 layer in order to restrict those files to
411 machine-specific builds.</para></listitem>
412 </itemizedlist>
413 </para>
414 </section>
415
416 <section id='other-recommendations'>
417 <title>Other Recommendations</title>
418
419 <para>
420 We also recommend the following:
421 <itemizedlist>
422 <listitem><para>Store custom layers in a Git repository
423 that uses the
424 <filename>meta-<replaceable>layer_name</replaceable></filename> format.
425 </para></listitem>
426 <listitem><para>Clone the repository alongside other
427 <filename>meta</filename> directories in the
428 <link linkend='source-directory'>Source Directory</link>.
429 </para></listitem>
430 </itemizedlist>
431 Following these recommendations keeps your Source Directory and
432 its configuration entirely inside the Yocto Project's core
433 base.
434 </para>
435 </section>
436 </section>
437
438 <section id='enabling-your-layer'>
439 <title>Enabling Your Layer</title>
440
441 <para>
442 Before the OpenEmbedded build system can use your new layer,
443 you need to enable it.
444 To enable your layer, simply add your layer's path to the
445 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
446 variable in your <filename>conf/bblayers.conf</filename> file,
447 which is found in the
448 <link linkend='build-directory'>Build Directory</link>.
449 The following example shows how to enable a layer named
450 <filename>meta-mylayer</filename>:
451 <literallayout class='monospaced'>
452 LCONF_VERSION = "6"
453
454 BBPATH = "${TOPDIR}"
455 BBFILES ?= ""
456
457 BBLAYERS ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 $HOME/poky/meta-yocto-bsp \
461 $HOME/poky/meta-mylayer \
462 "
463
464 BBLAYERS_NON_REMOVABLE ?= " \
465 $HOME/poky/meta \
466 $HOME/poky/meta-yocto \
467 "
468 </literallayout>
469 </para>
470
471 <para>
472 BitBake parses each <filename>conf/layer.conf</filename> file
473 as specified in the <filename>BBLAYERS</filename> variable
474 within the <filename>conf/bblayers.conf</filename> file.
475 During the processing of each
476 <filename>conf/layer.conf</filename> file, BitBake adds the
477 recipes, classes and configurations contained within the
478 particular layer to the source directory.
479 </para>
480 </section>
481
482 <section id='using-bbappend-files'>
483 <title>Using .bbappend Files</title>
484
485 <para>
486 Recipes used to append Metadata to other recipes are called
487 BitBake append files.
488 BitBake append files use the <filename>.bbappend</filename> file
489 type suffix, while the corresponding recipes to which Metadata
490 is being appended use the <filename>.bb</filename> file type
491 suffix.
492 </para>
493
494 <para>
495 A <filename>.bbappend</filename> file allows your layer to make
496 additions or changes to the content of another layer's recipe
497 without having to copy the other recipe into your layer.
498 Your <filename>.bbappend</filename> file resides in your layer,
499 while the main <filename>.bb</filename> recipe file to
500 which you are appending Metadata resides in a different layer.
501 </para>
502
503 <para>
504 Append files must have the same root names as their corresponding
505 recipes.
506 For example, the append file
507 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
508 <filename>someapp_&DISTRO;.bb</filename>.
509 This means the original recipe and append file names are version
510 number-specific.
511 If the corresponding recipe is renamed to update to a newer
512 version, the corresponding <filename>.bbappend</filename> file must
513 be renamed (and possibly updated) as well.
514 During the build process, BitBake displays an error on starting
515 if it detects a <filename>.bbappend</filename> file that does
516 not have a corresponding recipe with a matching name.
517 See the
518 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
519 variable for information on how to handle this error.
520 </para>
521
522 <para>
523 Being able to append information to an existing recipe not only
524 avoids duplication, but also automatically applies recipe
525 changes in a different layer to your layer.
526 If you were copying recipes, you would have to manually merge
527 changes as they occur.
528 </para>
529
530 <para>
531 As an example, consider the main formfactor recipe and a
532 corresponding formfactor append file both from the
533 <link linkend='source-directory'>Source Directory</link>.
534 Here is the main formfactor recipe, which is named
535 <filename>formfactor_0.0.bb</filename> and located in the
536 "meta" layer at
537 <filename>meta/recipes-bsp/formfactor</filename>:
538 <literallayout class='monospaced'>
539 SUMMARY = "Device formfactor information"
540 SECTION = "base"
541 LICENSE = "MIT"
542 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
543 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
544 PR = "r45"
545
546 SRC_URI = "file://config file://machconfig"
547 S = "${WORKDIR}"
548
549 PACKAGE_ARCH = "${MACHINE_ARCH}"
550 INHIBIT_DEFAULT_DEPS = "1"
551
552 do_install() {
553 # Install file only if it has contents
554 install -d ${D}${sysconfdir}/formfactor/
555 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
556 if [ -s "${S}/machconfig" ]; then
557 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
558 fi
559 }
560 </literallayout>
561 In the main recipe, note the
562 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
563 variable, which tells the OpenEmbedded build system where to
564 find files during the build.
565 </para>
566
567 <para>
568 Following is the append file, which is named
569 <filename>formfactor_0.0.bbappend</filename> and is from the
570 Crown Bay BSP Layer named
571 <filename>meta-intel/meta-crownbay</filename>.
572 The file is in <filename>recipes-bsp/formfactor</filename>:
573 <literallayout class='monospaced'>
574 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
575 </literallayout>
576 </para>
577
578 <para>
579 By default, the build system uses the
580 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
581 variable to locate files.
582 This append file extends the locations by setting the
583 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
584 variable.
585 Setting this variable in the <filename>.bbappend</filename>
586 file is the most reliable and recommended method for adding
587 directories to the search path used by the build system
588 to find files.
589 </para>
590
591 <para>
592 The statement in this example extends the directories to include
593 <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>,
594 which resolves to a directory named
595 <filename>formfactor</filename> in the same directory
596 in which the append file resides (i.e.
597 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
598 This implies that you must have the supporting directory
599 structure set up that will contain any files or patches you
600 will be including from the layer.
601 </para>
602
603 <para>
604 Using the immediate expansion assignment operator
605 <filename>:=</filename> is important because of the reference to
606 <filename>THISDIR</filename>.
607 The trailing colon character is important as it ensures that
608 items in the list remain colon-separated.
609 <note>
610 <para>
611 BitBake automatically defines the
612 <filename>THISDIR</filename> variable.
613 You should never set this variable yourself.
614 Using "_prepend" ensures your path will
615 be searched prior to other paths in the final list.
616 </para>
617
618 <para>
619 Also, not all append files add extra files.
620 Many append files simply exist to add build options
621 (e.g. <filename>systemd</filename>).
622 For these cases, it is not necessary to use the
623 "_prepend" part of the statement.
624 </para>
625 </note>
626 </para>
627 </section>
628
629 <section id='prioritizing-your-layer'>
630 <title>Prioritizing Your Layer</title>
631
632 <para>
633 Each layer is assigned a priority value.
634 Priority values control which layer takes precedence if there
635 are recipe files with the same name in multiple layers.
636 For these cases, the recipe file from the layer with a higher
637 priority number takes precedence.
638 Priority values also affect the order in which multiple
639 <filename>.bbappend</filename> files for the same recipe are
640 applied.
641 You can either specify the priority manually, or allow the
642 build system to calculate it based on the layer's dependencies.
643 </para>
644
645 <para>
646 To specify the layer's priority manually, use the
647 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
648 variable.
649 For example:
650 <literallayout class='monospaced'>
651 BBFILE_PRIORITY_mylayer = "1"
652 </literallayout>
653 </para>
654
655 <note>
656 <para>It is possible for a recipe with a lower version number
657 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
658 in a layer that has a higher priority to take precedence.</para>
659 <para>Also, the layer priority does not currently affect the
660 precedence order of <filename>.conf</filename>
661 or <filename>.bbclass</filename> files.
662 Future versions of BitBake might address this.</para>
663 </note>
664 </section>
665
666 <section id='managing-layers'>
667 <title>Managing Layers</title>
668
669 <para>
670 You can use the BitBake layer management tool to provide a view
671 into the structure of recipes across a multi-layer project.
672 Being able to generate output that reports on configured layers
673 with their paths and priorities and on
674 <filename>.bbappend</filename> files and their applicable
675 recipes can help to reveal potential problems.
676 </para>
677
678 <para>
679 Use the following form when running the layer management tool.
680 <literallayout class='monospaced'>
681 $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>]
682 </literallayout>
683 The following list describes the available commands:
684 <itemizedlist>
685 <listitem><para><filename><emphasis>help:</emphasis></filename>
686 Displays general help or help on a specified command.
687 </para></listitem>
688 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
689 Shows the current configured layers.
690 </para></listitem>
691 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
692 Lists available recipes and the layers that provide them.
693 </para></listitem>
694 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
695 Lists overlayed recipes.
696 A recipe is overlayed when a recipe with the same name
697 exists in another layer that has a higher layer
698 priority.
699 </para></listitem>
700 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
701 Lists <filename>.bbappend</filename> files and the
702 recipe files to which they apply.
703 </para></listitem>
704 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
705 Lists dependency relationships between recipes that
706 cross layer boundaries.
707 </para></listitem>
708 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
709 Flattens the layer configuration into a separate output
710 directory.
711 Flattening your layer configuration builds a "flattened"
712 directory that contains the contents of all layers,
713 with any overlayed recipes removed and any
714 <filename>.bbappend</filename> files appended to the
715 corresponding recipes.
716 You might have to perform some manual cleanup of the
717 flattened layer as follows:
718 <itemizedlist>
719 <listitem><para>Non-recipe files (such as patches)
720 are overwritten.
721 The flatten command shows a warning for these
722 files.
723 </para></listitem>
724 <listitem><para>Anything beyond the normal layer
725 setup has been added to the
726 <filename>layer.conf</filename> file.
727 Only the lowest priority layer's
728 <filename>layer.conf</filename> is used.
729 </para></listitem>
730 <listitem><para>Overridden and appended items from
731 <filename>.bbappend</filename> files need to be
732 cleaned up.
733 The contents of each
734 <filename>.bbappend</filename> end up in the
735 flattened recipe.
736 However, if there are appended or changed
737 variable values, you need to tidy these up
738 yourself.
739 Consider the following example.
740 Here, the <filename>bitbake-layers</filename>
741 command adds the line
742 <filename>#### bbappended ...</filename> so that
743 you know where the following lines originate:
744 <literallayout class='monospaced'>
745 ...
746 DESCRIPTION = "A useful utility"
747 ...
748 EXTRA_OECONF = "&dash;&dash;enable-something"
749 ...
750
751 #### bbappended from meta-anotherlayer ####
752
753 DESCRIPTION = "Customized utility"
754 EXTRA_OECONF += "&dash;&dash;enable-somethingelse"
755 </literallayout>
756 Ideally, you would tidy up these utilities as
757 follows:
758 <literallayout class='monospaced'>
759 ...
760 DESCRIPTION = "Customized utility"
761 ...
762 EXTRA_OECONF = "&dash;&dash;enable-something &dash;&dash;enable-somethingelse"
763 ...
764 </literallayout></para></listitem>
765 </itemizedlist></para></listitem>
766 </itemizedlist>
767 </para>
768 </section>
769
770 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
771 <title>Creating a General Layer Using the yocto-layer Script</title>
772
773 <para>
774 The <filename>yocto-layer</filename> script simplifies
775 creating a new general layer.
776 <note>
777 For information on BSP layers, see the
778 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
779 section in the Yocto Project Board Specific (BSP)
780 Developer's Guide.
781 </note>
782 The default mode of the script's operation is to prompt you for
783 information needed to generate the layer:
784 <itemizedlist>
785 <listitem><para>The layer priority.
786 </para></listitem>
787 <listitem><para>Whether or not to create a sample recipe.
788 </para></listitem>
789 <listitem><para>Whether or not to create a sample
790 append file.
791 </para></listitem>
792 </itemizedlist>
793 </para>
794
795 <para>
796 Use the <filename>yocto-layer create</filename> sub-command
797 to create a new general layer.
798 In its simplest form, you can create a layer as follows:
799 <literallayout class='monospaced'>
800 $ yocto-layer create mylayer
801 </literallayout>
802 The previous example creates a layer named
803 <filename>meta-mylayer</filename> in the current directory.
804 </para>
805
806 <para>
807 As the <filename>yocto-layer create</filename> command runs,
808 default values for the prompts appear in brackets.
809 Pressing enter without supplying anything for the prompts
810 or pressing enter and providing an invalid response causes the
811 script to accept the default value.
812 Once the script completes, the new layer
813 is created in the current working directory.
814 The script names the layer by prepending
815 <filename>meta-</filename> to the name you provide.
816 </para>
817
818 <para>
819 Minimally, the script creates the following within the layer:
820 <itemizedlist>
821 <listitem><para><emphasis>The <filename>conf</filename>
822 directory:</emphasis>
823 This directory contains the layer's configuration file.
824 The root name for the file is the same as the root name
825 your provided for the layer (e.g.
826 <filename><replaceable>layer</replaceable>.conf</filename>).
827 </para></listitem>
828 <listitem><para><emphasis>The
829 <filename>COPYING.MIT</filename> file:</emphasis>
830 The copyright and use notice for the software.
831 </para></listitem>
832 <listitem><para><emphasis>The <filename>README</filename>
833 file:</emphasis>
834 A file describing the contents of your new layer.
835 </para></listitem>
836 </itemizedlist>
837 </para>
838
839 <para>
840 If you choose to generate a sample recipe file, the script
841 prompts you for the name for the recipe and then creates it
842 in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>.
843 The script creates a <filename>.bb</filename> file and a
844 directory, which contains a sample
845 <filename>helloworld.c</filename> source file, along with
846 a sample patch file.
847 If you do not provide a recipe name, the script uses
848 "example".
849 </para>
850
851 <para>
852 If you choose to generate a sample append file, the script
853 prompts you for the name for the file and then creates it
854 in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>.
855 The script creates a <filename>.bbappend</filename> file and a
856 directory, which contains a sample patch file.
857 If you do not provide a recipe name, the script uses
858 "example".
859 The script also prompts you for the version of the append file.
860 The version should match the recipe to which the append file
861 is associated.
862 </para>
863
864 <para>
865 The easiest way to see how the <filename>yocto-layer</filename>
866 script works is to experiment with the script.
867 You can also read the usage information by entering the
868 following:
869 <literallayout class='monospaced'>
870 $ yocto-layer help
871 </literallayout>
872 </para>
873
874 <para>
875 Once you create your general layer, you must add it to your
876 <filename>bblayers.conf</filename> file.
877 Here is an example where a layer named
878 <filename>meta-mylayer</filename> is added:
879 <literallayout class='monospaced'>
880 BBLAYERS = ?" \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 /usr/local/src/yocto/meta-yocto-bsp \
884 /usr/local/src/yocto/meta-mylayer \
885 "
886
887 BBLAYERS_NON_REMOVABLE ?= " \
888 /usr/local/src/yocto/meta \
889 /usr/local/src/yocto/meta-yocto \
890 "
891 </literallayout>
892 Adding the layer to this file enables the build system to
893 locate the layer during the build.
894 </para>
895 </section>
896 </section>
897
898 <section id='usingpoky-extend-customimage'>
899 <title>Customizing Images</title>
900
901 <para>
902 You can customize images to satisfy particular requirements.
903 This section describes several methods and provides guidelines for each.
904 </para>
905
906 <section id='usingpoky-extend-customimage-localconf'>
907 <title>Customizing Images Using <filename>local.conf</filename></title>
908
909 <para>
910 Probably the easiest way to customize an image is to add a
911 package by way of the <filename>local.conf</filename>
912 configuration file.
913 Because it is limited to local use, this method generally only
914 allows you to add packages and is not as flexible as creating
915 your own customized image.
916 When you add packages using local variables this way, you need
917 to realize that these variable changes are in effect for every
918 build and consequently affect all images, which might not
919 be what you require.
920 </para>
921
922 <para>
923 To add a package to your image using the local configuration
924 file, use the
925 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
926 variable with the <filename>_append</filename> operator:
927 <literallayout class='monospaced'>
928 IMAGE_INSTALL_append = " strace"
929 </literallayout>
930 Use of the syntax is important - specifically, the space between
931 the quote and the package name, which is
932 <filename>strace</filename> in this example.
933 This space is required since the <filename>_append</filename>
934 operator does not add the space.
935 </para>
936
937 <para>
938 Furthermore, you must use <filename>_append</filename> instead
939 of the <filename>+=</filename> operator if you want to avoid
940 ordering issues.
941 The reason for this is because doing so unconditionally appends
942 to the variable and avoids ordering problems due to the
943 variable being set in image recipes and
944 <filename>.bbclass</filename> files with operators like
945 <filename>?=</filename>.
946 Using <filename>_append</filename> ensures the operation takes
947 affect.
948 </para>
949
950 <para>
951 As shown in its simplest use,
952 <filename>IMAGE_INSTALL_append</filename> affects all images.
953 It is possible to extend the syntax so that the variable
954 applies to a specific image only.
955 Here is an example:
956 <literallayout class='monospaced'>
957 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
958 </literallayout>
959 This example adds <filename>strace</filename> to the
960 <filename>core-image-minimal</filename> image only.
961 </para>
962
963 <para>
964 You can add packages using a similar approach through the
965 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
966 variable.
967 If you use this variable, only
968 <filename>core-image-*</filename> images are affected.
969 </para>
970 </section>
971
972 <section id='usingpoky-extend-customimage-imagefeatures'>
973 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
974 <filename>EXTRA_IMAGE_FEATURES</filename></title>
975
976 <para>
977 Another method for customizing your image is to enable or
978 disable high-level image features by using the
979 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
980 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
981 variables.
982 Although the functions for both variables are nearly equivalent,
983 best practices dictate using <filename>IMAGE_FEATURES</filename>
984 from within a recipe and using
985 <filename>EXTRA_IMAGE_FEATURES</filename> from within
986 your <filename>local.conf</filename> file, which is found in the
987 <link linkend='build-directory'>Build Directory</link>.
988 </para>
989
990 <para>
991 To understand how these features work, the best reference is
992 <filename>meta/classes/core-image.bbclass</filename>.
993 In summary, the file looks at the contents of the
994 <filename>IMAGE_FEATURES</filename> variable and then maps
995 those contents into a set of package groups.
996 Based on this information, the build system automatically
997 adds the appropriate packages to the
998 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
999 variable.
1000 Effectively, you are enabling extra features by extending the
1001 class or creating a custom class for use with specialized image
1002 <filename>.bb</filename> files.
1003 </para>
1004
1005 <para>
1006 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1007 from within your local configuration file.
1008 Using a separate area from which to enable features with
1009 this variable helps you avoid overwriting the features in the
1010 image recipe that are enabled with
1011 <filename>IMAGE_FEATURES</filename>.
1012 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1013 to <filename>IMAGE_FEATURES</filename> within
1014 <filename>meta/conf/bitbake.conf</filename>.
1015 </para>
1016
1017 <para>
1018 To illustrate how you can use these variables to modify your
1019 image, consider an example that selects the SSH server.
1020 The Yocto Project ships with two SSH servers you can use
1021 with your images: Dropbear and OpenSSH.
1022 Dropbear is a minimal SSH server appropriate for
1023 resource-constrained environments, while OpenSSH is a
1024 well-known standard SSH server implementation.
1025 By default, the <filename>core-image-sato</filename> image
1026 is configured to use Dropbear.
1027 The <filename>core-image-full-cmdline</filename> and
1028 <filename>core-image-lsb</filename> images both
1029 include OpenSSH.
1030 The <filename>core-image-minimal</filename> image does not
1031 contain an SSH server.
1032 </para>
1033
1034 <para>
1035 You can customize your image and change these defaults.
1036 Edit the <filename>IMAGE_FEATURES</filename> variable
1037 in your recipe or use the
1038 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1039 <filename>local.conf</filename> file so that it configures the
1040 image you are working with to include
1041 <filename>ssh-server-dropbear</filename> or
1042 <filename>ssh-server-openssh</filename>.
1043 </para>
1044
1045 <note>
1046 See the
1047 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1048 section in the Yocto Project Reference Manual for a complete
1049 list of image features that ship with the Yocto Project.
1050 </note>
1051 </section>
1052
1053 <section id='usingpoky-extend-customimage-custombb'>
1054 <title>Customizing Images Using Custom .bb Files</title>
1055
1056 <para>
1057 You can also customize an image by creating a custom recipe
1058 that defines additional software as part of the image.
1059 The following example shows the form for the two lines you need:
1060 <literallayout class='monospaced'>
1061 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1062
1063 inherit core-image
1064 </literallayout>
1065 </para>
1066
1067 <para>
1068 Defining the software using a custom recipe gives you total
1069 control over the contents of the image.
1070 It is important to use the correct names of packages in the
1071 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1072 variable.
1073 You must use the OpenEmbedded notation and not the Debian notation for the names
1074 (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>).
1075 </para>
1076
1077 <para>
1078 The other method for creating a custom image is to base it on an existing image.
1079 For example, if you want to create an image based on <filename>core-image-sato</filename>
1080 but add the additional package <filename>strace</filename> to the image,
1081 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1082 new <filename>.bb</filename> and add the following line to the end of the copy:
1083 <literallayout class='monospaced'>
1084 IMAGE_INSTALL += "strace"
1085 </literallayout>
1086 </para>
1087 </section>
1088
1089 <section id='usingpoky-extend-customimage-customtasks'>
1090 <title>Customizing Images Using Custom Package Groups</title>
1091
1092 <para>
1093 For complex custom images, the best approach for customizing
1094 an image is to create a custom package group recipe that is
1095 used to build the image or images.
1096 A good example of a package group recipe is
1097 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1098 The
1099 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1100 variable lists the package group packages you wish to produce.
1101 <filename>inherit packagegroup</filename> sets appropriate
1102 default values and automatically adds <filename>-dev</filename>,
1103 <filename>-dbg</filename>, and <filename>-ptest</filename>
1104 complementary packages for every package specified in
1105 <filename>PACKAGES</filename>.
1106 Note that the inherit line should be towards
1107 the top of the recipe, certainly before you set
1108 <filename>PACKAGES</filename>.
1109 For each package you specify in <filename>PACKAGES</filename>,
1110 you can use
1111 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1112 and
1113 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1114 entries to provide a list of packages the parent task package
1115 should contain.
1116 Following is an example:
1117 <literallayout class='monospaced'>
1118 DESCRIPTION = "My Custom Package Groups"
1119
1120 inherit packagegroup
1121
1122 PACKAGES = "\
1123 packagegroup-custom-apps \
1124 packagegroup-custom-tools \
1125 "
1126
1127 RDEPENDS_packagegroup-custom-apps = "\
1128 dropbear \
1129 portmap \
1130 psplash"
1131
1132 RDEPENDS_packagegroup-custom-tools = "\
1133 oprofile \
1134 oprofileui-server \
1135 lttng-control \
1136 lttng-viewer"
1137
1138 RRECOMMENDS_packagegroup-custom-tools = "\
1139 kernel-module-oprofile"
1140 </literallayout>
1141 </para>
1142
1143 <para>
1144 In the previous example, two package group packages are created with their dependencies and their
1145 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1146 <filename>packagegroup-custom-tools</filename>.
1147 To build an image using these package group packages, you need to add
1148 <filename>packagegroup-custom-apps</filename> and/or
1149 <filename>packagegroup-custom-tools</filename> to
1150 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1151 For other forms of image dependencies see the other areas of this section.
1152 </para>
1153 </section>
1154 </section>
1155
1156 <section id='new-recipe-writing-a-new-recipe'>
1157 <title>Writing a New Recipe</title>
1158
1159 <para>
1160 Recipes (<filename>.bb</filename> files) are fundamental components
1161 in the Yocto Project environment.
1162 Each software component built by the OpenEmbedded build system
1163 requires a recipe to define the component.
1164 This section describes how to create, write, and test a new
1165 recipe.
1166 <note>
1167 For information on variables that are useful for recipes and
1168 for information about recipe naming issues, see the
1169 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1170 section of the Yocto Project Reference Manual.
1171 </note>
1172 </para>
1173
1174 <section id='new-recipe-overview'>
1175 <title>Overview</title>
1176
1177 <para>
1178 The following figure shows the basic process for creating a
1179 new recipe.
1180 The remainder of the section provides details for the steps.
1181 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1182 </para>
1183 </section>
1184
1185 <section id='new-recipe-locate-a-base-recipe'>
1186 <title>Locate a Base Recipe</title>
1187
1188 <para>
1189 Before writing a recipe from scratch, it is often useful to
1190 discover whether someone else has already written one that
1191 meets (or comes close to meeting) your needs.
1192 The Yocto Project and OpenEmbedded communities maintain many
1193 recipes that might be candidates for what you are doing.
1194 You can find a good central index of these recipes in the
1195 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1196 </para>
1197
1198 <para>
1199 Working from an existing recipe or a skeleton recipe is the
1200 best way to get started.
1201 Here are some points on both methods:
1202 <itemizedlist>
1203 <listitem><para><emphasis>Locate and modify a recipe that
1204 is close to what you want to do:</emphasis>
1205 This method works when you are familiar with the
1206 current recipe space.
1207 The method does not work so well for those new to
1208 the Yocto Project or writing recipes.</para>
1209 <para>Some risks associated with this method are
1210 using a recipe that has areas totally unrelated to
1211 what you are trying to accomplish with your recipe,
1212 not recognizing areas of the recipe that you might
1213 have to add from scratch, and so forth.
1214 All these risks stem from unfamiliarity with the
1215 existing recipe space.</para></listitem>
1216 <listitem><para><emphasis>Use and modify the following
1217 skeleton recipe:</emphasis>
1218 <literallayout class='monospaced'>
1219 SUMMARY = ""
1220 HOMEPAGE = ""
1221 LICENSE = ""
1222
1223 LIC_FILES_CHKSUM = ""
1224
1225 SRC_URI = ""
1226 SRC_URI[md5sum] = ""
1227 SRC_URI[sha256sum] = ""
1228
1229 S = "${WORKDIR}/${PN}-${PV}"
1230
1231 inherit <replaceable>stuff</replaceable>
1232 </literallayout>
1233 Modifying this recipe is the recommended method for
1234 creating a new recipe.
1235 The recipe provides the fundamental areas that you need
1236 to include, exclude, or alter to fit your needs.
1237 </para></listitem>
1238 </itemizedlist>
1239 </para>
1240 </section>
1241
1242 <section id='new-recipe-storing-and-naming-the-recipe'>
1243 <title>Storing and Naming the Recipe</title>
1244
1245 <para>
1246 Once you have your base recipe, you should put it in your
1247 own layer and name it appropriately.
1248 Locating it correctly ensures that the OpenEmbedded build
1249 system can find it when you use BitBake to process the
1250 recipe.
1251 </para>
1252
1253 <itemizedlist>
1254 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1255 The OpenEmbedded build system locates your recipe
1256 through the layer's <filename>conf/layer.conf</filename>
1257 file and the
1258 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1259 variable.
1260 This variable sets up a path from which the build system can
1261 locate recipes.
1262 Here is the typical use:
1263 <literallayout class='monospaced'>
1264 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1265 ${LAYERDIR}/recipes-*/*/*.bbappend"
1266 </literallayout>
1267 Consequently, you need to be sure you locate your new recipe
1268 inside your layer such that it can be found.</para>
1269 <para>You can find more information on how layers are
1270 structured in the
1271 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1272 section.</para></listitem>
1273 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1274 When you name your recipe, you need to follow this naming
1275 convention:
1276 <literallayout class='monospaced'>
1277 <replaceable>basename</replaceable>_<replaceable>version</replaceable>.bb
1278 </literallayout>
1279 Use lower-cased characters and do not include the reserved
1280 suffixes <filename>-native</filename>,
1281 <filename>-cross</filename>, <filename>-initial</filename>,
1282 or <filename>-dev</filename> casually (i.e. do not use them
1283 as part of your recipe name unless the string applies).
1284 Here are some examples:
1285 <literallayout class='monospaced'>
1286 cups_1.7.0.bb
1287 gawk_4.0.2.bb
1288 irssi_0.8.16-rc1.bb
1289 </literallayout></para></listitem>
1290 </itemizedlist>
1291 </section>
1292
1293 <section id='understanding-recipe-syntax'>
1294 <title>Understanding Recipe Syntax</title>
1295
1296 <para>
1297 Understanding recipe file syntax is important for
1298 writing recipes.
1299 The following list overviews the basic items that make up a
1300 BitBake recipe file.
1301 For more complete BitBake syntax descriptions, see the
1302 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
1303 chapter of the BitBake User Manual.
1304 <itemizedlist>
1305 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1306 Variable assignments allow a value to be assigned to a
1307 variable.
1308 The assignment can be static text or might include
1309 the contents of other variables.
1310 In addition to the assignment, appending and prepending
1311 operations are also supported.</para>
1312 <para>The following example shows some of the ways
1313 you can use variables in recipes:
1314 <literallayout class='monospaced'>
1315 S = "${WORKDIR}/postfix-${PV}"
1316 CFLAGS += "-DNO_ASM"
1317 SRC_URI_append = " file://fixup.patch"
1318 </literallayout>
1319 </para></listitem>
1320 <listitem><para><emphasis>Functions:</emphasis>
1321 Functions provide a series of actions to be performed.
1322 You usually use functions to override the default
1323 implementation of a task function or to complement
1324 a default function (i.e. append or prepend to an
1325 existing function).
1326 Standard functions use <filename>sh</filename> shell
1327 syntax, although access to OpenEmbedded variables and
1328 internal methods are also available.</para>
1329 <para>The following is an example function from the
1330 <filename>sed</filename> recipe:
1331 <literallayout class='monospaced'>
1332 do_install () {
1333 autotools_do_install
1334 install -d ${D}${base_bindir}
1335 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
1336 rmdir ${D}${bindir}/
1337 }
1338 </literallayout>
1339 It is also possible to implement new functions that
1340 are called between existing tasks as long as the
1341 new functions are not replacing or complementing the
1342 default functions.
1343 You can implement functions in Python
1344 instead of shell.
1345 Both of these options are not seen in the majority of
1346 recipes.</para></listitem>
1347 <listitem><para><emphasis>Keywords:</emphasis>
1348 BitBake recipes use only a few keywords.
1349 You use keywords to include common
1350 functions (<filename>inherit</filename>), load parts
1351 of a recipe from other files
1352 (<filename>include</filename> and
1353 <filename>require</filename>) and export variables
1354 to the environment (<filename>export</filename>).</para>
1355 <para>The following example shows the use of some of
1356 these keywords:
1357 <literallayout class='monospaced'>
1358 export POSTCONF = "${STAGING_BINDIR}/postconf"
1359 inherit autoconf
1360 require otherfile.inc
1361 </literallayout>
1362 </para></listitem>
1363 <listitem><para><emphasis>Comments:</emphasis>
1364 Any lines that begin with the hash character
1365 (<filename>#</filename>) are treated as comment lines
1366 and are ignored:
1367 <literallayout class='monospaced'>
1368 # This is a comment
1369 </literallayout>
1370 </para></listitem>
1371 </itemizedlist>
1372 </para>
1373
1374 <para>
1375 This next list summarizes the most important and most commonly
1376 used parts of the recipe syntax.
1377 For more information on these parts of the syntax, you can
1378 reference the
1379 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1380 chapter in the BitBake User Manual.
1381 <itemizedlist>
1382 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1383 Use the backward slash (<filename>\</filename>)
1384 character to split a statement over multiple lines.
1385 Place the slash character at the end of the line that
1386 is to be continued on the next line:
1387 <literallayout class='monospaced'>
1388 VAR = "A really long \
1389 line"
1390 </literallayout>
1391 <note>
1392 You cannot have any characters including spaces
1393 or tabs after the slash character.
1394 </note>
1395 </para></listitem>
1396 <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1397 Use the <filename>${<replaceable>varname</replaceable>}</filename> syntax to
1398 access the contents of a variable:
1399 <literallayout class='monospaced'>
1400 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1401 </literallayout>
1402 </para></listitem>
1403 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1404 Use double quotes around the value in all variable
1405 assignments.
1406 <literallayout class='monospaced'>
1407 VAR1 = "${OTHERVAR}"
1408 VAR2 = "The version is ${PV}"
1409 </literallayout>
1410 </para></listitem>
1411 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1412 Conditional assignment is used to assign a value to
1413 a variable, but only when the variable is currently
1414 unset.
1415 Use the question mark followed by the equal sign
1416 (<filename>?=</filename>) to make a "soft" assignment
1417 used for conditional assignment.
1418 Typically, "soft" assignments are used in the
1419 <filename>local.conf</filename> file for variables
1420 that are allowed to come through from the external
1421 environment.
1422 </para>
1423 <para>Here is an example where
1424 <filename>VAR1</filename> is set to "New value" if
1425 it is currently empty.
1426 However, if <filename>VAR1</filename> has already been
1427 set, it remains unchanged:
1428 <literallayout class='monospaced'>
1429 VAR1 ?= "New value"
1430 </literallayout>
1431 In this next example, <filename>VAR1</filename>
1432 is left with the value "Original value":
1433 <literallayout class='monospaced'>
1434 VAR1 = "Original value"
1435 VAR1 ?= "New value"
1436 </literallayout>
1437 </para></listitem>
1438 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1439 Use the plus character followed by the equals sign
1440 (<filename>+=</filename>) to append values to existing
1441 variables.
1442 <note>
1443 This operator adds a space between the existing
1444 content of the variable and the new content.
1445 </note></para>
1446 <para>Here is an example:
1447 <literallayout class='monospaced'>
1448 SRC_URI += "file://fix-makefile.patch"
1449 </literallayout>
1450 </para></listitem>
1451 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1452 Use the equals sign followed by the plus character
1453 (<filename>=+</filename>) to prepend values to existing
1454 variables.
1455 <note>
1456 This operator adds a space between the new content
1457 and the existing content of the variable.
1458 </note></para>
1459 <para>Here is an example:
1460 <literallayout class='monospaced'>
1461 VAR =+ "Starts"
1462 </literallayout>
1463 </para></listitem>
1464 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1465 Use the <filename>_append</filename> operator to
1466 append values to existing variables.
1467 This operator does not add any additional space.
1468 Also, the operator is applied after all the
1469 <filename>+=</filename>, and
1470 <filename>=+</filename> operators have been applied and
1471 after all <filename>=</filename> assignments have
1472 occurred.
1473 </para>
1474 <para>The following example shows the space being
1475 explicitly added to the start to ensure the appended
1476 value is not merged with the existing value:
1477 <literallayout class='monospaced'>
1478 SRC_URI_append = " file://fix-makefile.patch"
1479 </literallayout>
1480 You can also use the <filename>_append</filename>
1481 operator with overrides, which results in the actions
1482 only being performed for the specified target or
1483 machine:
1484 <literallayout class='monospaced'>
1485 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1486 </literallayout>
1487 </para></listitem>
1488 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1489 Use the <filename>_prepend</filename> operator to
1490 prepend values to existing variables.
1491 This operator does not add any additional space.
1492 Also, the operator is applied after all the
1493 <filename>+=</filename>, and
1494 <filename>=+</filename> operators have been applied and
1495 after all <filename>=</filename> assignments have
1496 occurred.
1497 </para>
1498 <para>The following example shows the space being
1499 explicitly added to the end to ensure the prepended
1500 value is not merged with the existing value:
1501 <literallayout class='monospaced'>
1502 CFLAGS_prepend = "-I${S}/myincludes "
1503 </literallayout>
1504 You can also use the <filename>_prepend</filename>
1505 operator with overrides, which results in the actions
1506 only being performed for the specified target or
1507 machine:
1508 <literallayout class='monospaced'>
1509 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1510 </literallayout>
1511 </para></listitem>
1512 <listitem><para><emphasis>Overrides:</emphasis> -
1513 You can use overrides to set a value conditionally,
1514 typically based on how the recipe is being built.
1515 For example, to set the
1516 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1517 variable's value to "standard/base" for any target
1518 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1519 except for qemuarm where it should be set to
1520 "standard/arm-versatile-926ejs", you would do the
1521 following:
1522 <literallayout class='monospaced'>
1523 KBRANCH = "standard/base"
1524 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1525 </literallayout>
1526 Overrides are also used to separate alternate values
1527 of a variable in other situations.
1528 For example, when setting variables such as
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1530 and
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1532 that are specific to individual packages produced by
1533 a recipe, you should always use an override that
1534 specifies the name of the package.
1535 </para></listitem>
1536 <listitem><para><emphasis>Indentation:</emphasis>
1537 Use spaces for indentation rather than than tabs.
1538 For shell functions, both currently work.
1539 However, it is a policy decision of the Yocto Project
1540 to use tabs in shell functions.
1541 Realize that some layers have a policy to use spaces
1542 for all indentation.
1543 </para></listitem>
1544 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1545 For more advanced processing, it is possible to use
1546 Python code during variable assignments (e.g.
1547 search and replacement on a variable).</para>
1548 <para>You indicate Python code using the
1549 <filename>${@<replaceable>python_code</replaceable>}</filename>
1550 syntax for the variable assignment:
1551 <literallayout class='monospaced'>
1552 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1553 </literallayout>
1554 </para></listitem>
1555 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1556 Write shell functions as if you were writing a shell
1557 script when you describe a list of actions to take.
1558 You should ensure that your script works with a generic
1559 <filename>sh</filename> and that it does not require
1560 any <filename>bash</filename> or other shell-specific
1561 functionality.
1562 The same considerations apply to various system
1563 utilities (e.g. <filename>sed</filename>,
1564 <filename>grep</filename>, <filename>awk</filename>,
1565 and so forth) that you might wish to use.
1566 If in doubt, you should check with multiple
1567 implementations - including those from BusyBox.
1568 </para></listitem>
1569 </itemizedlist>
1570 </para>
1571 </section>
1572
1573 <section id='new-recipe-running-a-build-on-the-recipe'>
1574 <title>Running a Build on the Recipe</title>
1575
1576 <para>
1577 Creating a new recipe is usually an iterative process that
1578 requires using BitBake to process the recipe multiple times in
1579 order to progressively discover and add information to the
1580 recipe file.
1581 </para>
1582
1583 <para>
1584 Assuming you have sourced a build environment setup script (i.e.
1585 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1586 or
1587 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1588 and you are in the
1589 <link linkend='build-directory'>Build Directory</link>,
1590 use BitBake to process your recipe.
1591 All you need to provide is the
1592 <filename><replaceable>basename</replaceable></filename> of the recipe as described
1593 in the previous section:
1594 <literallayout class='monospaced'>
1595 $ bitbake <replaceable>basename</replaceable>
1596 </literallayout>
1597
1598 </para>
1599
1600 <para>
1601 During the build, the OpenEmbedded build system creates a
1602 temporary work directory for each recipe
1603 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1604 where it keeps extracted source files, log files, intermediate
1605 compilation and packaging files, and so forth.
1606 </para>
1607
1608 <para>
1609 The per-recipe temporary work directory is constructed as follows and
1610 depends on several factors:
1611 <literallayout class='monospaced'>
1612 BASE_WORKDIR ?= "${TMPDIR}/work"
1613 WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
1614 </literallayout>
1615 As an example, assume a Source Directory top-level folder named
1616 <filename>poky</filename>, a default Build Directory at
1617 <filename>poky/build</filename>, and a
1618 <filename>qemux86-poky-linux</filename> machine target system.
1619 Furthermore, suppose your recipe is named
1620 <filename>foo_1.3.0.bb</filename>.
1621 In this case, the work directory the build system uses to
1622 build the package would be as follows:
1623 <literallayout class='monospaced'>
1624 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1625 </literallayout>
1626 Inside this directory you can find sub-directories such as
1627 <filename>image</filename>, <filename>packages-split</filename>,
1628 and <filename>temp</filename>.
1629 After the build, you can examine these to determine how well
1630 the build went.
1631 <note>
1632 You can find log files for each task in the recipe's
1633 <filename>temp</filename> directory (e.g.
1634 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1635 Log files are named <filename>log.<replaceable>taskname</replaceable></filename>
1636 (e.g. <filename>log.do_configure</filename>,
1637 <filename>log.do_fetch</filename>, and
1638 <filename>log.do_compile</filename>).
1639 </note>
1640 </para>
1641
1642 <para>
1643 You can find more information about the build process in the
1644 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1645 chapter of the Yocto Project Reference Manual.
1646 </para>
1647
1648 <para>
1649 You can also reference the following variables in the
1650 Yocto Project Reference Manual's glossary for more information:
1651 <itemizedlist>
1652 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1653 The top-level build output directory</listitem>
1654 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1655 The target system identifier</listitem>
1656 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1657 The recipe name</listitem>
1658 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1659 The epoch - (if
1660 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1661 is not specified, which is usually the case for most
1662 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1663 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1664 The recipe version</listitem>
1665 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1666 The recipe revision</listitem>
1667 </itemizedlist>
1668 </para>
1669 </section>
1670
1671 <section id='new-recipe-fetching-code'>
1672 <title>Fetching Code</title>
1673
1674 <para>
1675 The first thing your recipe must do is specify how to fetch
1676 the source files.
1677 Fetching is controlled mainly through the
1678 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1679 variable.
1680 Your recipe must have a <filename>SRC_URI</filename> variable
1681 that points to where the source is located.
1682 For a graphical representation of source locations, see the
1683 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1684 section in the Yocto Project Reference Manual.
1685 </para>
1686
1687 <para>
1688 The
1689 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1690 task uses the prefix of each entry in the
1691 <filename>SRC_URI</filename> variable value to determine which
1692 fetcher to use to get your source files.
1693 It is the <filename>SRC_URI</filename> variable that triggers
1694 the fetcher.
1695 The
1696 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1697 task uses the variable after source is fetched to apply
1698 patches.
1699 The OpenEmbedded build system uses
1700 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1701 for scanning directory locations for local files in
1702 <filename>SRC_URI</filename>.
1703 </para>
1704
1705 <para>
1706 The <filename>SRC_URI</filename> variable in your recipe must
1707 define each unique location for your source files.
1708 It is good practice to not hard-code pathnames in an URL used
1709 in <filename>SRC_URI</filename>.
1710 Rather than hard-code these paths, use
1711 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1712 which causes the fetch process to use the version specified in
1713 the recipe filename.
1714 Specifying the version in this manner means that upgrading the
1715 recipe to a future version is as simple as renaming the recipe
1716 to match the new version.
1717 </para>
1718
1719 <para>
1720 Here is a simple example from the
1721 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb</filename>
1722 recipe where the source comes from a single tarball.
1723 Notice the use of the
1724 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1725 variable:
1726 <literallayout class='monospaced'>
1727 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1728 </literallayout>
1729 </para>
1730
1731 <para>
1732 Files mentioned in <filename>SRC_URI</filename> whose names end
1733 in a typical archive extension (e.g. <filename>.tar</filename>,
1734 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1735 <filename>.zip</filename>, and so forth), are automatically
1736 extracted during the
1737 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1738 task.
1739 For another example that specifies these types of files, see
1740 the
1741 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1742 section.
1743 </para>
1744
1745 <para>
1746 Another way of specifying source is from an SCM.
1747 For Git repositories, you must specify
1748 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1749 and you should specify
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1751 to include the revision with
1752 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1753 Here is an example from the recipe
1754 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1755 <literallayout class='monospaced'>
1756 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1757
1758 PR = "r6"
1759 PV = "1.0.5+git${SRCPV}"
1760
1761 SRC_URI = "git://git.kernel.dk/blktrace.git \
1762 file://ldflags.patch"
1763 </literallayout>
1764 </para>
1765
1766 <para>
1767 If your <filename>SRC_URI</filename> statement includes
1768 URLs pointing to individual files fetched from a remote server
1769 other than a version control system, BitBake attempts to
1770 verify the files against checksums defined in your recipe to
1771 ensure they have not been tampered with or otherwise modified
1772 since the recipe was written.
1773 Two checksums are used:
1774 <filename>SRC_URI[md5sum]</filename> and
1775 <filename>SRC_URI[sha256sum]</filename>.
1776 </para>
1777
1778 <para>
1779 If your <filename>SRC_URI</filename> variable points to
1780 more than a single URL (excluding SCM URLs), you need to
1781 provide the <filename>md5</filename> and
1782 <filename>sha256</filename> checksums for each URL.
1783 For these cases, you provide a name for each URL as part of
1784 the <filename>SRC_URI</filename> and then reference that name
1785 in the subsequent checksum statements.
1786 Here is an example:
1787 <literallayout class='monospaced'>
1788 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1789 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1790
1791 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1792 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1793
1794 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1795 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1796 </literallayout>
1797 </para>
1798
1799 <para>
1800 Proper values for <filename>md5</filename> and
1801 <filename>sha256</filename> checksums might be available
1802 with other signatures on the download page for the upstream
1803 source (e.g. <filename>md5</filename>,
1804 <filename>sha1</filename>, <filename>sha256</filename>,
1805 <filename>GPG</filename>, and so forth).
1806 Because the OpenEmbedded build system only deals with
1807 <filename>sha256sum</filename> and <filename>md5sum</filename>,
1808 you should verify all the signatures you find by hand.
1809 </para>
1810
1811 <para>
1812 If no <filename>SRC_URI</filename> checksums are specified
1813 when you attempt to build the recipe, the build will produce
1814 an error for each missing checksum.
1815 As part of the error message, the build system provides
1816 the checksum string corresponding to the fetched file.
1817 Once you have the correct checksums, you can copy and paste
1818 them into your recipe and then run the build again to continue.
1819 <note>
1820 As mentioned, if the upstream source provides signatures
1821 for verifying the downloaded source code, you should
1822 verify those manually before setting the checksum values
1823 in the recipe and continuing with the build.
1824 </note>
1825 </para>
1826
1827 <para>
1828 This final example is a bit more complicated and is from the
1829 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb</filename>
1830 recipe.
1831 The example's <filename>SRC_URI</filename> statement identifies
1832 multiple files as the source files for the recipe: a tarball, a
1833 patch file, a desktop file, and an icon.
1834 <literallayout class='monospaced'>
1835 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1836 file://xwc.patch \
1837 file://rxvt.desktop \
1838 file://rxvt.png"
1839 </literallayout>
1840 </para>
1841
1842 <para>
1843 When you specify local files using the
1844 <filename>file://</filename> URI protocol, the build system
1845 fetches files from the local machine.
1846 The path is relative to the
1847 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1848 variable and searches specific directories in a certain order:
1849 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1850 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1851 and <filename>files</filename>.
1852 The directories are assumed to be subdirectories of the
1853 directory in which the recipe or append file resides.
1854 For another example that specifies these types of files, see the
1855 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1856 section.
1857 </para>
1858
1859 <para>
1860 The previous example also specifies a patch file.
1861 Patch files are files whose names end in
1862 <filename>.patch</filename> or <filename>.diff</filename>.
1863 The build system automatically applies patches as described
1864 in the
1865 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1866 </para>
1867 </section>
1868
1869 <section id='new-recipe-unpacking-code'>
1870 <title>Unpacking Code</title>
1871
1872 <para>
1873 During the build, the
1874 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1875 task unpacks the source with
1876 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1877 pointing to where it is unpacked.
1878 </para>
1879
1880 <para>
1881 If you are fetching your source files from an upstream source
1882 archived tarball and the tarball's internal structure matches
1883 the common convention of a top-level subdirectory named
1884 <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>,
1885 then you do not need to set <filename>S</filename>.
1886 However, if <filename>SRC_URI</filename> specifies to fetch
1887 source from an archive that does not use this convention,
1888 or from an SCM like Git or Subversion, your recipe needs to
1889 define <filename>S</filename>.
1890 </para>
1891
1892 <para>
1893 If processing your recipe using BitBake successfully unpacks
1894 the source files, you need to be sure that the directory
1895 pointed to by <filename>${S}</filename> matches the structure
1896 of the source.
1897 </para>
1898 </section>
1899
1900 <section id='new-recipe-patching-code'>
1901 <title>Patching Code</title>
1902
1903 <para>
1904 Sometimes it is necessary to patch code after it has been
1905 fetched.
1906 Any files mentioned in <filename>SRC_URI</filename> whose
1907 names end in <filename>.patch</filename> or
1908 <filename>.diff</filename> are treated as patches.
1909 The
1910 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1911 task automatically applies these patches.
1912 </para>
1913
1914 <para>
1915 The build system should be able to apply patches with the "-p1"
1916 option (i.e. one directory level in the path will be stripped
1917 off).
1918 If your patch needs to have more directory levels stripped off,
1919 specify the number of levels using the "striplevel" option in
1920 the <filename>SRC_URI</filename> entry for the patch.
1921 Alternatively, if your patch needs to be applied in a specific
1922 subdirectory that is not specified in the patch file, use the
1923 "patchdir" option in the entry.
1924 </para>
1925
1926 <para>
1927 As with all local files referenced in
1928 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1929 using <filename>file://</filename>, you should place
1930 patch files in a directory next to the recipe either
1931 named the same as the base name of the recipe
1932 (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
1933 or "files".
1934 </para>
1935 </section>
1936
1937 <section id='new-recipe-licensing'>
1938 <title>Licensing</title>
1939
1940 <para>
1941 Your recipe needs to have both the
1942 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1943 and
1944 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1945 variables:
1946 <itemizedlist>
1947 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1948 This variable specifies the license for the software.
1949 If you do not know the license under which the software
1950 you are building is distributed, you should go to the
1951 source code and look for that information.
1952 Typical files containing this information include
1953 <filename>COPYING</filename>,
1954 <filename>LICENSE</filename>, and
1955 <filename>README</filename> files.
1956 You could also find the information near the top of
1957 a source file.
1958 For example, given a piece of software licensed under
1959 the GNU General Public License version 2, you would
1960 set <filename>LICENSE</filename> as follows:
1961 <literallayout class='monospaced'>
1962 LICENSE = "GPLv2"
1963 </literallayout></para>
1964 <para>The licenses you specify within
1965 <filename>LICENSE</filename> can have any name as long
1966 as you do not use spaces, since spaces are used as
1967 separators between license names.
1968 For standard licenses, use the names of the files in
1969 <filename>meta/files/common-licenses/</filename>
1970 or the <filename>SPDXLICENSEMAP</filename> flag names
1971 defined in <filename>meta/conf/licenses.conf</filename>.
1972 </para></listitem>
1973 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1974 The OpenEmbedded build system uses this variable to
1975 make sure the license text has not changed.
1976 If it has, the build produces an error and it affords
1977 you the chance to figure it out and correct the problem.
1978 </para>
1979 <para>You need to specify all applicable licensing
1980 files for the software.
1981 At the end of the configuration step, the build process
1982 will compare the checksums of the files to be sure
1983 the text has not changed.
1984 Any differences result in an error with the message
1985 containing the current checksum.
1986 For more explanation and examples of how to set the
1987 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1988 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1989 section in the Yocto Project Reference Manual.</para>
1990 <para>To determine the correct checksum string, you
1991 can list the appropriate files in the
1992 <filename>LIC_FILES_CHKSUM</filename> variable with
1993 incorrect md5 strings, attempt to build the software,
1994 and then note the resulting error messages that will
1995 report the correct md5 strings.
1996 See the
1997 "<link linkend='new-recipe-fetching-code'>Fetching Code</link>"
1998 section for additional information.
1999 </para>
2000
2001 <para>
2002 Here is an example that assumes the software has a
2003 <filename>COPYING</filename> file:
2004 <literallayout class='monospaced'>
2005 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
2006 </literallayout>
2007 When you try to build the software, the build system
2008 will produce an error and give you the correct string
2009 that you can substitute into the recipe file for a
2010 subsequent build.
2011 </para></listitem>
2012 </itemizedlist>
2013 </para>
2014
2015<!--
2016
2017 <para>
2018 For trying this out I created a new recipe named
2019 <filename>htop_1.0.2.bb</filename> and put it in
2020 <filename>poky/meta/recipes-extended/htop</filename>.
2021 There are two license type statements in my very simple
2022 recipe:
2023 <literallayout class='monospaced'>
2024 LICENSE = ""
2025
2026 LIC_FILES_CHKSUM = ""
2027
2028 SRC_URI[md5sum] = ""
2029 SRC_URI[sha256sum] = ""
2030 </literallayout>
2031 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
2032 Next, you delete or comment out the two <filename>SRC_URI</filename>
2033 lines at the end and then attempt to build the software with
2034 <filename>bitbake htop</filename>.
2035 Doing so causes BitBake to report some errors and and give
2036 you the actual strings you need for the last two
2037 <filename>SRC_URI</filename> lines.
2038 Prior to this, you have to dig around in the home page of the
2039 source for <filename>htop</filename> and determine that the
2040 software is released under GPLv2.
2041 You can provide that in the <filename>LICENSE</filename>
2042 statement.
2043 Now you edit your recipe to have those two strings for
2044 the <filename>SRC_URI</filename> statements:
2045 <literallayout class='monospaced'>
2046 LICENSE = "GPLv2"
2047
2048 LIC_FILES_CHKSUM = ""
2049
2050 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
2051 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
2052 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
2053 </literallayout>
2054 At this point, you can build the software again using the
2055 <filename>bitbake htop</filename> command.
2056 There is just a set of errors now associated with the
2057 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
2058 </para>
2059-->
2060
2061 </section>
2062
2063 <section id='new-recipe-configuring-the-recipe'>
2064 <title>Configuring the Recipe</title>
2065
2066 <para>
2067 Most software provides some means of setting build-time
2068 configuration options before compilation.
2069 Typically, setting these options is accomplished by running a
2070 configure script with some options, or by modifying a build
2071 configuration file.
2072 </para>
2073
2074 <para>
2075 A major part of build-time configuration is about checking for
2076 build-time dependencies and possibly enabling optional
2077 functionality as a result.
2078 You need to specify any build-time dependencies for the
2079 software you are building in your recipe's
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2081 value, in terms of other recipes that satisfy those
2082 dependencies.
2083 You can often find build-time or runtime
2084 dependencies described in the software's documentation.
2085 </para>
2086
2087 <para>
2088 The following list provides configuration items of note based
2089 on how your software is built:
2090 <itemizedlist>
2091 <listitem><para><emphasis>Autotools:</emphasis>
2092 If your source files have a
2093 <filename>configure.ac</filename> file, then your
2094 software is built using Autotools.
2095 If this is the case, you just need to worry about
2096 modifying the configuration.</para>
2097 <para>When using Autotools, your recipe needs to inherit
2098 the
2099 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2100 class and your recipe does not have to contain a
2101 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2102 task.
2103 However, you might still want to make some adjustments.
2104 For example, you can set
2105 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
2106 to pass any needed configure options that are specific
2107 to the recipe.</para></listitem>
2108 <listitem><para><emphasis>CMake:</emphasis>
2109 If your source files have a
2110 <filename>CMakeLists.txt</filename> file, then your
2111 software is built using CMake.
2112 If this is the case, you just need to worry about
2113 modifying the configuration.</para>
2114 <para>When you use CMake, your recipe needs to inherit
2115 the
2116 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2117 class and your recipe does not have to contain a
2118 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2119 task.
2120 You can make some adjustments by setting
2121 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
2122 to pass any needed configure options that are specific
2123 to the recipe.</para></listitem>
2124 <listitem><para><emphasis>Other:</emphasis>
2125 If your source files do not have a
2126 <filename>configure.ac</filename> or
2127 <filename>CMakeLists.txt</filename> file, then your
2128 software is built using some method other than Autotools
2129 or CMake.
2130 If this is the case, you normally need to provide a
2131 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2132 task in your recipe
2133 unless, of course, there is nothing to configure.
2134 </para>
2135 <para>Even if your software is not being built by
2136 Autotools or CMake, you still might not need to deal
2137 with any configuration issues.
2138 You need to determine if configuration is even a required step.
2139 You might need to modify a Makefile or some configuration file
2140 used for the build to specify necessary build options.
2141 Or, perhaps you might need to run a provided, custom
2142 configure script with the appropriate options.</para>
2143 <para>For the case involving a custom configure
2144 script, you would run
2145 <filename>./configure &dash;&dash;help</filename> and look for
2146 the options you need to set.</para></listitem>
2147 </itemizedlist>
2148 </para>
2149
2150 <para>
2151 Once configuration succeeds, it is always good practice to
2152 look at the <filename>log.do_configure</filename> file to
2153 ensure that the appropriate options have been enabled and no
2154 additional build-time dependencies need to be added to
2155 <filename>DEPENDS</filename>.
2156 For example, if the configure script reports that it found
2157 something not mentioned in <filename>DEPENDS</filename>, or
2158 that it did not find something that it needed for some
2159 desired optional functionality, then you would need to add
2160 those to <filename>DEPENDS</filename>.
2161 Looking at the log might also reveal items being checked for,
2162 enabled, or both that you do not want, or items not being found
2163 that are in <filename>DEPENDS</filename>, in which case
2164 you would need to look at passing extra options to the
2165 configure script as needed.
2166 For reference information on configure options specific to the
2167 software you are building, you can consult the output of the
2168 <filename>./configure &dash;&dash;help</filename> command within
2169 <filename>${S}</filename> or consult the software's upstream
2170 documentation.
2171 </para>
2172 </section>
2173
2174 <section id='new-recipe-compilation'>
2175 <title>Compilation</title>
2176
2177 <para>
2178 During a build, the <filename>do_compile</filename> task
2179 happens after source is fetched, unpacked, and configured.
2180 If the recipe passes through <filename>do_compile</filename>
2181 successfully, nothing needs to be done.
2182 </para>
2183
2184 <para>
2185 However, if the compile step fails, you need to diagnose the
2186 failure.
2187 Here are some common issues that cause failures:
2188 <itemizedlist>
2189 <listitem><para><emphasis>Parallel build failures:</emphasis>
2190 These failures manifest themselves as intermittent
2191 errors, or errors reporting that a file or directory
2192 that should be created by some other part of the build
2193 process could not be found.
2194 This type of failure can occur even if, upon inspection,
2195 the file or directory does exist after the build has
2196 failed, because that part of the build process happened
2197 in the wrong order.</para>
2198 <para>To fix the problem, you need to either satisfy
2199 the missing dependency in the Makefile or whatever
2200 script produced the Makefile, or (as a workaround)
2201 set
2202 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
2203 to an empty string:
2204 <literallayout class='monospaced'>
2205 PARALLEL_MAKE = ""
2206 </literallayout></para>
2207 <para>
2208 For information on parallel Makefile issues, see the
2209 "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
2210 section.
2211 </para></listitem>
2212 <listitem><para><emphasis>Improper host path usage:</emphasis>
2213 This failure applies to recipes building for the target
2214 or <filename>nativesdk</filename> only.
2215 The failure occurs when the compilation process uses
2216 improper headers, libraries, or other files from the
2217 host system when cross-compiling for the target.
2218 </para>
2219 <para>To fix the problem, examine the
2220 <filename>log.do_compile</filename> file to identify
2221 the host paths being used (e.g.
2222 <filename>/usr/include</filename>,
2223 <filename>/usr/lib</filename>, and so forth) and then
2224 either add configure options, apply a patch, or do both.
2225 </para></listitem>
2226 <listitem><para><emphasis>Failure to find required
2227 libraries/headers:</emphasis>
2228 If a build-time dependency is missing because it has
2229 not been declared in
2230 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2231 or because the dependency exists but the path used by
2232 the build process to find the file is incorrect and the
2233 configure step did not detect it, the compilation
2234 process could fail.
2235 For either of these failures, the compilation process
2236 notes that files could not be found.
2237 In these cases, you need to go back and add additional
2238 options to the configure script as well as possibly
2239 add additional build-time dependencies to
2240 <filename>DEPENDS</filename>.</para>
2241 <para>Occasionally, it is necessary to apply a patch
2242 to the source to ensure the correct paths are used.
2243 If you need to specify paths to find files staged
2244 into the sysroot from other recipes, use the variables
2245 that the OpenEmbedded build system provides
2246 (e.g.
2247 <filename>STAGING_BINDIR</filename>,
2248 <filename>STAGING_INCDIR</filename>,
2249 <filename>STAGING_DATADIR</filename>, and so forth).
2250<!--
2251 (e.g.
2252 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
2253 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
2254 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
2255 and so forth).
2256-->
2257 </para></listitem>
2258 </itemizedlist>
2259 </para>
2260 </section>
2261
2262 <section id='new-recipe-installing'>
2263 <title>Installing</title>
2264
2265 <para>
2266 During <filename>do_install</filename>, the task copies the
2267 built files along with their hierarchy to locations that
2268 would mirror their locations on the target device.
2269 The installation process copies files from the
2270 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
2271 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
2272 and
2273 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
2274 directories to the
2275 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
2276 directory to create the structure as it should appear on the
2277 target system.
2278 </para>
2279
2280 <para>
2281 How your software is built affects what you must do to be
2282 sure your software is installed correctly.
2283 The following list describes what you must do for installation
2284 depending on the type of build system used by the software
2285 being built:
2286 <itemizedlist>
2287 <listitem><para><emphasis>Autotools and CMake:</emphasis>
2288 If the software your recipe is building uses Autotools
2289 or CMake, the OpenEmbedded build
2290 system understands how to install the software.
2291 Consequently, you do not have to have a
2292 <filename>do_install</filename> task as part of your
2293 recipe.
2294 You just need to make sure the install portion of the
2295 build completes with no issues.
2296 However, if you wish to install additional files not
2297 already being installed by
2298 <filename>make install</filename>, you should do this
2299 using a <filename>do_install_append</filename> function
2300 using the install command as described in
2301 the "Manual" bulleted item later in this list.
2302 </para></listitem>
2303 <listitem><para><emphasis>Other (using
2304 <filename>make install</filename>):</emphasis>
2305 You need to define a
2306 <filename>do_install</filename> function in your
2307 recipe.
2308 The function should call
2309 <filename>oe_runmake install</filename> and will likely
2310 need to pass in the destination directory as well.
2311 How you pass that path is dependent on how the
2312 <filename>Makefile</filename> being run is written
2313 (e.g. <filename>DESTDIR=${D}</filename>,
2314 <filename>PREFIX=${D}</filename>,
2315 <filename>INSTALLROOT=${D}</filename>, and so forth).
2316 </para>
2317 <para>For an example recipe using
2318 <filename>make install</filename>, see the
2319 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
2320 section.</para></listitem>
2321 <listitem><para><emphasis>Manual:</emphasis>
2322 You need to define a
2323 <filename>do_install</filename> function in your
2324 recipe.
2325 The function must first use
2326 <filename>install -d</filename> to create the
2327 directories under
2328 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
2329 Once the directories exist, your function can use
2330 <filename>install</filename> to manually install the
2331 built software into the directories.</para>
2332 <para>You can find more information on
2333 <filename>install</filename> at
2334 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
2335 </para></listitem>
2336 </itemizedlist>
2337 </para>
2338
2339 <para>
2340 For the scenarios that do not use Autotools or
2341 CMake, you need to track the installation
2342 and diagnose and fix any issues until everything installs
2343 correctly.
2344 You need to look in the default location of
2345 <filename>${D}</filename>, which is
2346 <filename>${WORKDIR}/image</filename>, to be sure your
2347 files have been installed correctly.
2348 </para>
2349
2350 <note><title>Notes</title>
2351 <itemizedlist>
2352 <listitem><para>
2353 During the installation process, you might need to
2354 modify some of the installed files to suit the target
2355 layout.
2356 For example, you might need to replace hard-coded paths
2357 in an initscript with values of variables provided by
2358 the build system, such as replacing
2359 <filename>/usr/bin/</filename> with
2360 <filename>${bindir}</filename>.
2361 If you do perform such modifications during
2362 <filename>do_install</filename>, be sure to modify the
2363 destination file after copying rather than before
2364 copying.
2365 Modifying after copying ensures that the build system
2366 can re-execute <filename>do_install</filename> if
2367 needed.
2368 </para></listitem>
2369 <listitem><para>
2370 <filename>oe_runmake install</filename>, which can be
2371 run directly or can be run indirectly by the
2372 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2373 and
2374 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2375 classes, runs <filename>make install</filename> in
2376 parallel.
2377 Sometimes, a Makefile can have missing dependencies
2378 between targets that can result in race conditions.
2379 If you experience intermittent failures during
2380 <filename>do_install</filename>, you might be able to
2381 work around them by disabling parallel Makefile
2382 installs by adding the following to the recipe:
2383 <literallayout class='monospaced'>
2384 PARALLEL_MAKEINST = ""
2385 </literallayout>
2386 See
2387 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2388 for additional information.
2389 </para></listitem>
2390 </itemizedlist>
2391 </note>
2392 </section>
2393
2394 <section id='new-recipe-enabling-system-services'>
2395 <title>Enabling System Services</title>
2396
2397 <para>
2398 If you want to install a service, which is a process that
2399 usually starts on boot and runs in the background, then
2400 you must include some additional definitions in your recipe.
2401 </para>
2402
2403 <para>
2404 If you are adding services and the service initialization
2405 script or the service file itself is not installed, you must
2406 provide for that installation in your recipe using a
2407 <filename>do_install_append</filename> function.
2408 If your recipe already has a <filename>do_install</filename>
2409 function, update the function near its end rather than
2410 adding an additional <filename>do_install_append</filename>
2411 function.
2412 </para>
2413
2414 <para>
2415 When you create the installation for your services, you need
2416 to accomplish what is normally done by
2417 <filename>make install</filename>.
2418 In other words, make sure your installation arranges the output
2419 similar to how it is arranged on the target system.
2420 </para>
2421
2422 <para>
2423 The OpenEmbedded build system provides support for starting
2424 services two different ways:
2425 <itemizedlist>
2426 <listitem><para><emphasis>SysVinit:</emphasis>
2427 SysVinit is a system and service manager that
2428 manages the init system used to control the very basic
2429 functions of your system.
2430 The init program is the first program
2431 started by the Linux kernel when the system boots.
2432 Init then controls the startup, running and shutdown
2433 of all other programs.</para>
2434 <para>To enable a service using SysVinit, your recipe
2435 needs to inherit the
2436 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2437 class.
2438 The class helps facilitate safely installing the
2439 package on the target.</para>
2440 <para>You will need to set the
2441 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2442 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2443 and
2444 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2445 variables within your recipe.</para></listitem>
2446 <listitem><para><emphasis>systemd:</emphasis>
2447 System Management Daemon (systemd) was designed to
2448 replace SysVinit and to provide
2449 enhanced management of services.
2450 For more information on systemd, see the systemd
2451 homepage at
2452 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2453 </para>
2454 <para>To enable a service using systemd, your recipe
2455 needs to inherit the
2456 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2457 class.
2458 See the <filename>systemd.bbclass</filename> file
2459 located in your
2460 <link linkend='source-directory'>Source Directory</link>.
2461 section for more information.
2462 </para></listitem>
2463 </itemizedlist>
2464 </para>
2465 </section>
2466
2467 <section id='new-recipe-packaging'>
2468 <title>Packaging</title>
2469
2470 <para>
2471 Successful packaging is a combination of automated processes
2472 performed by the OpenEmbedded build system and some
2473 specific steps you need to take.
2474 The following list describes the process:
2475 <itemizedlist>
2476 <listitem><para><emphasis>Splitting Files</emphasis>:
2477 The <filename>do_package</filename> task splits the
2478 files produced by the recipe into logical components.
2479 Even software that produces a single binary might
2480 still have debug symbols, documentation, and other
2481 logical components that should be split out.
2482 The <filename>do_package</filename> task ensures
2483 that files are split up and packaged correctly.
2484 </para></listitem>
2485 <listitem><para><emphasis>Running QA Checks</emphasis>:
2486 The
2487 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2488 class adds a step to
2489 the package generation process so that output quality
2490 assurance checks are generated by the OpenEmbedded
2491 build system.
2492 This step performs a range of checks to be sure the
2493 build's output is free of common problems that show
2494 up during runtime.
2495 For information on these checks, see the
2496 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2497 class and the
2498 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
2499 chapter in the Yocto Project Reference Manual.
2500 </para></listitem>
2501 <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
2502 After you build your software, you need to be sure
2503 your packages are correct.
2504 Examine the
2505 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2506 directory and make sure files are where you expect
2507 them to be.
2508 If you discover problems, you can set
2509 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2510 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2511 <filename>do_install(_append)</filename>, and so forth as
2512 needed.
2513 </para></listitem>
2514 <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
2515 If you need to split an application into several
2516 packages, see the
2517 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2518 section for an example.
2519 </para></listitem>
2520 <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
2521 For an example showing how to install a
2522 post-installation script, see the
2523 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2524 section.
2525 </para></listitem>
2526 <listitem><para><emphasis>Marking Package Architecture</emphasis>:
2527 Depending on what your recipe is building and how it
2528 is configured, it might be important to mark the
2529 packages produced as being specific to a particular
2530 machine, or to mark them as not being specific to
2531 a particular machine or architecture at all.
2532 By default, packages produced for the target are
2533 marked as being specific to the architecture of the
2534 target machine because that is usually the desired
2535 result.
2536 However, if the recipe configures the software to be
2537 built specific to the target machine (e.g. the
2538 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2539 value is passed into the configure script or a patch
2540 is applied only for a particular machine), then you
2541 should mark the packages produced as being
2542 machine-specific by adding the following to the
2543 recipe:
2544 <literallayout class='monospaced'>
2545 PACKAGE_ARCH = "${MACHINE_ARCH}"
2546 </literallayout>
2547 On the other hand, if the recipe produces packages
2548 that do not contain anything specific to the target
2549 machine or architecture at all (e.g. recipes
2550 that simply package script files or configuration
2551 files), you should use the
2552 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
2553 class to do this for you by adding this to your
2554 recipe:
2555 <literallayout class='monospaced'>
2556 inherit allarch
2557 </literallayout>
2558 Ensuring that the package architecture is correct is
2559 not critical while you are doing the first few builds
2560 of your recipe.
2561 However, it is important in order
2562 to ensure that your recipe rebuilds (or does not
2563 rebuild) appropriately in response to changes in
2564 configuration, and to ensure that you get the
2565 appropriate packages installed on the target machine,
2566 particularly if you run separate builds for more
2567 than one target machine.
2568 </para></listitem>
2569 </itemizedlist>
2570 </para>
2571 </section>
2572
2573 <section id='properly-versioning-pre-release-recipes'>
2574 <title>Properly Versioning Pre-Release Recipes</title>
2575
2576 <para>
2577 Sometimes the name of a recipe can lead to versioning
2578 problems when the recipe is upgraded to a final release.
2579 For example, consider the
2580 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2581 the list of example recipes in the
2582 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2583 section.
2584 This recipe is at a release candidate stage (i.e.
2585 "rc1").
2586 When the recipe is released, the recipe filename becomes
2587 <filename>irssi_0.8.16.bb</filename>.
2588 The version change from <filename>0.8.16-rc1</filename>
2589 to <filename>0.8.16</filename> is seen as a decrease by the
2590 build system and package managers, so the resulting packages
2591 will not correctly trigger an upgrade.
2592 </para>
2593
2594 <para>
2595 In order to ensure the versions compare properly, the
2596 recommended convention is to set
2597 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2598 within the recipe to
2599 "<replaceable>previous_version</replaceable>+<replaceable>current_version</replaceable>".
2600 You can use an additional variable so that you can use the
2601 current version elsewhere.
2602 Here is an example:
2603 <literallayout class='monospaced'>
2604 REALPV = "0.8.16-rc1"
2605 PV = "0.8.15+${REALPV}"
2606 </literallayout>
2607 </para>
2608 </section>
2609
2610 <section id='new-recipe-post-installation-scripts'>
2611 <title>Post-Installation Scripts</title>
2612
2613 <para>
2614 Post-installation scripts run immediately after installing
2615 a package on the target or during image creation when a
2616 package is included in an image.
2617 To add a post-installation script to a package, add a
2618 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2619 the recipe file (<filename>.bb</filename>) and replace
2620 <filename>PACKAGENAME</filename> with the name of the package
2621 you want to attach to the <filename>postinst</filename>
2622 script.
2623 To apply the post-installation script to the main package
2624 for the recipe, which is usually what is required, specify
2625 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2626 in place of <filename>PACKAGENAME</filename>.
2627 </para>
2628
2629 <para>
2630 A post-installation function has the following structure:
2631 <literallayout class='monospaced'>
2632 pkg_postinst_PACKAGENAME() {
2633 #!/bin/sh -e
2634 # Commands to carry out
2635 }
2636 </literallayout>
2637 </para>
2638
2639 <para>
2640 The script defined in the post-installation function is
2641 called when the root filesystem is created.
2642 If the script succeeds, the package is marked as installed.
2643 If the script fails, the package is marked as unpacked and
2644 the script is executed when the image boots again.
2645 </para>
2646
2647 <para>
2648 Sometimes it is necessary for the execution of a
2649 post-installation script to be delayed until the first boot.
2650 For example, the script might need to be executed on the
2651 device itself.
2652 To delay script execution until boot time, use the following
2653 structure in the post-installation script:
2654 <literallayout class='monospaced'>
2655 pkg_postinst_PACKAGENAME() {
2656 #!/bin/sh -e
2657 if [ x"$D" = "x" ]; then
2658 # Actions to carry out on the device go here
2659 else
2660 exit 1
2661 fi
2662 }
2663 </literallayout>
2664 </para>
2665
2666 <para>
2667 The previous example delays execution until the image boots
2668 again because the environment variable <filename>D</filename>
2669 points to the directory containing the image when
2670 the root filesystem is created at build time but is unset
2671 when executed on the first boot.
2672 </para>
2673
2674 <note>
2675 Equivalent support for pre-install, pre-uninstall, and
2676 post-uninstall scripts exist by way of
2677 <filename>pkg_preinst</filename>,
2678 <filename>pkg_prerm</filename>, and
2679 <filename>pkg_postrm</filename>, respectively.
2680 These scrips work in exactly the same way as does
2681 <filename>pkg_postinst</filename> with the exception that they
2682 run at different times.
2683 Also, because of when they run, they are not applicable to
2684 being run at image creation time like
2685 <filename>pkg_postinst</filename>.
2686 </note>
2687 </section>
2688
2689 <section id='new-recipe-testing'>
2690 <title>Testing</title>
2691
2692 <para>
2693 The final step for completing your recipe is to be sure that
2694 the software you built runs correctly.
2695 To accomplish runtime testing, add the build's output
2696 packages to your image and test them on the target.
2697 </para>
2698
2699 <para>
2700 For information on how to customize your image by adding
2701 specific packages, see the
2702 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2703 section.
2704 </para>
2705 </section>
2706
2707 <section id='new-recipe-testing-examples'>
2708 <title>Examples</title>
2709
2710 <para>
2711 To help summarize how to write a recipe, this section provides
2712 some examples given various scenarios:
2713 <itemizedlist>
2714 <listitem><para>Recipes that use local files</para></listitem>
2715 <listitem><para>Using an Autotooled package</para></listitem>
2716 <listitem><para>Using a Makefile-based package</para></listitem>
2717 <listitem><para>Splitting an application into multiple packages</para></listitem>
2718 <listitem><para>Adding binaries to an image</para></listitem>
2719 </itemizedlist>
2720 </para>
2721
2722 <section id='new-recipe-single-c-file-package-hello-world'>
2723 <title>Single .c File Package (Hello World!)</title>
2724
2725 <para>
2726 Building an application from a single file that is stored
2727 locally (e.g. under <filename>files</filename>) requires
2728 a recipe that has the file listed in the
2729 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2730 variable.
2731 Additionally, you need to manually write the
2732 <filename>do_compile</filename> and
2733 <filename>do_install</filename> tasks.
2734 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2735 variable defines the directory containing the source code,
2736 which is set to
2737 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2738 in this case - the directory BitBake uses for the build.
2739 <literallayout class='monospaced'>
2740 SUMMARY = "Simple helloworld application"
2741 SECTION = "examples"
2742 LICENSE = "MIT"
2743 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2744
2745 SRC_URI = "file://helloworld.c"
2746
2747 S = "${WORKDIR}"
2748
2749 do_compile() {
2750 ${CC} helloworld.c -o helloworld
2751 }
2752
2753 do_install() {
2754 install -d ${D}${bindir}
2755 install -m 0755 helloworld ${D}${bindir}
2756 }
2757 </literallayout>
2758 </para>
2759
2760 <para>
2761 By default, the <filename>helloworld</filename>,
2762 <filename>helloworld-dbg</filename>, and
2763 <filename>helloworld-dev</filename> packages are built.
2764 For information on how to customize the packaging process,
2765 see the
2766 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2767 section.
2768 </para>
2769 </section>
2770
2771 <section id='new-recipe-autotooled-package'>
2772 <title>Autotooled Package</title>
2773 <para>
2774 Applications that use Autotools such as <filename>autoconf</filename> and
2775 <filename>automake</filename> require a recipe that has a source archive listed in
2776 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2777 also inherit the
2778 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2779 class, which contains the definitions of all the steps
2780 needed to build an Autotool-based application.
2781 The result of the build is automatically packaged.
2782 And, if the application uses NLS for localization, packages with local information are
2783 generated (one package per language).
2784 Following is one example: (<filename>hello_2.3.bb</filename>)
2785 <literallayout class='monospaced'>
2786 SUMMARY = "GNU Helloworld application"
2787 SECTION = "examples"
2788 LICENSE = "GPLv2+"
2789 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2790
2791 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2792
2793 inherit autotools gettext
2794 </literallayout>
2795 </para>
2796
2797 <para>
2798 The variable
2799 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2800 is used to track source license changes as described in the
2801 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2802 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2803 </para>
2804 </section>
2805
2806 <section id='new-recipe-makefile-based-package'>
2807 <title>Makefile-Based Package</title>
2808
2809 <para>
2810 Applications that use GNU <filename>make</filename> also require a recipe that has
2811 the source archive listed in
2812 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2813 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2814 starts the <filename>make</filename> command to compile the application.
2815 If you need additional <filename>make</filename> options, you should store them in the
2816 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2817 variable.
2818 BitBake passes these options into the GNU <filename>make</filename> invocation.
2819 Note that a <filename>do_install</filename> task is still required.
2820 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2821 </para>
2822
2823 <para>
2824 Some applications might require extra parameters to be passed to the compiler.
2825 For example, the application might need an additional header path.
2826 You can accomplish this by adding to the
2827 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2828 The following example shows this:
2829 <literallayout class='monospaced'>
2830 CFLAGS_prepend = "-I ${S}/include "
2831 </literallayout>
2832 </para>
2833
2834 <para>
2835 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2836 <literallayout class='monospaced'>
2837 SUMMARY = "Tools for managing memory technology devices"
2838 SECTION = "base"
2839 DEPENDS = "zlib lzo e2fsprogs util-linux"
2840 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2841 LICENSE = "GPLv2+"
2842 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2843 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2844
2845 # Use the latest version at 26 Oct, 2013
2846 SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b"
2847 SRC_URI = "git://git.infradead.org/mtd-utils.git \
2848 file://add-exclusion-to-mkfs-jffs2-git-2.patch \
2849 "
2850
2851 PV = "1.5.1+git${SRCPV}"
2852
2853 S = "${WORKDIR}/git/"
2854
2855 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2856
2857 do_install () {
2858 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir}
2859 }
2860
2861 PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc"
2862
2863 FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool"
2864 FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*"
2865 FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image"
2866
2867 PARALLEL_MAKE = ""
2868
2869 BBCLASSEXTEND = "native"
2870 </literallayout>
2871 </para>
2872 </section>
2873
2874 <section id='splitting-an-application-into-multiple-packages'>
2875 <title>Splitting an Application into Multiple Packages</title>
2876
2877 <para>
2878 You can use the variables
2879 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2880 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2881 to split an application into multiple packages.
2882 </para>
2883
2884 <para>
2885 Following is an example that uses the <filename>libxpm</filename> recipe.
2886 By default, this recipe generates a single package that contains the library along
2887 with a few binaries.
2888 You can modify the recipe to split the binaries into separate packages:
2889 <literallayout class='monospaced'>
2890 require xorg-lib-common.inc
2891
2892 SUMMARY = "X11 Pixmap library"
2893 LICENSE = "X-BSD"
2894 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2895 DEPENDS += "libxext libsm libxt"
2896 PR = "r3"
2897 PE = "1"
2898
2899 XORG_PN = "libXpm"
2900
2901 PACKAGES =+ "sxpm cxpm"
2902 FILES_cxpm = "${bindir}/cxpm"
2903 FILES_sxpm = "${bindir}/sxpm"
2904 </literallayout>
2905 </para>
2906
2907 <para>
2908 In the previous example, we want to ship the <filename>sxpm</filename>
2909 and <filename>cxpm</filename> binaries in separate packages.
2910 Since <filename>bindir</filename> would be packaged into the main
2911 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2912 package by default, we prepend the <filename>PACKAGES</filename>
2913 variable so additional package names are added to the start of list.
2914 This results in the extra <filename>FILES_*</filename>
2915 variables then containing information that define which files and
2916 directories go into which packages.
2917 Files included by earlier packages are skipped by latter packages.
2918 Thus, the main <filename>PN</filename> package
2919 does not include the above listed files.
2920 </para>
2921 </section>
2922
2923 <section id='packaging-externally-produced-binaries'>
2924 <title>Packaging Externally Produced Binaries</title>
2925
2926 <para>
2927 Sometimes, you need to add pre-compiled binaries to an
2928 image.
2929 For example, suppose that binaries for proprietary code
2930 exist, which are created by a particular division of a
2931 company.
2932 Your part of the company needs to use those binaries as
2933 part of an image that you are building using the
2934 OpenEmbedded build system.
2935 Since you only have the binaries and not the source code,
2936 you cannot use a typical recipe that expects to fetch the
2937 source specified in
2938 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2939 and then compile it.
2940 </para>
2941
2942 <para>
2943 One method is to package the binaries and then install them
2944 as part of the image.
2945 Generally, it is not a good idea to package binaries
2946 since, among other things, it can hinder the ability to
2947 reproduce builds and could lead to compatibility problems
2948 with ABI in the future.
2949 However, sometimes you have no choice.
2950 </para>
2951
2952 <para>
2953 The easiest solution is to create a recipe that uses
2954 the
2955 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-bin-package'><filename>bin_package</filename></ulink>
2956 class and to be sure that you are using default locations
2957 for build artifacts.
2958 In most cases, the <filename>bin_package</filename> class
2959 handles "skipping" the configure and compile steps as well
2960 as sets things up to grab packages from the appropriate
2961 area.
2962 In particular, this class sets <filename>noexec</filename>
2963 on both the
2964 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2965 and
2966 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2967 tasks, sets
2968 <filename>FILES_${PN}</filename> to "/" so that it picks
2969 up all files, and sets up a
2970 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
2971 task, which effectively copies all files from
2972 <filename>${S}</filename> to <filename>${D}</filename>.
2973 The <filename>bin_package</filename> class works well when
2974 the files extracted into <filename>${S}</filename> are
2975 already laid out in the way they should be laid out
2976 on the target.
2977 For more information on these variables, see the
2978 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2979 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
2980 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>,
2981 and
2982 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
2983 variables in the Yocto Project Reference Manual's variable
2984 glossary.
2985 </para>
2986
2987 <para>
2988 If you can't use the <filename>bin_package</filename>
2989 class, you need to be sure you are doing the following:
2990 <itemizedlist>
2991 <listitem><para>Create a recipe where the
2992 <filename>do_configure</filename> and
2993 <filename>do_compile</filename> tasks do nothing:
2994 <literallayout class='monospaced'>
2995 do_configure[noexec] = "1"
2996 do_compile[noexec] = "1"
2997 </literallayout>
2998 Alternatively, you can make these tasks an empty
2999 function.
3000 </para></listitem>
3001 <listitem><para>Make sure your
3002 <filename>do_install</filename> task installs the
3003 binaries appropriately.
3004 </para></listitem>
3005 <listitem><para>Ensure that you set up
3006 <filename>FILES</filename> (usually
3007 <filename>FILES_${PN}</filename>) to point to the
3008 files you have installed, which of course depends
3009 on where you have installed them and whether
3010 those files are in different locations than the
3011 defaults.
3012 </para></listitem>
3013 </itemizedlist>
3014 </para>
3015 </section>
3016 </section>
3017 </section>
3018
3019 <section id="platdev-newmachine">
3020 <title>Adding a New Machine</title>
3021
3022 <para>
3023 Adding a new machine to the Yocto Project is a straightforward
3024 process.
3025 This section describes how to add machines that are similar
3026 to those that the Yocto Project already supports.
3027 <note>
3028 Although well within the capabilities of the Yocto Project,
3029 adding a totally new architecture might require
3030 changes to <filename>gcc/glibc</filename> and to the site
3031 information, which is beyond the scope of this manual.
3032 </note>
3033 </para>
3034
3035 <para>
3036 For a complete example that shows how to add a new machine,
3037 see the
3038 "<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>"
3039 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
3040 </para>
3041
3042 <section id="platdev-newmachine-conffile">
3043 <title>Adding the Machine Configuration File</title>
3044
3045 <para>
3046 To add a new machine, you need to add a new machine
3047 configuration file to the layer's
3048 <filename>conf/machine</filename> directory.
3049 This configuration file provides details about the device
3050 you are adding.
3051 </para>
3052
3053 <para>
3054 The OpenEmbedded build system uses the root name of the
3055 machine configuration file to reference the new machine.
3056 For example, given a machine configuration file named
3057 <filename>crownbay.conf</filename>, the build system
3058 recognizes the machine as "crownbay".
3059 </para>
3060
3061 <para>
3062 The most important variables you must set in your machine
3063 configuration file or include from a lower-level configuration
3064 file are as follows:
3065 <itemizedlist>
3066 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
3067 (e.g. "arm")</para></listitem>
3068 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
3069 </para></listitem>
3070 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
3071 (e.g. "apm screen wifi")</para></listitem>
3072 </itemizedlist>
3073 </para>
3074
3075 <para>
3076 You might also need these variables:
3077 <itemizedlist>
3078 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
3079 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
3080 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
3081 (e.g. "zImage")</para></listitem>
3082 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
3083 (e.g. "tar.gz jffs2")</para></listitem>
3084 </itemizedlist>
3085 </para>
3086
3087 <para>
3088 You can find full details on these variables in the reference
3089 section.
3090 You can leverage existing machine <filename>.conf</filename>
3091 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
3092 </para>
3093 </section>
3094
3095 <section id="platdev-newmachine-kernel">
3096 <title>Adding a Kernel for the Machine</title>
3097
3098 <para>
3099 The OpenEmbedded build system needs to be able to build a kernel
3100 for the machine.
3101 You need to either create a new kernel recipe for this machine,
3102 or extend an existing kernel recipe.
3103 You can find several kernel recipe examples in the
3104 Source Directory at
3105 <filename>meta/recipes-kernel/linux</filename>
3106 that you can use as references.
3107 </para>
3108
3109 <para>
3110 If you are creating a new kernel recipe, normal recipe-writing
3111 rules apply for setting up a
3112 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
3113 Thus, you need to specify any necessary patches and set
3114 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
3115 to point at the source code.
3116 You need to create a <filename>do_configure</filename> task that
3117 configures the unpacked kernel with a
3118 <filename>defconfig</filename> file.
3119 You can do this by using a <filename>make defconfig</filename>
3120 command or, more commonly, by copying in a suitable
3121 <filename>defconfig</filename> file and then running
3122 <filename>make oldconfig</filename>.
3123 By making use of <filename>inherit kernel</filename> and
3124 potentially some of the <filename>linux-*.inc</filename> files,
3125 most other functionality is centralized and the defaults of the
3126 class normally work well.
3127 </para>
3128
3129 <para>
3130 If you are extending an existing kernel recipe, it is usually
3131 a matter of adding a suitable <filename>defconfig</filename>
3132 file.
3133 The file needs to be added into a location similar to
3134 <filename>defconfig</filename> files used for other machines
3135 in a given kernel recipe.
3136 A possible way to do this is by listing the file in the
3137 <filename>SRC_URI</filename> and adding the machine to the
3138 expression in
3139 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
3140 <literallayout class='monospaced'>
3141 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
3142 </literallayout>
3143 </para>
3144 </section>
3145
3146 <section id="platdev-newmachine-formfactor">
3147 <title>Adding a Formfactor Configuration File</title>
3148
3149 <para>
3150 A formfactor configuration file provides information about the
3151 target hardware for which the image is being built and information that
3152 the build system cannot obtain from other sources such as the kernel.
3153 Some examples of information contained in a formfactor configuration file include
3154 framebuffer orientation, whether or not the system has a keyboard,
3155 the positioning of the keyboard in relation to the screen, and
3156 the screen resolution.
3157 </para>
3158
3159 <para>
3160 The build system uses reasonable defaults in most cases.
3161 However, if customization is
3162 necessary, you need to create a <filename>machconfig</filename> file
3163 in the <filename>meta/recipes-bsp/formfactor/files</filename>
3164 directory.
3165 This directory contains directories for specific machines such as
3166 <filename>qemuarm</filename> and <filename>qemux86</filename>.
3167 For information about the settings available and the defaults, see the
3168 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
3169 same area.
3170 </para>
3171
3172 <para>
3173 Following is an example for "qemuarm" machine:
3174 <literallayout class='monospaced'>
3175 HAVE_TOUCHSCREEN=1
3176 HAVE_KEYBOARD=1
3177
3178 DISPLAY_CAN_ROTATE=0
3179 DISPLAY_ORIENTATION=0
3180 #DISPLAY_WIDTH_PIXELS=640
3181 #DISPLAY_HEIGHT_PIXELS=480
3182 #DISPLAY_BPP=16
3183 DISPLAY_DPI=150
3184 DISPLAY_SUBPIXEL_ORDER=vrgb
3185 </literallayout>
3186 </para>
3187 </section>
3188 </section>
3189
3190 <section id="platdev-working-with-libraries">
3191 <title>Working With Libraries</title>
3192
3193 <para>
3194 Libraries are an integral part of your system.
3195 This section describes some common practices you might find
3196 helpful when working with libraries to build your system:
3197 <itemizedlist>
3198 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
3199 </para></listitem>
3200 <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>
3201 </para></listitem>
3202 <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>
3203 </para></listitem>
3204 </itemizedlist>
3205 </para>
3206
3207 <section id='including-static-library-files'>
3208 <title>Including Static Library Files</title>
3209
3210 <para>
3211 If you are building a library and the library offers static linking, you can control
3212 which static library files (<filename>*.a</filename> files) get included in the
3213 built library.
3214 </para>
3215
3216 <para>
3217 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
3218 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
3219 variables in the
3220 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
3221 by the <filename>do_install</filename> task are packaged.
3222 By default, the <filename>PACKAGES</filename> variable includes
3223 <filename>${PN}-staticdev</filename>, which represents all static library files.
3224 <note>
3225 Some previously released versions of the Yocto Project
3226 defined the static library files through
3227 <filename>${PN}-dev</filename>.
3228 </note>
3229 Following is part of the BitBake configuration file, where
3230 you can see how the static library files are defined:
3231 <literallayout class='monospaced'>
3232 PACKAGE_BEFORE_PN ?= ""
3233 PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}"
3234 PACKAGES_DYNAMIC = "^${PN}-locale-.*"
3235 FILES = ""
3236
3237 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
3238 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
3239 ${base_bindir}/* ${base_sbindir}/* \
3240 ${base_libdir}/*${SOLIBS} \
3241 ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \
3242 ${datadir}/${BPN} ${libdir}/${BPN}/* \
3243 ${datadir}/pixmaps ${datadir}/applications \
3244 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
3245 ${libdir}/bonobo/servers"
3246
3247 FILES_${PN}-bin = "${bindir}/* ${sbindir}/*"
3248
3249 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
3250 ${datadir}/gnome/help"
3251 SECTION_${PN}-doc = "doc"
3252
3253 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
3254 FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \
3255 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
3256 ${datadir}/aclocal ${base_libdir}/*.o \
3257 ${libdir}/${BPN}/*.la ${base_libdir}/*.la"
3258 SECTION_${PN}-dev = "devel"
3259 ALLOW_EMPTY_${PN}-dev = "1"
3260 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
3261
3262 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a"
3263 SECTION_${PN}-staticdev = "devel"
3264 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
3265 </literallayout>
3266 </para>
3267 </section>
3268
3269 <section id="combining-multiple-versions-library-files-into-one-image">
3270 <title>Combining Multiple Versions of Library Files into One Image</title>
3271
3272 <para>
3273 The build system offers the ability to build libraries with different
3274 target optimizations or architecture formats and combine these together
3275 into one system image.
3276 You can link different binaries in the image
3277 against the different libraries as needed for specific use cases.
3278 This feature is called "Multilib."
3279 </para>
3280
3281 <para>
3282 An example would be where you have most of a system compiled in 32-bit
3283 mode using 32-bit libraries, but you have something large, like a database
3284 engine, that needs to be a 64-bit application and uses 64-bit libraries.
3285 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
3286 </para>
3287
3288 <para>
3289 While the Multilib feature is most commonly used for 32 and 64-bit differences,
3290 the approach the build system uses facilitates different target optimizations.
3291 You could compile some binaries to use one set of libraries and other binaries
3292 to use a different set of libraries.
3293 The libraries could differ in architecture, compiler options, or other
3294 optimizations.
3295 </para>
3296
3297 <para>
3298 This section overviews the Multilib process only.
3299 For more details on how to implement Multilib, see the
3300 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
3301 page.
3302 </para>
3303
3304 <para>
3305 Aside from this wiki page, several examples exist in the
3306 <filename>meta-skeleton</filename> layer found in the
3307 <link linkend='source-directory'>Source Directory</link>:
3308 <itemizedlist>
3309 <listitem><para><filename>conf/multilib-example.conf</filename>
3310 configuration file</para></listitem>
3311 <listitem><para><filename>conf/multilib-example2.conf</filename>
3312 configuration file</para></listitem>
3313 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
3314 recipe</para></listitem>
3315 </itemizedlist>
3316 </para>
3317
3318 <section id='preparing-to-use-multilib'>
3319 <title>Preparing to Use Multilib</title>
3320
3321 <para>
3322 User-specific requirements drive the Multilib feature.
3323 Consequently, there is no one "out-of-the-box" configuration that likely
3324 exists to meet your needs.
3325 </para>
3326
3327 <para>
3328 In order to enable Multilib, you first need to ensure your recipe is
3329 extended to support multiple libraries.
3330 Many standard recipes are already extended and support multiple libraries.
3331 You can check in the <filename>meta/conf/multilib.conf</filename>
3332 configuration file in the
3333 <link linkend='source-directory'>Source Directory</link> to see how this is
3334 done using the
3335 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
3336 variable.
3337 Eventually, all recipes will be covered and this list will
3338 not be needed.
3339 </para>
3340
3341 <para>
3342 For the most part, the Multilib class extension works automatically to
3343 extend the package name from <filename>${PN}</filename> to
3344 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
3345 is the particular multilib (e.g. "lib32-" or "lib64-").
3346 Standard variables such as
3347 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
3348 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
3349 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
3350 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
3351 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, and
3352 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink>
3353 are automatically extended by the system.
3354 If you are extending any manual code in the recipe, you can use the
3355 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
3356 correctly.
3357 This automatic extension code resides in <filename>multilib.bbclass</filename>.
3358 </para>
3359 </section>
3360
3361 <section id='using-multilib'>
3362 <title>Using Multilib</title>
3363
3364 <para>
3365 After you have set up the recipes, you need to define the actual
3366 combination of multiple libraries you want to build.
3367 You accomplish this through your <filename>local.conf</filename>
3368 configuration file in the
3369 <link linkend='build-directory'>Build Directory</link>.
3370 An example configuration would be as follows:
3371 <literallayout class='monospaced'>
3372 MACHINE = "qemux86-64"
3373 require conf/multilib.conf
3374 MULTILIBS = "multilib:lib32"
3375 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
3376 IMAGE_INSTALL = "lib32-connman"
3377 </literallayout>
3378 This example enables an
3379 additional library named <filename>lib32</filename> alongside the
3380 normal target packages.
3381 When combining these "lib32" alternatives, the example uses "x86" for tuning.
3382 For information on this particular tuning, see
3383 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
3384 </para>
3385
3386 <para>
3387 The example then includes <filename>lib32-connman</filename>
3388 in all the images, which illustrates one method of including a
3389 multiple library dependency.
3390 You can use a normal image build to include this dependency,
3391 for example:
3392 <literallayout class='monospaced'>
3393 $ bitbake core-image-sato
3394 </literallayout>
3395 You can also build Multilib packages specifically with a command like this:
3396 <literallayout class='monospaced'>
3397 $ bitbake lib32-connman
3398 </literallayout>
3399 </para>
3400 </section>
3401
3402 <section id='additional-implementation-details'>
3403 <title>Additional Implementation Details</title>
3404
3405 <para>
3406 Different packaging systems have different levels of native Multilib
3407 support.
3408 For the RPM Package Management System, the following implementation details
3409 exist:
3410 <itemizedlist>
3411 <listitem><para>A unique architecture is defined for the Multilib packages,
3412 along with creating a unique deploy folder under
3413 <filename>tmp/deploy/rpm</filename> in the
3414 <link linkend='build-directory'>Build Directory</link>.
3415 For example, consider <filename>lib32</filename> in a
3416 <filename>qemux86-64</filename> image.
3417 The possible architectures in the system are "all", "qemux86_64",
3418 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
3419 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
3420 <filename>${PN}</filename> during RPM packaging.
3421 The naming for a normal RPM package and a Multilib RPM package in a
3422 <filename>qemux86-64</filename> system resolves to something similar to
3423 <filename>bash-4.1-r2.x86_64.rpm</filename> and
3424 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
3425 </para></listitem>
3426 <listitem><para>When installing a Multilib image, the RPM backend first
3427 installs the base image and then installs the Multilib libraries.
3428 </para></listitem>
3429 <listitem><para>The build system relies on RPM to resolve the identical files in the
3430 two (or more) Multilib packages.</para></listitem>
3431 </itemizedlist>
3432 </para>
3433
3434 <para>
3435 For the IPK Package Management System, the following implementation details exist:
3436 <itemizedlist>
3437 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
3438 <filename>${PN}</filename> during IPK packaging.
3439 The naming for a normal RPM package and a Multilib IPK package in a
3440 <filename>qemux86-64</filename> system resolves to something like
3441 <filename>bash_4.1-r2.x86_64.ipk</filename> and
3442 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
3443 </para></listitem>
3444 <listitem><para>The IPK deploy folder is not modified with
3445 <filename>${MLPREFIX}</filename> because packages with and without
3446 the Multilib feature can exist in the same folder due to the
3447 <filename>${PN}</filename> differences.</para></listitem>
3448 <listitem><para>IPK defines a sanity check for Multilib installation
3449 using certain rules for file comparison, overridden, etc.
3450 </para></listitem>
3451 </itemizedlist>
3452 </para>
3453 </section>
3454 </section>
3455
3456 <section id='installing-multiple-versions-of-the-same-library'>
3457 <title>Installing Multiple Versions of the Same Library</title>
3458
3459 <para>
3460 Situations can exist where you need to install and use
3461 multiple versions of the same library on the same system
3462 at the same time.
3463 These situations almost always exist when a library API
3464 changes and you have multiple pieces of software that
3465 depend on the separate versions of the library.
3466 To accommodate these situations, you can install multiple
3467 versions of the same library in parallel on the same system.
3468 </para>
3469
3470 <para>
3471 The process is straightforward as long as the libraries use
3472 proper versioning.
3473 With properly versioned libraries, all you need to do to
3474 individually specify the libraries is create separate,
3475 appropriately named recipes where the
3476 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
3477 name includes a portion that differentiates each library version
3478 (e.g.the major part of the version number).
3479 Thus, instead of having a single recipe that loads one version
3480 of a library (e.g. <filename>clutter</filename>), you provide
3481 multiple recipes that result in different versions
3482 of the libraries you want.
3483 As an example, the following two recipes would allow the
3484 two separate versions of the <filename>clutter</filename>
3485 library to co-exist on the same system:
3486 <literallayout class='monospaced'>
3487 clutter-1.6_1.6.20.bb
3488 clutter-1.8_1.8.4.bb
3489 </literallayout>
3490 Additionally, if you have other recipes that depend on a given
3491 library, you need to use the
3492 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
3493 variable to create the dependency.
3494 Continuing with the same example, if you want to have a recipe
3495 depend on the 1.8 version of the <filename>clutter</filename>
3496 library, use the following in your recipe:
3497 <literallayout class='monospaced'>
3498 DEPENDS = "clutter-1.8"
3499 </literallayout>
3500 </para>
3501 </section>
3502 </section>
3503
3504 <section id='creating-partitioned-images'>
3505 <title>Creating Partitioned Images</title>
3506
3507 <para>
3508 Creating an image for a particular hardware target using the
3509 OpenEmbedded build system does not necessarily mean you can boot
3510 that image as is on your device.
3511 Physical devices accept and boot images in various ways depending
3512 on the specifics of the device.
3513 Usually, information about the hardware can tell you what image
3514 format the device requires.
3515 Should your device require multiple partitions on an SD card, flash,
3516 or an HDD, you can use the OpenEmbedded Image Creator,
3517 <filename>wic</filename>, to create the properly partitioned image.
3518 </para>
3519
3520 <para>
3521 The <filename>wic</filename> command generates partitioned images
3522 from existing OpenEmbedded build artifacts.
3523 Image generation is driven by partitioning commands contained
3524 in an Openembedded kickstart file (<filename>.wks</filename>)
3525 specified either directly on the command line or as one of a
3526 selection of canned <filename>.wks</filename> files as shown
3527 with the <filename>wic list images</filename> command in the
3528 "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>"
3529 section.
3530 When applied to a given set of build artifacts, the result is an
3531 image or set of images that can be directly written onto media and
3532 used on a particular system.
3533 </para>
3534
3535 <para>
3536 The <filename>wic</filename> command and the infrastructure
3537 it is based on is by definition incomplete.
3538 Its purpose is to allow the generation of customized images,
3539 and as such was designed to be completely extensible through a
3540 plugin interface.
3541 See the
3542 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
3543 section for information on these plugins.
3544 </para>
3545
3546 <para>
3547 This section provides some background information on
3548 <filename>wic</filename>, describes what you need to have in
3549 place to run the tool, provides instruction on how to use
3550 <filename>wic</filename>, and provides several examples.
3551 </para>
3552
3553 <section id='wic-background'>
3554 <title>Background</title>
3555
3556 <para>
3557 This section provides some background on the
3558 <filename>wic</filename> utility.
3559 While none of this information is required to use
3560 <filename>wic</filename>, you might find it interesting.
3561 <itemizedlist>
3562 <listitem><para>
3563 The name "wic" is derived from OpenEmbedded
3564 Image Creator (oeic).
3565 The "oe" diphthong in "oeic" was promoted to the
3566 letter "w", because "oeic" is both difficult to remember and
3567 pronounce.</para></listitem>
3568 <listitem><para>
3569 <filename>wic</filename> is loosely based on the
3570 Meego Image Creator (<filename>mic</filename>)
3571 framework.
3572 The <filename>wic</filename> implementation has been
3573 heavily modified to make direct use of OpenEmbedded
3574 build artifacts instead of package installation and
3575 configuration, which are already incorporated within
3576 the OpenEmbedded artifacts.</para></listitem>
3577 <listitem><para>
3578 <filename>wic</filename> is a completely independent
3579 standalone utility that initially provides
3580 easier-to-use and more flexible replacements for a
3581 couple bits of existing functionality in OE Core's
3582 <filename>boot-directdisk.bbclass</filename> and
3583 <filename>mkefidisk.sh</filename> scripts.
3584 The difference between
3585 <filename>wic</filename> and those examples is
3586 that with <filename>wic</filename> the
3587 functionality of those scripts is implemented
3588 by a general-purpose partitioning language, which is
3589 based on Redhat kickstart syntax.</para></listitem>
3590 </itemizedlist>
3591 </para>
3592 </section>
3593
3594 <section id='wic-requirements'>
3595 <title>Requirements</title>
3596
3597 <para>
3598 In order to use the <filename>wic</filename> utility
3599 with the OpenEmbedded Build system, your system needs
3600 to meet the following requirements:
3601 <itemizedlist>
3602 <listitem><para>The Linux distribution on your
3603 development host must support the Yocto Project.
3604 See the
3605 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
3606 section in the Yocto Project Reference Manual for this
3607 list of distributions.</para></listitem>
3608 <listitem><para>
3609 The standard system utilities, such as
3610 <filename>cp</filename>, must be installed on your
3611 development host system.
3612 </para></listitem>
3613 <listitem><para>
3614 The
3615 <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink>
3616 package must be installed on your development host
3617 system.
3618 </para></listitem>
3619 <listitem><para>
3620 You need to have the build artifacts already
3621 available, which typically means that you must
3622 have already created an image using the
3623 Openembedded build system (e.g.
3624 <filename>core-image-minimal</filename>).
3625 While it might seem redundant to generate an image in
3626 order to create an image using
3627 <filename>wic</filename>, the current version of
3628 <filename>wic</filename> requires the artifacts
3629 in the form generated by the build system.
3630 </para></listitem>
3631 <listitem><para>
3632 You must have sourced one of the build environment
3633 setup scripts (i.e.
3634 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3635 or
3636 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
3637 found in the
3638 <link linkend='build-directory'>Build Directory</link>.
3639 </para></listitem>
3640 </itemizedlist>
3641 </para>
3642 </section>
3643
3644 <section id='wic-getting-help'>
3645 <title>Getting Help</title>
3646
3647 <para>
3648 You can get general help for the <filename>wic</filename>
3649 by entering the <filename>wic</filename> command by itself
3650 or by entering the command with a help argument as follows:
3651 <literallayout class='monospaced'>
3652 $ wic -h
3653 $ wic &dash;&dash;help
3654 </literallayout>
3655 </para>
3656
3657 <para>
3658 Currently, <filename>wic</filename> supports two commands:
3659 <filename>create</filename> and <filename>list</filename>.
3660 You can get help for these commands as follows:
3661 <literallayout class='monospaced'>
3662 $ wic help <replaceable>command</replaceable>
3663 </literallayout>
3664 </para>
3665
3666 <para>
3667 You can also get detailed help on a number of topics
3668 from the help system.
3669 The output of <filename>wic &dash;&dash;help</filename>
3670 displays a list of available help
3671 topics under a "Help topics" heading.
3672 You can have the help system display the help text for
3673 a given topic by prefacing the topic with
3674 <filename>wic help</filename>:
3675 <literallayout class='monospaced'>
3676 $ wic help <replaceable>help_topic</replaceable>
3677 </literallayout>
3678 </para>
3679
3680 <para>
3681 You can find out more about the images
3682 <filename>wic</filename> creates using the existing
3683 kickstart files with the following form of the command:
3684 <literallayout class='monospaced'>
3685 $ wic list <replaceable>image</replaceable> help
3686 </literallayout>
3687 where <filename><replaceable>image</replaceable></filename> is either
3688 <filename>directdisk</filename> or
3689 <filename>mkefidisk</filename>.
3690 </para>
3691 </section>
3692
3693 <section id='operational-modes'>
3694 <title>Operational Modes</title>
3695
3696 <para>
3697 You can use <filename>wic</filename> in two different
3698 modes, depending on how much control you need for
3699 specifying the Openembedded build artifacts that are
3700 used for creating the image: Raw and Cooked:
3701 <itemizedlist>
3702 <listitem><para><emphasis>Raw Mode:</emphasis>
3703 You explicitly specify build artifacts through
3704 command-line arguments.</para></listitem>
3705 <listitem><para><emphasis>Cooked Mode:</emphasis>
3706 The current
3707 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3708 setting and image name are used to automatically locate
3709 and provide the build artifacts.</para></listitem>
3710 </itemizedlist>
3711 </para>
3712
3713 <para>
3714 Regardless of the mode you use, you need to have the build
3715 artifacts ready and available.
3716 Additionally, the environment must be set up using the
3717 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3718 or
3719 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
3720 script found in the
3721 <link linkend='build-directory'>Build Directory</link>.
3722 </para>
3723
3724 <section id='raw-mode'>
3725 <title>Raw Mode</title>
3726
3727 <para>
3728 The general form of the 'wic' command in raw mode is:
3729 <literallayout class='monospaced'>
3730 $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
3731
3732 Where:
3733
3734 <replaceable>image_name</replaceable>.wks
3735 An OpenEmbedded kickstart file. You can provide
3736 your own custom file or use a file from a set of
3737 existing files as described by further options.
3738
3739 -o <replaceable>OUTDIR</replaceable>, &dash;&dash;outdir=<replaceable>OUTDIR</replaceable>
3740 The name of a directory in which to create image.
3741
3742 -i <replaceable>PROPERTIES_FILE</replaceable>, &dash;&dash;infile=<replaceable>PROPERTIES_FILE</replaceable>
3743 The name of a file containing the values for image
3744 properties as a JSON file.
3745
3746 -e <replaceable>IMAGE_NAME</replaceable>, &dash;&dash;image-name=<replaceable>IMAGE_NAME</replaceable>
3747 The name of the image from which to use the artifacts
3748 (e.g. <filename>core-image-sato</filename>).
3749
3750 -r <replaceable>ROOTFS_DIR</replaceable>, &dash;&dash;rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
3751 The path to the <filename>/rootfs</filename> directory to use as the
3752 <filename>.wks</filename> rootfs source.
3753
3754 -b <replaceable>BOOTIMG_DIR</replaceable>, &dash;&dash;bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable>
3755 The path to the directory containing the boot artifacts
3756 (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg
3757 source.
3758
3759 -k <replaceable>KERNEL_DIR</replaceable>, &dash;&dash;kernel-dir=<replaceable>KERNEL_DIR</replaceable>
3760 The path to the directory containing the kernel to use
3761 in the <filename>.wks</filename> boot image.
3762
3763 -n <replaceable>NATIVE_SYSROOT</replaceable>, &dash;&dash;native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable>
3764 The path to the native sysroot containing the tools to use
3765 to build the image.
3766
3767 -s, &dash;&dash;skip-build-check
3768 Skips the build check.
3769
3770 -D, &dash;&dash;debug
3771 Output debug information.
3772 </literallayout>
3773 <note>
3774 You do not need root privileges to run
3775 <filename>wic</filename>.
3776 In fact, you should not run as root when using the
3777 utility.
3778 </note>
3779 </para>
3780 </section>
3781
3782 <section id='cooked-mode'>
3783 <title>Cooked Mode</title>
3784
3785 <para>
3786 The general form of the <filename>wic</filename> command
3787 using Cooked Mode is:
3788 <literallayout class='monospaced'>
3789 $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable>
3790
3791 Where:
3792
3793 <replaceable>kickstart_file</replaceable>
3794 An OpenEmbedded kickstart file. You can provide your own
3795 custom file or supplied file.
3796
3797 <replaceable>image_name</replaceable>
3798 Specifies the image built using the OpenEmbedded build
3799 system.
3800 </literallayout>
3801 This form is the simplest and most user-friendly, as it
3802 does not require specifying all individual parameters.
3803 All you need to provide is your own
3804 <filename>.wks</filename> file or one provided with the
3805 release.
3806 </para>
3807 </section>
3808 </section>
3809
3810 <section id='using-a-provided-kickstart_file'>
3811 <title>Using an Existing Kickstart File</title>
3812
3813 <para>
3814 If you do not want to create your own
3815 <filename>.wks</filename> file, you can use an existing
3816 file provided by the <filename>wic</filename> installation.
3817 Use the following command to list the available files:
3818 <literallayout class='monospaced'>
3819 $ wic list images
3820 directdisk Create a 'pcbios' direct disk image
3821 mkefidisk Create an EFI disk image
3822 </literallayout>
3823 When you use an existing file, you do not have to use the
3824 <filename>.wks</filename> extension.
3825 Here is an example in Raw Mode that uses the
3826 <filename>directdisk</filename> file:
3827 <literallayout class='monospaced'>
3828 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \
3829 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable>
3830 </literallayout>
3831 </para>
3832
3833 <para>
3834 Here are the actual partition language commands
3835 used in the <filename>mkefidisk.wks</filename> file to generate
3836 an image:
3837 <literallayout class='monospaced'>
3838 # short-description: Create an EFI disk image
3839 # long-description: Creates a partitioned EFI disk image that the user
3840 # can directly dd to boot media.
3841
3842 part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024
3843
3844 part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
3845
3846 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
3847
3848 bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0"
3849 </literallayout>
3850 </para>
3851 </section>
3852
3853 <section id='wic-usage-examples'>
3854 <title>Examples</title>
3855
3856 <para>
3857 This section provides several examples that show how to use
3858 the <filename>wic</filename> utility.
3859 All the examples assume the list of requirements in the
3860 "<link linkend='wic-requirements'>Requirements</link>" section
3861 have been met.
3862 The examples assume the previously generated image is
3863 <filename>core-image-minimal</filename>.
3864 </para>
3865
3866 <section id='generate-an-image-using-a-provided-kickstart-file'>
3867 <title>Generate an Image using an Existing Kickstart File</title>
3868
3869 <para>
3870 This example runs in Cooked Mode and uses the
3871 <filename>mkefidisk</filename> kickstart file:
3872 <literallayout class='monospaced'>
3873 $ wic create mkefidisk -e core-image-minimal
3874 Checking basic build environment...
3875 Done.
3876
3877 Creating image(s)...
3878
3879 Info: The new image(s) can be found here:
3880 /var/tmp/wic/build/mkefidisk-201310230946-sda.direct
3881
3882 The following build artifacts were used to create the image(s):
3883 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs
3884 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg
3885 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
3886 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
3887
3888
3889 The image(s) were created using OE kickstart file:
3890 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
3891 </literallayout>
3892 This example shows the easiest way to create an image
3893 by running in Cooked Mode and using the
3894 <filename>-e</filename> option with an existing kickstart
3895 file.
3896 All that is necessary is to specify the image used to
3897 generate the artifacts.
3898 Your <filename>local.conf</filename> needs to have the
3899 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3900 variable set to the machine you are using, which is
3901 "minnow" in this example.
3902 </para>
3903
3904 <para>
3905 The output specifies the exact created as well as where
3906 it was created.
3907 The output also names the artifacts used and the exact
3908 <filename>.wks</filename> script that was used to generate
3909 the image.
3910 <note>
3911 You should always verify the details provided in the
3912 output to make sure that the image was indeed created
3913 exactly as expected.
3914 </note>
3915 </para>
3916
3917 <para>
3918 Continuing with the example, you can now directly
3919 <filename>dd</filename> the image to a USB stick, or
3920 whatever media for which you built your image,
3921 and boot the resulting media:
3922 <literallayout class='monospaced'>
3923 $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
3924 [sudo] password for trz:
3925 182274+0 records in
3926 182274+0 records out
3927 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
3928 [trz@empanada ~]$ sudo eject /dev/sdb
3929 </literallayout>
3930 </para>
3931 </section>
3932
3933 <section id='using-a-modified-kickstart-file'>
3934 <title>Using a Modified Kickstart File</title>
3935
3936 <para>
3937 Because <filename>wic</filename> image creation is driven
3938 by the kickstart file, it is easy to affect image creation
3939 by changing the parameters in the file.
3940 This next example demonstrates that through modification
3941 of the <filename>directdisk</filename> kickstart file.
3942 </para>
3943
3944 <para>
3945 As mentioned earlier, you can use the command
3946 <filename>wic list images</filename> to show the list
3947 of existing kickstart files.
3948 The directory in which these files reside is
3949 <filename>scripts/lib/image/canned-wks/</filename>
3950 located in the
3951 <link linkend='source-directory'>Source Directory</link>.
3952 Because the available files reside in this directory, you
3953 can create and add your own custom files to the directory.
3954 Subsequent use of the <filename>wic list images</filename>
3955 command would then include your kickstart files.
3956 </para>
3957
3958 <para>
3959 In this example, the existing
3960 <filename>directdisk</filename> file already does most
3961 of what is needed.
3962 However, for the hardware in this example, the image will
3963 need to boot from <filename>sdb</filename> instead of
3964 <filename>sda</filename>, which is what the
3965 <filename>directdisk</filename> kickstart file uses.
3966 </para>
3967
3968 <para>
3969 The example begins by making a copy of the
3970 <filename>directdisk.wks</filename> file in the
3971 <filename>scripts/lib/image/canned-wks</filename>
3972 directory and then changing the lines that specify the
3973 target disk from which to boot.
3974 <literallayout class='monospaced'>
3975 $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \
3976 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
3977 </literallayout>
3978 Next, the example modifies the
3979 <filename>directdisksdb.wks</filename> file and changes all
3980 instances of "<filename>&dash;&dash;ondisk sda</filename>"
3981 to "<filename>&dash;&dash;ondisk sdb</filename>".
3982 The example changes the following two lines and leaves the
3983 remaining lines untouched:
3984 <literallayout class='monospaced'>
3985 part /boot &dash;&dash;source bootimg-pcbios &dash;&dash;ondisk sdb &dash;&dash;label boot &dash;&dash;active &dash;&dash;align 1024
3986 part / &dash;&dash;source rootfs &dash;&dash;ondisk sdb &dash;&dash;fstype=ext3 &dash;&dash;label platform &dash;&dash;align 1024
3987 </literallayout>
3988 Once the lines are changed, the example generates the
3989 <filename>directdisksdb</filename> image.
3990 The command points the process at the
3991 <filename>core-image-minimal</filename> artifacts for the
3992 Next Unit of Computing (nuc)
3993 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3994 the <filename>local.conf</filename>.
3995 <literallayout class='monospaced'>
3996 $ wic create directdisksdb -e core-image-minimal
3997 Checking basic build environment...
3998 Done.
3999
4000 Creating image(s)...
4001
4002 Info: The new image(s) can be found here:
4003 /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
4004
4005 The following build artifacts were used to create the image(s):
4006 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
4007 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
4008 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
4009 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4010
4011
4012 The image(s) were created using OE kickstart file:
4013 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
4014 </literallayout>
4015 Continuing with the example, you can now directly
4016 <filename>dd</filename> the image to a USB stick, or
4017 whatever media for which you built your image,
4018 and boot the resulting media:
4019 <literallayout class='monospaced'>
4020 $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
4021 86018+0 records in
4022 86018+0 records out
4023 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
4024 [trz@empanada tmp]$ sudo eject /dev/sdb
4025 </literallayout>
4026 </para>
4027 </section>
4028
4029 <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
4030 <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title>
4031
4032 <para>
4033 This example creates an image based on
4034 <filename>core-image-minimal</filename> and a
4035 <filename>crownbay-noemgd</filename>
4036 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4037 that works right out of the box.
4038 <literallayout class='monospaced'>
4039 $ wic create directdisk -e core-image-minimal
4040
4041 Checking basic build environment...
4042 Done.
4043
4044 Creating image(s)...
4045
4046 Info: The new image(s) can be found here:
4047 /var/tmp/wic/build/directdisk-201309252350-sda.direct
4048
4049 The following build artifacts were used to create the image(s):
4050
4051 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
4052 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
4053 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4054 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4055
4056 The image(s) were created using OE kickstart file:
4057 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
4058 </literallayout>
4059 </para>
4060 </section>
4061
4062 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
4063 <title>Using a Modified Kickstart File and Running in Raw Mode</title>
4064
4065 <para>
4066 This next example manually specifies each build artifact
4067 (runs in Raw Mode) and uses a modified kickstart file.
4068 The example also uses the <filename>-o</filename> option
4069 to cause <filename>wic</filename> to create the output
4070 somewhere other than the default
4071 <filename>/var/tmp/wic</filename> directory:
4072 <literallayout class='monospaced'>
4073 $ wic create ~/test.wks -o /home/trz/testwic &dash;&dash;rootfs-dir \
4074 /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \
4075 &dash;&dash;bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \
4076 &dash;&dash;kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \
4077 &dash;&dash;native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4078
4079 Creating image(s)...
4080
4081 Info: The new image(s) can be found here:
4082 /home/trz/testwic/build/test-201309260032-sda.direct
4083
4084 The following build artifacts were used to create the image(s):
4085
4086 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
4087 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
4088 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4089 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4090
4091 The image(s) were created using OE kickstart file:
4092 /home/trz/test.wks
4093 </literallayout>
4094 For this example,
4095 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4096 did not have to be specified in the
4097 <filename>local.conf</filename> file since the artifact is
4098 manually specified.
4099 </para>
4100 </section>
4101 </section>
4102
4103 <section id='openembedded-kickstart-plugins'>
4104 <title>Plugins</title>
4105
4106 <para>
4107 Plugins allow <filename>wic</filename> functionality to
4108 be extended and specialized by users.
4109 This section documents the plugin interface, which is
4110 currently restricted to source plugins.
4111 </para>
4112
4113 <para>
4114 Source plugins provide a mechanism to customize
4115 various aspects of the image generation process in
4116 <filename>wic</filename>, mainly the contents of
4117 partitions.
4118 The plugins provide a mechanism for mapping values
4119 specified in <filename>.wks</filename> files using the
4120 <filename>&dash;&dash;source</filename> keyword to a
4121 particular plugin implementation that populates a
4122 corresponding partition.
4123 </para>
4124
4125 <para>
4126 A source plugin is created as a subclass of
4127 <filename>SourcePlugin</filename>.
4128 The plugin file containing it is added to
4129 <filename>scripts/lib/mic/plugins/source/</filename> to
4130 make the plugin implementation available to the
4131 <filename>wic</filename> implementation.
4132 For more information, see
4133 <filename>scripts/lib/mic/pluginbase.py</filename>.
4134 </para>
4135
4136 <para>
4137 Source plugins can also be implemented and added by
4138 external layers.
4139 As such, any plugins found in a
4140 <filename>scripts/lib/mic/plugins/source/</filename>
4141 directory in an external layer are also made
4142 available.
4143 </para>
4144
4145 <para>
4146 When the <filename>wic</filename> implementation needs
4147 to invoke a partition-specific implementation, it looks
4148 for the plugin that has the same name as the
4149 <filename>&dash;&dash;source</filename> parameter given to
4150 that partition.
4151 For example, if the partition is set up as follows:
4152 <literallayout class='monospaced'>
4153 part /boot &dash;&dash;source bootimg-pcbios ...
4154 </literallayout>
4155 The methods defined as class members of the plugin
4156 having the matching <filename>bootimg-pcbios.name</filename>
4157 class member are used.
4158 </para>
4159
4160 <para>
4161 To be more concrete, here is the plugin definition that
4162 matches a
4163 <filename>&dash;&dash;source bootimg-pcbios</filename> usage,
4164 along with an example
4165 method called by the <filename>wic</filename> implementation
4166 when it needs to invoke an implementation-specific
4167 partition-preparation function:
4168 <literallayout class='monospaced'>
4169 class BootimgPcbiosPlugin(SourcePlugin):
4170 name = 'bootimg-pcbios'
4171
4172 @classmethod
4173 def do_prepare_partition(self, part, ...)
4174 </literallayout>
4175 If the subclass itself does not implement a function, a
4176 default version in a superclass is located and
4177 used, which is why all plugins must be derived from
4178 <filename>SourcePlugin</filename>.
4179 </para>
4180
4181 <para>
4182 The <filename>SourcePlugin</filename> class defines the
4183 following methods, which is the current set of methods
4184 that can be implemented or overridden by
4185 <filename>&dash;&dash;source</filename> plugins.
4186 Any methods not implemented by a
4187 <filename>SourcePlugin</filename> subclass inherit the
4188 implementations present in the
4189 <filename>SourcePlugin</filename> class.
4190 For more information, see the
4191 <filename>SourcePlugin</filename> source for details:
4192 </para>
4193
4194 <para>
4195 <itemizedlist>
4196 <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
4197 Called to do the actual content population for a
4198 partition.
4199 In other words, the method prepares the final
4200 partition image that is incorporated into the
4201 disk image.
4202 </para></listitem>
4203 <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
4204 Called before
4205 <filename>do_prepare_partition()</filename>.
4206 This method is typically used to create custom
4207 configuration files for a partition (e.g. syslinux or
4208 grub configuration files).
4209 </para></listitem>
4210 <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
4211 Called after all partitions have been prepared and
4212 assembled into a disk image.
4213 This method provides a hook to allow finalization of a
4214 disk image, (e.g. writing an MBR).
4215 </para></listitem>
4216 <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
4217 Special content-staging hook called before
4218 <filename>do_prepare_partition()</filename>.
4219 This method is normally empty.</para>
4220 <para>Typically, a partition just uses the passed-in
4221 parameters (e.g. the unmodified value of
4222 <filename>bootimg_dir</filename>).
4223 However, in some cases things might need to be
4224 more tailored.
4225 As an example, certain files might additionally
4226 need to be taken from
4227 <filename>bootimg_dir + /boot</filename>.
4228 This hook allows those files to be staged in a
4229 customized fashion.
4230 <note>
4231 <filename>get_bitbake_var()</filename>
4232 allows you to access non-standard variables
4233 that you might want to use for this.
4234 </note>
4235 </para></listitem>
4236 </itemizedlist>
4237 </para>
4238
4239 <para>
4240 This scheme is extensible.
4241 Adding more hooks is a simple matter of adding more
4242 plugin methods to <filename>SourcePlugin</filename> and
4243 derived classes.
4244 The code that then needs to call the plugin methods uses
4245 <filename>plugin.get_source_plugin_methods()</filename>
4246 to find the method or methods needed by the call.
4247 Retrieval of those methods is accomplished
4248 by filling up a dict with keys
4249 containing the method names of interest.
4250 On success, these will be filled in with the actual
4251 methods.
4252 Please see the <filename>wic</filename>
4253 implementation for examples and details.
4254 </para>
4255 </section>
4256
4257 <section id='openembedded-kickstart-wks-reference'>
4258 <title>OpenEmbedded Kickstart (.wks) Reference</title>
4259
4260 <para>
4261 The current <filename>wic</filename> implementation supports
4262 only the basic kickstart partitioning commands:
4263 <filename>partition</filename> (or <filename>part</filename>
4264 for short) and <filename>bootloader</filename>.
4265 <note>
4266 Future updates will implement more commands and options.
4267 If you use anything that is not specifically
4268 supported, results can be unpredictable.
4269 </note>
4270 </para>
4271
4272 <para>
4273 The following is a list of the commands, their syntax,
4274 and meanings.
4275 The commands are based on the Fedora
4276 kickstart versions but with modifications to
4277 reflect <filename>wic</filename> capabilities.
4278 You can see the original documentation for those commands
4279 at the following links:
4280 <itemizedlist>
4281 <listitem><para>
4282 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
4283 </para></listitem>
4284 <listitem><para>
4285 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
4286 </para></listitem>
4287 </itemizedlist>
4288 </para>
4289
4290 <section id='command-part-or-partition'>
4291 <title>Command: part or partition</title>
4292
4293 <para>
4294 This command creates a partition on the system and uses the
4295 following syntax:
4296 <literallayout class='monospaced'>
4297 part <replaceable>mntpoint</replaceable>
4298 </literallayout>
4299 The <filename><replaceable>mntpoint</replaceable></filename>
4300 is where the
4301 partition will be mounted and must be of one of the
4302 following forms:
4303 <itemizedlist>
4304 <listitem><para><filename>/<replaceable>path</replaceable></filename>:
4305 For example, <filename>/</filename>,
4306 <filename>/usr</filename>, and
4307 <filename>/home</filename></para></listitem>
4308 <listitem><para><filename>swap</filename>:
4309 The partition will be used as swap space.
4310 </para></listitem>
4311 </itemizedlist>
4312 </para>
4313
4314 <para>
4315 Following are the supported options:
4316 <itemizedlist>
4317 <listitem><para><emphasis><filename>&dash;&dash;size</filename>:</emphasis>
4318 The minimum partition size in MBytes.
4319 Specify an integer value such as 500.
4320 Do not append the number with "MB".
4321 You do not need this option if you use
4322 <filename>&dash;&dash;source</filename>.</para></listitem>
4323 <listitem><para><emphasis><filename>&dash;&dash;source</filename>:</emphasis>
4324 This option is a
4325 <filename>wic</filename>-specific option that
4326 names the source of the data that populates
4327 the partition.
4328 The most common value for this option is
4329 "rootfs", but you can use any value that maps to
4330 a valid source plugin.
4331 For information on the source plugins, see the
4332 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
4333 section.</para>
4334 <para>If you use
4335 <filename>&dash;&dash;source rootfs</filename>,
4336 <filename>wic</filename> creates a partition as
4337 large as needed and to fill it with the contents of
4338 the root filesystem pointed to by the
4339 <filename>-r</filename> command-line option
4340 or the equivalent rootfs derived from the
4341 <filename>-e</filename> command-line
4342 option.
4343 The filesystem type used to create the
4344 partition is driven by the value of the
4345 <filename>&dash;&dash;fstype</filename> option
4346 specified for the partition.
4347 See the entry on
4348 <filename>&dash;&dash;fstype</filename> that
4349 follows for more information.
4350 </para>
4351 <para>If you use
4352 <filename>&dash;&dash;source <replaceable>plugin-name</replaceable></filename>,
4353 <filename>wic</filename> creates a partition as
4354 large as needed and fills it with the contents of
4355 the partition that is generated by the
4356 specified plugin name using the data pointed
4357 to by the <filename>-r</filename> command-line
4358 option or the equivalent rootfs derived from the
4359 <filename>-e</filename> command-line
4360 option.
4361 Exactly what those contents and
4362 filesystem type end up being are dependent
4363 on the given plugin implementation.
4364 </para></listitem>
4365 <listitem><para><emphasis><filename>&dash;&dash;ondisk</filename> or <filename>&dash;&dash;ondrive</filename>:</emphasis>
4366 Forces the partition to be created on a particular
4367 disk.</para></listitem>
4368 <listitem><para><emphasis><filename>&dash;&dash;fstype</filename>:</emphasis>
4369 Sets the file system type for the partition.
4370 Valid values are:
4371 <itemizedlist>
4372 <listitem><para><filename>ext4</filename>
4373 </para></listitem>
4374 <listitem><para><filename>ext3</filename>
4375 </para></listitem>
4376 <listitem><para><filename>ext2</filename>
4377 </para></listitem>
4378 <listitem><para><filename>btrfs</filename>
4379 </para></listitem>
4380 <listitem><para><filename>squashfs</filename>
4381 </para></listitem>
4382 <listitem><para><filename>swap</filename>
4383 </para></listitem>
4384 </itemizedlist></para></listitem>
4385 <listitem><para><emphasis><filename>&dash;&dash;fsoptions</filename>:</emphasis>
4386 Specifies a free-form string of options to be
4387 used when mounting the filesystem.
4388 This string will be copied into the
4389 <filename>/etc/fstab</filename> file of the
4390 installed system and should be enclosed in
4391 quotes.
4392 If not specified, the default string
4393 is "defaults".
4394 </para></listitem>
4395 <listitem><para><emphasis><filename>&dash;&dash;label label</filename>:</emphasis>
4396 Specifies the label to give to the filesystem to
4397 be made on the partition.
4398 If the given label is already in use by another
4399 filesystem, a new label is created for the
4400 partition.</para></listitem>
4401 <listitem><para><emphasis><filename>&dash;&dash;active</filename>:</emphasis>
4402 Marks the partition as active.</para></listitem>
4403 <listitem><para><emphasis><filename>&dash;&dash;align (in KBytes)</filename>:</emphasis>
4404 This option is a <filename>wic</filename>-specific
4405 option that says to start a partition on an
4406 x KBytes boundary.</para></listitem>
4407 </itemizedlist>
4408 </para>
4409 </section>
4410
4411 <section id='command-bootloader'>
4412 <title>Command: bootloader</title>
4413
4414 <para>
4415 This command specifies how the boot loader should be
4416 configured and supports the following options:
4417 <note>
4418 Bootloader functionality and boot partitions are
4419 implemented by the various
4420 <filename>&dash;&dash;source</filename>
4421 plugins that implement bootloader functionality.
4422 The bootloader command essentially provides a means of
4423 modifying bootloader configuration.
4424 </note>
4425 <itemizedlist>
4426 <listitem><para><emphasis><filename>&dash;&dash;timeout</filename>:</emphasis>
4427 Specifies the number of seconds before the
4428 bootloader times out and boots the default option.
4429 </para></listitem>
4430 <listitem><para><emphasis><filename>&dash;&dash;append</filename>:</emphasis>
4431 Specifies kernel parameters.
4432 These parameters will be added to the syslinux
4433 <filename>APPEND</filename> or
4434 <filename>grub</filename> kernel command line.
4435 </para></listitem>
4436 </itemizedlist>
4437 </para>
4438 </section>
4439 </section>
4440 </section>
4441
4442 <section id='configuring-the-kernel'>
4443 <title>Configuring the Kernel</title>
4444
4445 <para>
4446 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
4447 file has all the right information in it for the image you are building.
4448 You can use the <filename>menuconfig</filename> tool and configuration fragments to
4449 make sure your <filename>.config</filename> file is just how you need it.
4450 This section describes how to use <filename>menuconfig</filename>, create and use
4451 configuration fragments, and how to interactively modify your <filename>.config</filename>
4452 file to create the leanest kernel configuration file possible.
4453 </para>
4454
4455 <para>
4456 For more information on kernel configuration, see the
4457 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
4458 section in the Yocto Project Linux Kernel Development Manual.
4459 </para>
4460
4461 <section id='using-menuconfig'>
4462 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
4463
4464 <para>
4465 The easiest way to define kernel configurations is to set them through the
4466 <filename>menuconfig</filename> tool.
4467 This tool provides an interactive method with which
4468 to set kernel configurations.
4469 For general information on <filename>menuconfig</filename>, see
4470 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
4471 </para>
4472
4473 <para>
4474 To use the <filename>menuconfig</filename> tool in the Yocto Project development
4475 environment, you must launch it using BitBake.
4476 Thus, the environment must be set up using the
4477 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
4478 or
4479 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
4480 script found in the
4481 <link linkend='build-directory'>Build Directory</link>.
4482 The following commands run <filename>menuconfig</filename> assuming the
4483 <link linkend='source-directory'>Source Directory</link>
4484 top-level folder is <filename>~/poky</filename>:
4485 <literallayout class='monospaced'>
4486 $ cd poky
4487 $ source oe-init-build-env
4488 $ bitbake linux-yocto -c menuconfig
4489 </literallayout>
4490 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
4491 interactively examine and configure all the kernel configuration parameters.
4492 After making your changes, simply exit the tool and save your changes to
4493 create an updated version of the <filename>.config</filename> configuration file.
4494 </para>
4495
4496 <para>
4497 Consider an example that configures the <filename>linux-yocto-3.14</filename>
4498 kernel.
4499 The OpenEmbedded build system recognizes this kernel as
4500 <filename>linux-yocto</filename>.
4501 Thus, the following commands from the shell in which you previously sourced the
4502 environment initialization script cleans the shared state cache and the
4503 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
4504 directory and then runs <filename>menuconfig</filename>:
4505 <literallayout class='monospaced'>
4506 $ bitbake linux-yocto -c menuconfig
4507 </literallayout>
4508 </para>
4509
4510 <para>
4511 Once <filename>menuconfig</filename> launches, use the interface
4512 to navigate through the selections to find the configuration settings in
4513 which you are interested.
4514 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
4515 You can find it at <filename>Processor Type and Features</filename> under
4516 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
4517 After highlighting the selection, use the arrow keys to select or deselect
4518 the setting.
4519 When you are finished with all your selections, exit out and save them.
4520 </para>
4521
4522 <para>
4523 Saving the selections updates the <filename>.config</filename> configuration file.
4524 This is the file that the OpenEmbedded build system uses to configure the
4525 kernel during the build.
4526 You can find and examine this file in the Build Directory in
4527 <filename>tmp/work/</filename>.
4528 The actual <filename>.config</filename> is located in the area where the
4529 specific kernel is built.
4530 For example, if you were building a Linux Yocto kernel based on the
4531 Linux 3.14 kernel and you were building a QEMU image targeted for
4532 <filename>x86</filename> architecture, the
4533 <filename>.config</filename> file would be located here:
4534 <literallayout class='monospaced'>
4535 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
4536 ...656ed30-r1/linux-qemux86-standard-build
4537 </literallayout>
4538 <note>
4539 The previous example directory is artificially split and many of the characters
4540 in the actual filename are omitted in order to make it more readable.
4541 Also, depending on the kernel you are using, the exact pathname
4542 for <filename>linux-yocto-3.14...</filename> might differ.
4543 </note>
4544 </para>
4545
4546 <para>
4547 Within the <filename>.config</filename> file, you can see the kernel settings.
4548 For example, the following entry shows that symmetric multi-processor support
4549 is not set:
4550 <literallayout class='monospaced'>
4551 # CONFIG_SMP is not set
4552 </literallayout>
4553 </para>
4554
4555 <para>
4556 A good method to isolate changed configurations is to use a combination of the
4557 <filename>menuconfig</filename> tool and simple shell commands.
4558 Before changing configurations with <filename>menuconfig</filename>, copy the
4559 existing <filename>.config</filename> and rename it to something else,
4560 use <filename>menuconfig</filename> to make
4561 as many changes as you want and save them, then compare the renamed configuration
4562 file against the newly created file.
4563 You can use the resulting differences as your base to create configuration fragments
4564 to permanently save in your kernel layer.
4565 <note>
4566 Be sure to make a copy of the <filename>.config</filename> and don't just
4567 rename it.
4568 The build system needs an existing <filename>.config</filename>
4569 from which to work.
4570 </note>
4571 </para>
4572 </section>
4573
4574 <section id='creating-config-fragments'>
4575 <title>Creating Configuration Fragments</title>
4576
4577 <para>
4578 Configuration fragments are simply kernel options that appear in a file
4579 placed where the OpenEmbedded build system can find and apply them.
4580 Syntactically, the configuration statement is identical to what would appear
4581 in the <filename>.config</filename> file, which is in the
4582 <link linkend='build-directory'>Build Directory</link> in
4583 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
4584 </para>
4585
4586 <para>
4587 It is simple to create a configuration fragment.
4588 For example, issuing the following from the shell creates a configuration fragment
4589 file named <filename>my_smp.cfg</filename> that enables multi-processor support
4590 within the kernel:
4591 <literallayout class='monospaced'>
4592 $ echo "CONFIG_SMP=y" >> my_smp.cfg
4593 </literallayout>
4594 <note>
4595 All configuration files must use the <filename>.cfg</filename> extension in order
4596 for the OpenEmbedded build system to recognize them as a configuration fragment.
4597 </note>
4598 </para>
4599
4600 <para>
4601 Where do you put your configuration files?
4602 You can place these configuration files in the same area pointed to by
4603 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
4604 The OpenEmbedded build system will pick up the configuration and add it to the
4605 kernel's configuration.
4606 For example, suppose you had a set of configuration options in a file called
4607 <filename>myconfig.cfg</filename>.
4608 If you put that file inside a directory named <filename>linux-yocto</filename>
4609 that resides in the same directory as the kernel's append file and then add
4610 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
4611 those configuration options will be picked up and applied when the kernel is built.
4612 <literallayout class='monospaced'>
4613 SRC_URI += "file://myconfig.cfg"
4614 </literallayout>
4615 </para>
4616
4617 <para>
4618 As mentioned earlier, you can group related configurations into multiple files and
4619 name them all in the <filename>SRC_URI</filename> statement as well.
4620 For example, you could group separate configurations specifically for Ethernet and graphics
4621 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
4622 following in your append file:
4623 <literallayout class='monospaced'>
4624 SRC_URI += "file://myconfig.cfg \
4625 file://eth.cfg \
4626 file://gfx.cfg"
4627 </literallayout>
4628 </para>
4629 </section>
4630
4631 <section id='fine-tuning-the-kernel-configuration-file'>
4632 <title>Fine-Tuning the Kernel Configuration File</title>
4633
4634 <para>
4635 You can make sure the <filename>.config</filename> file is as lean or efficient as
4636 possible by reading the output of the kernel configuration fragment audit,
4637 noting any issues, making changes to correct the issues, and then repeating.
4638 </para>
4639
4640 <para>
4641 As part of the kernel build process, the
4642 <filename>do_kernel_configcheck</filename> task runs.
4643 This task validates the kernel configuration by checking the final
4644 <filename>.config</filename> file against the input files.
4645 During the check, the task produces warning messages for the following
4646 issues:
4647 <itemizedlist>
4648 <listitem><para>Requested options that did not make the final
4649 <filename>.config</filename> file.</para></listitem>
4650 <listitem><para>Configuration items that appear twice in the same
4651 configuration fragment.</para></listitem>
4652 <listitem><para>Configuration items tagged as "required" that were overridden.
4653 </para></listitem>
4654 <listitem><para>A board overrides a non-board specific option.</para></listitem>
4655 <listitem><para>Listed options not valid for the kernel being processed.
4656 In other words, the option does not appear anywhere.</para></listitem>
4657 </itemizedlist>
4658 <note>
4659 The <filename>do_kernel_configcheck</filename> task can
4660 also optionally report if an option is overridden during
4661 processing.
4662 </note>
4663 </para>
4664
4665 <para>
4666 For each output warning, a message points to the file
4667 that contains a list of the options and a pointer to the config
4668 fragment that defines them.
4669 Collectively, the files are the key to streamlining the configuration.
4670 </para>
4671
4672 <para>
4673 To streamline the configuration, do the following:
4674 <orderedlist>
4675 <listitem><para>Start with a full configuration that you
4676 know works - it builds and boots successfully.
4677 This configuration file will be your baseline.
4678 </para></listitem>
4679 <listitem><para>Separately run the
4680 <filename>do_configme</filename> and
4681 <filename>do_kernel_configcheck</filename> tasks.
4682 </para></listitem>
4683 <listitem><para>Take the resulting list of files from the
4684 <filename>do_kernel_configcheck</filename> task
4685 warnings and do the following:
4686 <itemizedlist>
4687 <listitem><para>
4688 Drop values that are redefined in the fragment
4689 but do not change the final
4690 <filename>.config</filename> file.
4691 </para></listitem>
4692 <listitem><para>
4693 Analyze and potentially drop values from the
4694 <filename>.config</filename> file that override
4695 required configurations.
4696 </para></listitem>
4697 <listitem><para>
4698 Analyze and potentially remove non-board
4699 specific options.
4700 </para></listitem>
4701 <listitem><para>
4702 Remove repeated and invalid options.
4703 </para></listitem>
4704 </itemizedlist></para></listitem>
4705 <listitem><para>
4706 After you have worked through the output of the kernel
4707 configuration audit, you can re-run the
4708 <filename>do_configme</filename> and
4709 <filename>do_kernel_configcheck</filename> tasks to
4710 see the results of your changes.
4711 If you have more issues, you can deal with them as
4712 described in the previous step.
4713 </para></listitem>
4714 </orderedlist>
4715 </para>
4716
4717 <para>
4718 Iteratively working through steps two through four eventually yields
4719 a minimal, streamlined configuration file.
4720 Once you have the best <filename>.config</filename>, you can build the Linux
4721 Yocto kernel.
4722 </para>
4723 </section>
4724 </section>
4725
4726 <section id="patching-the-kernel">
4727 <title>Patching the Kernel</title>
4728
4729 <para>
4730 Patching the kernel involves changing or adding configurations to an existing kernel,
4731 changing or adding recipes to the kernel that are needed to support specific hardware features,
4732 or even altering the source code itself.
4733 <note>
4734 You can use the <filename>yocto-kernel</filename> script
4735 found in the <link linkend='source-directory'>Source Directory</link>
4736 under <filename>scripts</filename> to manage kernel patches and configuration.
4737 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>"
4738 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
4739 more information.</note>
4740 </para>
4741
4742 <para>
4743 This example creates a simple patch by adding some QEMU emulator console
4744 output at boot time through <filename>printk</filename> statements in the kernel's
4745 <filename>calibrate.c</filename> source code file.
4746 Applying the patch and booting the modified image causes the added
4747 messages to appear on the emulator's console.
4748 </para>
4749
4750 <para>
4751 The example assumes a clean build exists for the <filename>qemux86</filename>
4752 machine in a
4753 <link linkend='source-directory'>Source Directory</link>
4754 named <filename>poky</filename>.
4755 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
4756 <filename>build</filename> and is located in <filename>poky</filename> and
4757 the kernel is based on the Linux 3.4 kernel.
4758 For general information on how to configure the most efficient build, see the
4759 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
4760 in the Yocto Project Quick Start.
4761 </para>
4762
4763 <para>
4764 Also, for more information on patching the kernel, see the
4765 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
4766 section in the Yocto Project Linux Kernel Development Manual.
4767 </para>
4768
4769 <section id='create-a-layer-for-your-changes'>
4770 <title>Create a Layer for your Changes</title>
4771
4772 <para>
4773 The first step is to create a layer so you can isolate your
4774 changes.
4775 Rather than use the <filename>yocto-layer</filename> script
4776 to create the layer, this example steps through the process
4777 by hand.
4778 If you want information on the script that creates a general
4779 layer, see the
4780 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
4781 section.
4782 </para>
4783
4784 <para>
4785 These two commands create a directory you can use for your
4786 layer:
4787 <literallayout class='monospaced'>
4788 $ cd ~/poky
4789 $ mkdir meta-mylayer
4790 </literallayout>
4791 Creating a directory that follows the Yocto Project layer naming
4792 conventions sets up the layer for your changes.
4793 The layer is where you place your configuration files, append
4794 files, and patch files.
4795 To learn more about creating a layer and filling it with the
4796 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
4797 and Creating Layers</link>" section.
4798 </para>
4799 </section>
4800
4801 <section id='finding-the-kernel-source-code'>
4802 <title>Finding the Kernel Source Code</title>
4803
4804 <para>
4805 Each time you build a kernel image, the kernel source code is fetched
4806 and unpacked into the following directory:
4807 <literallayout class='monospaced'>
4808 ${S}/linux
4809 </literallayout>
4810 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
4811 section and the
4812 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
4813 for more information about where source is kept during a build.
4814 </para>
4815
4816 <para>
4817 For this example, we are going to patch the
4818 <filename>init/calibrate.c</filename> file
4819 by adding some simple console <filename>printk</filename> statements that we can
4820 see when we boot the image using QEMU.
4821 </para>
4822 </section>
4823
4824 <section id='creating-the-patch'>
4825 <title>Creating the Patch</title>
4826
4827 <para>
4828 Two methods exist by which you can create the patch:
4829 <link linkend='using-a-git-workflow'>Git workflow</link> and
4830 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
4831 For kernel patches, the Git workflow is more appropriate.
4832 This section assumes the Git workflow and shows the steps specific to
4833 this example.
4834 <orderedlist>
4835 <listitem><para><emphasis>Change the working directory</emphasis>:
4836 Change to where the kernel source code is before making
4837 your edits to the <filename>calibrate.c</filename> file:
4838 <literallayout class='monospaced'>
4839 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
4840 </literallayout>
4841 Because you are working in an established Git repository,
4842 you must be in this directory in order to commit your changes
4843 and create the patch file.
4844 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
4845 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
4846 represent the version and revision for the
4847 <filename>linux-yocto</filename> recipe.
4848 The <filename>PV</filename> variable includes the Git meta and machine
4849 hashes, which make the directory name longer than you might
4850 expect.
4851 </note></para></listitem>
4852 <listitem><para><emphasis>Edit the source file</emphasis>:
4853 Edit the <filename>init/calibrate.c</filename> file to have the
4854 following changes:
4855 <literallayout class='monospaced'>
4856 void calibrate_delay(void)
4857 {
4858 unsigned long lpj;
4859 static bool printed;
4860 int this_cpu = smp_processor_id();
4861
4862 printk("*************************************\n");
4863 printk("* *\n");
4864 printk("* HELLO YOCTO KERNEL *\n");
4865 printk("* *\n");
4866 printk("*************************************\n");
4867
4868 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
4869 .
4870 .
4871 .
4872 </literallayout></para></listitem>
4873 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
4874 These Git commands display the modified file, stage it, and then
4875 commit the file:
4876 <literallayout class='monospaced'>
4877 $ git status
4878 $ git add init/calibrate.c
4879 $ git commit -m "calibrate: Add printk example"
4880 </literallayout></para></listitem>
4881 <listitem><para><emphasis>Generate the patch file</emphasis>:
4882 This Git command creates the a patch file named
4883 <filename>0001-calibrate-Add-printk-example.patch</filename>
4884 in the current directory.
4885 <literallayout class='monospaced'>
4886 $ git format-patch -1
4887 </literallayout>
4888 </para></listitem>
4889 </orderedlist>
4890 </para>
4891 </section>
4892
4893 <section id='set-up-your-layer-for-the-build'>
4894 <title>Set Up Your Layer for the Build</title>
4895
4896 <para>These steps get your layer set up for the build:
4897 <orderedlist>
4898 <listitem><para><emphasis>Create additional structure</emphasis>:
4899 Create the additional layer structure:
4900 <literallayout class='monospaced'>
4901 $ cd ~/poky/meta-mylayer
4902 $ mkdir conf
4903 $ mkdir recipes-kernel
4904 $ mkdir recipes-kernel/linux
4905 $ mkdir recipes-kernel/linux/linux-yocto
4906 </literallayout>
4907 The <filename>conf</filename> directory holds your configuration files, while the
4908 <filename>recipes-kernel</filename> directory holds your append file and
4909 your patch file.</para></listitem>
4910 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
4911 Move to the <filename>meta-mylayer/conf</filename> directory and create
4912 the <filename>layer.conf</filename> file as follows:
4913 <literallayout class='monospaced'>
4914 # We have a conf and classes directory, add to BBPATH
4915 BBPATH .= ":${LAYERDIR}"
4916
4917 # We have recipes-* directories, add to BBFILES
4918 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
4919 ${LAYERDIR}/recipes-*/*/*.bbappend"
4920
4921 BBFILE_COLLECTIONS += "mylayer"
4922 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
4923 BBFILE_PRIORITY_mylayer = "5"
4924 </literallayout>
4925 Notice <filename>mylayer</filename> as part of the last three
4926 statements.</para></listitem>
4927 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
4928 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
4929 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
4930 <literallayout class='monospaced'>
4931 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4932
4933 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
4934 </literallayout>
4935 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
4936 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
4937 statements enable the OpenEmbedded build system to find the patch file.
4938 For more information on using append files, see the
4939 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
4940 section.
4941 </para></listitem>
4942 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
4943 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
4944 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
4945 directory.</para></listitem>
4946 </orderedlist>
4947 </para>
4948 </section>
4949
4950 <section id='set-up-for-the-build'>
4951 <title>Set Up for the Build</title>
4952
4953 <para>
4954 Do the following to make sure the build parameters are set up for the example.
4955 Once you set up these build parameters, they do not have to change unless you
4956 change the target architecture of the machine you are building:
4957 <itemizedlist>
4958 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
4959 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4960 definition within the <filename>local.conf</filename> file in the
4961 <link linkend='build-directory'>Build Directory</link>
4962 specifies the target architecture used when building the Linux kernel.
4963 By default, <filename>MACHINE</filename> is set to
4964 <filename>qemux86</filename>, which specifies a 32-bit
4965 <trademark class='registered'>Intel</trademark> Architecture
4966 target machine suitable for the QEMU emulator.</para></listitem>
4967 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
4968 layer:</emphasis> The
4969 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
4970 variable in the
4971 <filename>bblayers.conf</filename> file found in the
4972 <filename>poky/build/conf</filename> directory needs to have the path to your local
4973 <filename>meta-mylayer</filename> layer.
4974 By default, the <filename>BBLAYERS</filename> variable contains paths to
4975 <filename>meta</filename>, <filename>meta-yocto</filename>, and
4976 <filename>meta-yocto-bsp</filename> in the
4977 <filename>poky</filename> Git repository.
4978 Add the path to your <filename>meta-mylayer</filename> location:
4979 <literallayout class='monospaced'>
4980 BBLAYERS ?= " \
4981 $HOME/poky/meta \
4982 $HOME/poky/meta-yocto \
4983 $HOME/poky/meta-yocto-bsp \
4984 $HOME/poky/meta-mylayer \
4985 "
4986
4987 BBLAYERS_NON_REMOVABLE ?= " \
4988 $HOME/poky/meta \
4989 $HOME/poky/meta-yocto \
4990 "
4991 </literallayout></para></listitem>
4992 </itemizedlist>
4993 </para>
4994 </section>
4995
4996 <section id='build-the-modified-qemu-kernel-image'>
4997 <title>Build the Modified QEMU Kernel Image</title>
4998
4999 <para>
5000 The following steps build your modified kernel image:
5001 <orderedlist>
5002 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
5003 Your environment should be set up since you previously sourced
5004 the
5005 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
5006 script.
5007 If it is not, source the script again from <filename>poky</filename>.
5008 <literallayout class='monospaced'>
5009 $ cd ~/poky
5010 $ source &OE_INIT_FILE;
5011 </literallayout>
5012 </para></listitem>
5013 <listitem><para><emphasis>Clean up</emphasis>:
5014 Be sure to clean the shared state out by using BitBake
5015 to run from within the Build Directory the
5016 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
5017 task as follows:
5018 <literallayout class='monospaced'>
5019 $ bitbake -c cleansstate linux-yocto
5020 </literallayout></para>
5021 <para>
5022 <note>
5023 Never remove any files by hand from the
5024 <filename>tmp/deploy</filename>
5025 directory inside the
5026 <link linkend='build-directory'>Build Directory</link>.
5027 Always use the various BitBake clean tasks to
5028 clear out previous build artifacts.
5029 For information on the clean tasks, see the
5030 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
5031 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
5032 and
5033 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
5034 sections all in the Yocto Project Reference
5035 Manual.
5036 </note>
5037 </para></listitem>
5038 <listitem><para><emphasis>Build the image</emphasis>:
5039 Next, build the kernel image using this command:
5040 <literallayout class='monospaced'>
5041 $ bitbake -k linux-yocto
5042 </literallayout></para></listitem>
5043 </orderedlist>
5044 </para>
5045 </section>
5046
5047 <section id='boot-the-image-and-verify-your-changes'>
5048 <title>Boot the Image and Verify Your Changes</title>
5049
5050 <para>
5051 These steps boot the image and allow you to see the changes
5052 <orderedlist>
5053 <listitem><para><emphasis>Boot the image</emphasis>:
5054 Boot the modified image in the QEMU emulator
5055 using this command:
5056 <literallayout class='monospaced'>
5057 $ runqemu qemux86
5058 </literallayout></para></listitem>
5059 <listitem><para><emphasis>Verify the changes</emphasis>:
5060 Log into the machine using <filename>root</filename> with no password and then
5061 use the following shell command to scroll through the console's boot output.
5062 <literallayout class='monospaced'>
5063 # dmesg | less
5064 </literallayout>
5065 You should see the results of your <filename>printk</filename> statements
5066 as part of the output.</para></listitem>
5067 </orderedlist>
5068 </para>
5069 </section>
5070 </section>
5071
5072 <section id='making-images-more-secure'>
5073 <title>Making Images More Secure</title>
5074
5075 <para>
5076 Security is of increasing concern for embedded devices.
5077 Consider the issues and problems discussed in just this
5078 sampling of work found across the Internet:
5079 <itemizedlist>
5080 <listitem><para><emphasis>
5081 "<ulink url='https://www.schneier.com/blog/archives/2014/01/security_risks_9.html'>Security Risks of Embedded Systems</ulink>"</emphasis>
5082 by Bruce Schneier
5083 </para></listitem>
5084 <listitem><para><emphasis>
5085 "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
5086 by Carna Botnet</para></listitem>
5087 <listitem><para><emphasis>
5088 "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
5089 by Jake Edge
5090 </para></listitem>
5091 <listitem><para><emphasis>
5092 "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security
5093Gateways via their Web Interfaces</ulink>"</emphasis>
5094 by Ben Williams
5095 </para></listitem>
5096 </itemizedlist>
5097 </para>
5098
5099 <para>
5100 When securing your image is of concern, there are steps, tools,
5101 and variables that you can consider to help you reach the
5102 security goals you need for your particular device.
5103 Not all situations are identical when it comes to making an
5104 image secure.
5105 Consequently, this section provides some guidance and suggestions
5106 for consideration when you want to make your image more secure.
5107 <note>
5108 Because the security requirements and risks are
5109 different for every type of device, this section cannot
5110 provide a complete reference on securing your custom OS.
5111 It is strongly recommended that you also consult other sources
5112 of information on embedded Linux system hardening and on
5113 security.
5114 </note>
5115 </para>
5116
5117 <section id='general-considerations'>
5118 <title>General Considerations</title>
5119
5120 <para>
5121 General considerations exist that help you create more
5122 secure images.
5123 You should consider the following suggestions to help
5124 make your device more secure:
5125 <itemizedlist>
5126 <listitem><para>
5127 Scan additional code you are adding to the system
5128 (e.g. application code) by using static analysis
5129 tools.
5130 Look for buffer overflows and other potential
5131 security problems.
5132 </para></listitem>
5133 <listitem><para>
5134 Pay particular attention to the security for
5135 any web-based administration interface.
5136 </para>
5137 <para>Web interfaces typically need to perform
5138 administrative functions and tend to need to run with
5139 elevated privileges.
5140 Thus, the consequences resulting from the interface's
5141 security becoming compromised can be serious.
5142 Look for common web vulnerabilities such as
5143 cross-site-scripting (XSS), unvalidated inputs,
5144 and so forth.</para>
5145 <para>As with system passwords, the default credentials
5146 for accessing a web-based interface should not be the
5147 same across all devices.
5148 This is particularly true if the interface is enabled
5149 by default as it can be assumed that many end-users
5150 will not change the credentials.
5151 </para></listitem>
5152 <listitem><para>
5153 Ensure you can update the software on the device to
5154 mitigate vulnerabilities discovered in the future.
5155 This consideration especially applies when your
5156 device is network-enabled.
5157 </para></listitem>
5158 <listitem><para>
5159 Ensure you remove or disable debugging functionality
5160 before producing the final image.
5161 For information on how to do this, see the
5162 "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>"
5163 section.
5164 </para></listitem>
5165 <listitem><para>
5166 Ensure you have no network services listening that
5167 are not needed.
5168 </para></listitem>
5169 <listitem><para>
5170 Remove any software from the image that is not needed.
5171 </para></listitem>
5172 <listitem><para>
5173 Enable hardware support for secure boot functionality
5174 when your device supports this functionality.
5175 </para></listitem>
5176 </itemizedlist>
5177 </para>
5178 </section>
5179
5180 <section id='security-flags'>
5181 <title>Security Flags</title>
5182
5183 <para>
5184 The Yocto Project has security flags that you can enable that
5185 help make your build output more secure.
5186 The security flags are in the
5187 <filename>meta/conf/distro/include/security_flags.inc</filename>
5188 file in your
5189 <link linkend='source-directory'>Source Directory</link>
5190 (e.g. <filename>poky</filename>).
5191 <note>
5192 Depending on the recipe, certain security flags are enabled
5193 and disabled by default.
5194 </note>
5195 </para>
5196
5197 <para>
5198<!--
5199 The GCC/LD flags in <filename>security_flags.inc</filename>
5200 enable more secure code generation.
5201 By including the <filename>security_flags.inc</filename>
5202 file, you enable flags to the compiler and linker that cause
5203 them to generate more secure code.
5204 <note>
5205 The GCC/LD flags are enabled by default in the
5206 <filename>poky-lsb</filename> distribution.
5207 </note>
5208-->
5209 Use the following line in your
5210 <filename>local.conf</filename> file or in your custom
5211 distribution configuration file to enable the security
5212 compiler and linker flags for your build:
5213 <literallayout class='monospaced'>
5214 require conf/distro/include/security_flags.inc
5215 </literallayout>
5216 </para>
5217 </section>
5218
5219 <section id='considerations-specific-to-the-openembedded-build-system'>
5220 <title>Considerations Specific to the OpenEmbedded Build System</title>
5221
5222 <para>
5223 You can take some steps that are specific to the
5224 OpenEmbedded build system to make your images more secure:
5225 <itemizedlist>
5226 <listitem><para>
5227 Ensure "debug-tweaks" is not one of your selected
5228 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>.
5229 When creating a new project, the default is to provide you
5230 with an initial <filename>local.conf</filename> file that
5231 enables this feature using the
5232 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> variable with the line:
5233 <literallayout class='monospaced'>
5234 EXTRA_IMAGE_FEATURES = "debug-tweaks"
5235 </literallayout>
5236 To disable that feature, simply comment out that line in your
5237 <filename>local.conf</filename> file, or
5238 make sure <filename>IMAGE_FEATURES</filename> does not contain
5239 "debug-tweaks" before producing your final image.
5240 Among other things, leaving this in place sets the
5241 root password as blank, which makes logging in for
5242 debugging or inspection easy during
5243 development but also means anyone can easily log in
5244 during production.
5245 </para></listitem>
5246 <listitem><para>
5247 It is possible to set a root password for the image
5248 and also to set passwords for any extra users you might
5249 add (e.g. administrative or service type users).
5250 When you set up passwords for multiple images or
5251 users, you should not duplicate passwords.
5252 </para>
5253 <para>
5254 To set up passwords, use the
5255 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers</filename></ulink>
5256 class, which is the preferred method.
5257 For an example on how to set up both root and user
5258 passwords, see the
5259 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>"
5260 section.
5261 <note>
5262 When adding extra user accounts or setting a
5263 root password, be cautious about setting the
5264 same password on every device.
5265 If you do this, and the password you have set
5266 is exposed, then every device is now potentially
5267 compromised.
5268 If you need this access but want to ensure
5269 security, consider setting a different,
5270 random password for each device.
5271 Typically, you do this as a separate step after
5272 you deploy the image onto the device.
5273 </note>
5274 </para></listitem>
5275 <listitem><para>
5276 Consider enabling a Mandatory Access Control (MAC)
5277 framework such as SMACK or SELinux and tuning it
5278 appropriately for your device's usage.
5279 You can find more information in the
5280 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/'><filename>meta-selinux</filename></ulink>
5281 layer.
5282 </para></listitem>
5283 </itemizedlist>
5284 </para>
5285
5286 <para>
5287 </para>
5288 </section>
5289
5290 <section id='tools-for-hardening-your-image'>
5291 <title>Tools for Hardening Your Image</title>
5292
5293 <para>
5294 The Yocto Project provides tools for making your image
5295 more secure.
5296 You can find these tools in the
5297 <filename>meta-security</filename> layer of the
5298 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
5299 </para>
5300 </section>
5301 </section>
5302
5303 <section id='creating-your-own-distribution'>
5304 <title>Creating Your Own Distribution</title>
5305
5306 <para>
5307 When you build an image using the Yocto Project and
5308 do not alter any distribution
5309 <link linkend='metadata'>Metadata</link>, you are creating a
5310 Poky distribution.
5311 If you wish to gain more control over package alternative
5312 selections, compile-time options, and other low-level
5313 configurations, you can create your own distribution.
5314 </para>
5315
5316 <para>
5317 To create your own distribution, the basic steps consist of
5318 creating your own distribution layer, creating your own
5319 distribution configuration file, and then adding any needed
5320 code and Metadata to the layer.
5321 The following steps provide some more detail:
5322 <itemizedlist>
5323 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
5324 Create your distribution layer so that you can keep your
5325 Metadata and code for the distribution separate.
5326 It is strongly recommended that you create and use your own
5327 layer for configuration and code.
5328 Using your own layer as compared to just placing
5329 configurations in a <filename>local.conf</filename>
5330 configuration file makes it easier to reproduce the same
5331 build configuration when using multiple build machines.
5332 See the
5333 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
5334 section for information on how to quickly set up a layer.
5335 </para></listitem>
5336 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
5337 The distribution configuration file needs to be created in
5338 the <filename>conf/distro</filename> directory of your
5339 layer.
5340 You need to name it using your distribution name
5341 (e.g. <filename>mydistro.conf</filename>).
5342 <note>
5343 The
5344 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5345 variable in your
5346 <filename>local.conf</filename> file determines the
5347 name of your distribution.
5348 </note></para>
5349 <para>You can split out parts of your configuration file
5350 into include files and then "require" them from within
5351 your distribution configuration file.
5352 Be sure to place the include files in the
5353 <filename>conf/distro/include</filename> directory of
5354 your layer.
5355 A common example usage of include files would be to
5356 separate out the selection of desired version and revisions
5357 for individual recipes.
5358</para>
5359 <para>Your configuration file needs to set the following
5360 required variables:
5361 <literallayout class='monospaced'>
5362 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
5363 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
5364 </literallayout>
5365 These following variables are optional and you typically
5366 set them from the distribution configuration file:
5367 <literallayout class='monospaced'>
5368 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5369 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
5370 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
5371 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
5372 </literallayout>
5373 <tip>
5374 If you want to base your distribution configuration file
5375 on the very basic configuration from OE-Core, you
5376 can use
5377 <filename>conf/distro/defaultsetup.conf</filename> as
5378 a reference and just include variables that differ
5379 as compared to <filename>defaultsetup.conf</filename>.
5380 Alternatively, you can create a distribution
5381 configuration file from scratch using the
5382 <filename>defaultsetup.conf</filename> file
5383 or configuration files from other distributions
5384 such as Poky or Angstrom as references.
5385 </tip></para></listitem>
5386 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
5387 Be sure to define any other variables for which you want to
5388 create a default or enforce as part of the distribution
5389 configuration.
5390 You can include nearly any variable from the
5391 <filename>local.conf</filename> file.
5392 The variables you use are not limited to the list in the
5393 previous bulleted item.</para></listitem>
5394 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
5395 In your <filename>local.conf</filename> file in the
5396 <link linkend='build-directory'>Build Directory</link>,
5397 set your
5398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5399 variable to point to your distribution's configuration file.
5400 For example, if your distribution's configuration file is
5401 named <filename>mydistro.conf</filename>, then you point
5402 to it as follows:
5403 <literallayout class='monospaced'>
5404 DISTRO = "mydistro"
5405 </literallayout></para></listitem>
5406 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
5407 Use your layer to hold other information needed for the
5408 distribution:
5409 <itemizedlist>
5410 <listitem><para>Add recipes for installing
5411 distro-specific configuration files that are not
5412 already installed by another recipe.
5413 If you have distro-specific configuration files
5414 that are included by an existing recipe, you should
5415 add an append file (<filename>.bbappend</filename>)
5416 for those.
5417 For general information and recommendations
5418 on how to add recipes to your layer, see the
5419 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
5420 and
5421 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
5422 sections.</para></listitem>
5423 <listitem><para>Add any image recipes that are specific
5424 to your distribution.</para></listitem>
5425 <listitem><para>Add a <filename>psplash</filename>
5426 append file for a branded splash screen.
5427 For information on append files, see the
5428 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
5429 section.</para></listitem>
5430 <listitem><para>Add any other append files to make
5431 custom changes that are specific to individual
5432 recipes.</para></listitem>
5433 </itemizedlist></para></listitem>
5434 </itemizedlist>
5435 </para>
5436 </section>
5437
5438 <section id='creating-a-custom-template-configuration-directory'>
5439 <title>Creating a Custom Template Configuration Directory</title>
5440
5441 <para>
5442 If you are producing your own customized version
5443 of the build system for use by other users, you might
5444 want to customize the message shown by the setup script or
5445 you might want to change the template configuration files (i.e.
5446 <filename>local.conf</filename> and
5447 <filename>bblayers.conf</filename>) that are created in
5448 a new build directory.
5449 </para>
5450
5451 <para>
5452 The OpenEmbedded build system uses the environment variable
5453 <filename>TEMPLATECONF</filename> to locate the directory
5454 from which it gathers configuration information that ultimately
5455 ends up in the
5456 <link linkend='build-directory'>Build Directory's</link>
5457 <filename>conf</filename> directory.
5458 By default, <filename>TEMPLATECONF</filename> is set as
5459 follows in the <filename>poky</filename> repository:
5460 <literallayout class='monospaced'>
5461 TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf}
5462 </literallayout>
5463 This is the directory used by the build system to find templates
5464 from which to build some key configuration files.
5465 If you look at this directory, you will see the
5466 <filename>bblayers.conf.sample</filename>,
5467 <filename>local.conf.sample</filename>, and
5468 <filename>conf-notes.txt</filename> files.
5469 The build system uses these files to form the respective
5470 <filename>bblayers.conf</filename> file,
5471 <filename>local.conf</filename> file, and display the list of
5472 BitBake targets when running the setup script.
5473 </para>
5474
5475 <para>
5476 To override these default configuration files with
5477 configurations you want used within every new
5478 Build Directory, simply set the
5479 <filename>TEMPLATECONF</filename> variable to your directory.
5480 The <filename>TEMPLATECONF</filename> variable is set in the
5481 <filename>.templateconf</filename> file, which is in the
5482 top-level
5483 <link linkend='source-directory'>Source Directory</link>
5484 folder (e.g. <filename>poky</filename>).
5485 Edit the <filename>.templateconf</filename> so that it can locate
5486 your directory.
5487 </para>
5488
5489 <para>
5490 Best practices dictate that you should keep your
5491 template configuration directory in your custom distribution layer.
5492 For example, suppose you have a layer named
5493 <filename>meta-mylayer</filename> located in your home directory
5494 and you want your template configuration directory named
5495 <filename>myconf</filename>.
5496 Changing the <filename>.templateconf</filename> as follows
5497 causes the OpenEmbedded build system to look in your directory
5498 and base its configuration files on the
5499 <filename>*.sample</filename> configuration files it finds.
5500 The final configuration files (i.e.
5501 <filename>local.conf</filename> and
5502 <filename>bblayers.conf</filename> ultimately still end up in
5503 your Build Directory, but they are based on your
5504 <filename>*.sample</filename> files.
5505 <literallayout class='monospaced'>
5506 TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf}
5507 </literallayout>
5508 </para>
5509
5510 <para>
5511 Aside from the <filename>*.sample</filename> configuration files,
5512 the <filename>conf-notes.txt</filename> also resides in the
5513 default <filename>meta-yocto/conf</filename> directory.
5514 The scripts that set up the build environment
5515 (i.e.
5516 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
5517 and
5518 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>)
5519 use this file to display BitBake targets as part of the script
5520 output.
5521 Customizing this <filename>conf-notes.txt</filename> file is a
5522 good way to make sure your list of custom targets appears
5523 as part of the script's output.
5524 </para>
5525
5526 <para>
5527 Here is the default list of targets displayed as a result of
5528 running either of the setup scripts:
5529 <literallayout class='monospaced'>
5530 You can now run 'bitbake &lt;target&gt;'
5531
5532 Common targets are:
5533 core-image-minimal
5534 core-image-sato
5535 meta-toolchain
5536 adt-installer
5537 meta-ide-support
5538 </literallayout>
5539 </para>
5540
5541 <para>
5542 Changing the listed common targets is as easy as editing your
5543 version of <filename>conf-notes.txt</filename> in your
5544 custom template configuration directory and making sure you
5545 have <filename>TEMPLATECONF</filename> set to your directory.
5546 </para>
5547 </section>
5548
5549 <section id='building-a-tiny-system'>
5550 <title>Building a Tiny System</title>
5551
5552 <para>
5553 Very small distributions have some significant advantages such
5554 as requiring less on-die or in-package memory (cheaper), better
5555 performance through efficient cache usage, lower power requirements
5556 due to less memory, faster boot times, and reduced development
5557 overhead.
5558 Some real-world examples where a very small distribution gives
5559 you distinct advantages are digital cameras, medical devices,
5560 and small headless systems.
5561 </para>
5562
5563 <para>
5564 This section presents information that shows you how you can
5565 trim your distribution to even smaller sizes than the
5566 <filename>poky-tiny</filename> distribution, which is around
5567 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
5568 </para>
5569
5570 <section id='tiny-system-overview'>
5571 <title>Overview</title>
5572
5573 <para>
5574 The following list presents the overall steps you need to
5575 consider and perform to create distributions with smaller
5576 root filesystems, achieve faster boot times, maintain your critical
5577 functionality, and avoid initial RAM disks:
5578 <itemizedlist>
5579 <listitem><para>
5580 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
5581 </para></listitem>
5582 <listitem><para>
5583 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
5584 </para></listitem>
5585 <listitem><para>
5586 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
5587 </para></listitem>
5588 <listitem><para>
5589 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
5590 </para></listitem>
5591 <listitem><para>
5592 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
5593 </para></listitem>
5594 <listitem><para>
5595 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
5596 </para></listitem>
5597 <listitem><para>
5598 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
5599 </para></listitem>
5600 </itemizedlist>
5601 </para>
5602 </section>
5603
5604 <section id='goals-and-guiding-principles'>
5605 <title>Goals and Guiding Principles</title>
5606
5607 <para>
5608 Before you can reach your destination, you need to know
5609 where you are going.
5610 Here is an example list that you can use as a guide when
5611 creating very small distributions:
5612 <itemizedlist>
5613 <listitem><para>Determine how much space you need
5614 (e.g. a kernel that is 1 Mbyte or less and
5615 a root filesystem that is 3 Mbytes or less).
5616 </para></listitem>
5617 <listitem><para>Find the areas that are currently
5618 taking 90% of the space and concentrate on reducing
5619 those areas.
5620 </para></listitem>
5621 <listitem><para>Do not create any difficult "hacks"
5622 to achieve your goals.</para></listitem>
5623 <listitem><para>Leverage the device-specific
5624 options.</para></listitem>
5625 <listitem><para>Work in a separate layer so that you
5626 keep changes isolated.
5627 For information on how to create layers, see
5628 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
5629 </para></listitem>
5630 </itemizedlist>
5631 </para>
5632 </section>
5633
5634 <section id='understand-what-gives-your-image-size'>
5635 <title>Understand What Contributes to Your Image Size</title>
5636
5637 <para>
5638 It is easiest to have something to start with when creating
5639 your own distribution.
5640 You can use the Yocto Project out-of-the-box to create the
5641 <filename>poky-tiny</filename> distribution.
5642 Ultimately, you will want to make changes in your own
5643 distribution that are likely modeled after
5644 <filename>poky-tiny</filename>.
5645 <note>
5646 To use <filename>poky-tiny</filename> in your build,
5647 set the
5648 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5649 variable in your
5650 <filename>local.conf</filename> file to "poky-tiny"
5651 as described in the
5652 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
5653 section.
5654 </note>
5655 </para>
5656
5657 <para>
5658 Understanding some memory concepts will help you reduce the
5659 system size.
5660 Memory consists of static, dynamic, and temporary memory.
5661 Static memory is the TEXT (code), DATA (initialized data
5662 in the code), and BSS (uninitialized data) sections.
5663 Dynamic memory represents memory that is allocated at runtime:
5664 stacks, hash tables, and so forth.
5665 Temporary memory is recovered after the boot process.
5666 This memory consists of memory used for decompressing
5667 the kernel and for the <filename>__init__</filename>
5668 functions.
5669 </para>
5670
5671 <para>
5672 To help you see where you currently are with kernel and root
5673 filesystem sizes, you can use two tools found in the
5674 <link linkend='source-directory'>Source Directory</link> in
5675 the <filename>scripts/tiny/</filename> directory:
5676 <itemizedlist>
5677 <listitem><para><filename>ksize.py</filename>: Reports
5678 component sizes for the kernel build objects.
5679 </para></listitem>
5680 <listitem><para><filename>dirsize.py</filename>: Reports
5681 component sizes for the root filesystem.</para></listitem>
5682 </itemizedlist>
5683 This next tool and command help you organize configuration
5684 fragments and view file dependencies in a human-readable form:
5685 <itemizedlist>
5686 <listitem><para><filename>merge_config.sh</filename>:
5687 Helps you manage configuration files and fragments
5688 within the kernel.
5689 With this tool, you can merge individual configuration
5690 fragments together.
5691 The tool allows you to make overrides and warns you
5692 of any missing configuration options.
5693 The tool is ideal for allowing you to iterate on
5694 configurations, create minimal configurations, and
5695 create configuration files for different machines
5696 without having to duplicate your process.</para>
5697 <para>The <filename>merge_config.sh</filename> script is
5698 part of the Linux Yocto kernel Git repositories
5699 (i.e. <filename>linux-yocto-3.14</filename>,
5700 <filename>linux-yocto-3.10</filename>,
5701 <filename>linux-yocto-3.8</filename>, and so forth)
5702 in the
5703 <filename>scripts/kconfig</filename> directory.</para>
5704 <para>For more information on configuration fragments,
5705 see the
5706 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
5707 section of the Yocto Project Linux Kernel Development
5708 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
5709 section, which is in this manual.</para></listitem>
5710 <listitem><para><filename>bitbake -u depexp -g <replaceable>bitbake_target</replaceable></filename>:
5711 Using the BitBake command with these options brings up
5712 a Dependency Explorer from which you can view file
5713 dependencies.
5714 Understanding these dependencies allows you to make
5715 informed decisions when cutting out various pieces of the
5716 kernel and root filesystem.</para></listitem>
5717 </itemizedlist>
5718 </para>
5719 </section>
5720
5721 <section id='trim-the-root-filesystem'>
5722 <title>Trim the Root Filesystem</title>
5723
5724 <para>
5725 The root filesystem is made up of packages for booting,
5726 libraries, and applications.
5727 To change things, you can configure how the packaging happens,
5728 which changes the way you build them.
5729 You can also modify the filesystem itself or select a different
5730 filesystem.
5731 </para>
5732
5733 <para>
5734 First, find out what is hogging your root filesystem by running the
5735 <filename>dirsize.py</filename> script from your root directory:
5736 <literallayout class='monospaced'>
5737 $ cd <replaceable>root-directory-of-image</replaceable>
5738 $ dirsize.py 100000 > dirsize-100k.log
5739 $ cat dirsize-100k.log
5740 </literallayout>
5741 You can apply a filter to the script to ignore files under
5742 a certain size.
5743 The previous example filters out any files below 100 Kbytes.
5744 The sizes reported by the tool are uncompressed, and thus
5745 will be smaller by a relatively constant factor in a
5746 compressed root filesystem.
5747 When you examine your log file, you can focus on areas of the
5748 root filesystem that take up large amounts of memory.
5749 </para>
5750
5751 <para>
5752 You need to be sure that what you eliminate does not cripple
5753 the functionality you need.
5754 One way to see how packages relate to each other is by using
5755 the Dependency Explorer UI with the BitBake command:
5756 <literallayout class='monospaced'>
5757 $ cd <replaceable>image-directory</replaceable>
5758 $ bitbake -u depexp -g <replaceable>image</replaceable>
5759 </literallayout>
5760 Use the interface to select potential packages you wish to
5761 eliminate and see their dependency relationships.
5762 </para>
5763
5764 <para>
5765 When deciding how to reduce the size, get rid of packages that
5766 result in minimal impact on the feature set.
5767 For example, you might not need a VGA display.
5768 Or, you might be able to get by with <filename>devtmpfs</filename>
5769 and <filename>mdev</filename> instead of
5770 <filename>udev</filename>.
5771 </para>
5772
5773 <para>
5774 Use your <filename>local.conf</filename> file to make changes.
5775 For example, to eliminate <filename>udev</filename> and
5776 <filename>glib</filename>, set the following in the
5777 local configuration file:
5778 <literallayout class='monospaced'>
5779 VIRTUAL-RUNTIME_dev_manager = ""
5780 </literallayout>
5781 </para>
5782
5783 <para>
5784 Finally, you should consider exactly the type of root
5785 filesystem you need to meet your needs while also reducing
5786 its size.
5787 For example, consider <filename>cramfs</filename>,
5788 <filename>squashfs</filename>, <filename>ubifs</filename>,
5789 <filename>ext2</filename>, or an <filename>initramfs</filename>
5790 using <filename>initramfs</filename>.
5791 Be aware that <filename>ext3</filename> requires a 1 Mbyte
5792 journal.
5793 If you are okay with running read-only, you do not need this
5794 journal.
5795 </para>
5796
5797 <note>
5798 After each round of elimination, you need to rebuild your
5799 system and then use the tools to see the effects of your
5800 reductions.
5801 </note>
5802
5803
5804 </section>
5805
5806 <section id='trim-the-kernel'>
5807 <title>Trim the Kernel</title>
5808
5809 <para>
5810 The kernel is built by including policies for hardware-independent
5811 aspects.
5812 What subsystems do you enable?
5813 For what architecture are you building?
5814 Which drivers do you build by default?
5815 <note>You can modify the kernel source if you want to help
5816 with boot time.
5817 </note>
5818 </para>
5819
5820 <para>
5821 Run the <filename>ksize.py</filename> script from the top-level
5822 Linux build directory to get an idea of what is making up
5823 the kernel:
5824 <literallayout class='monospaced'>
5825 $ cd <replaceable>top-level-linux-build-directory</replaceable>
5826 $ ksize.py > ksize.log
5827 $ cat ksize.log
5828 </literallayout>
5829 When you examine the log, you will see how much space is
5830 taken up with the built-in <filename>.o</filename> files for
5831 drivers, networking, core kernel files, filesystem, sound,
5832 and so forth.
5833 The sizes reported by the tool are uncompressed, and thus
5834 will be smaller by a relatively constant factor in a compressed
5835 kernel image.
5836 Look to reduce the areas that are large and taking up around
5837 the "90% rule."
5838 </para>
5839
5840 <para>
5841 To examine, or drill down, into any particular area, use the
5842 <filename>-d</filename> option with the script:
5843 <literallayout class='monospaced'>
5844 $ ksize.py -d > ksize.log
5845 </literallayout>
5846 Using this option breaks out the individual file information
5847 for each area of the kernel (e.g. drivers, networking, and
5848 so forth).
5849 </para>
5850
5851 <para>
5852 Use your log file to see what you can eliminate from the kernel
5853 based on features you can let go.
5854 For example, if you are not going to need sound, you do not
5855 need any drivers that support sound.
5856 </para>
5857
5858 <para>
5859 After figuring out what to eliminate, you need to reconfigure
5860 the kernel to reflect those changes during the next build.
5861 You could run <filename>menuconfig</filename> and make all your
5862 changes at once.
5863 However, that makes it difficult to see the effects of your
5864 individual eliminations and also makes it difficult to replicate
5865 the changes for perhaps another target device.
5866 A better method is to start with no configurations using
5867 <filename>allnoconfig</filename>, create configuration
5868 fragments for individual changes, and then manage the
5869 fragments into a single configuration file using
5870 <filename>merge_config.sh</filename>.
5871 The tool makes it easy for you to iterate using the
5872 configuration change and build cycle.
5873 </para>
5874
5875 <para>
5876 Each time you make configuration changes, you need to rebuild
5877 the kernel and check to see what impact your changes had on
5878 the overall size.
5879 </para>
5880 </section>
5881
5882 <section id='remove-package-management-requirements'>
5883 <title>Remove Package Management Requirements</title>
5884
5885 <para>
5886 Packaging requirements add size to the image.
5887 One way to reduce the size of the image is to remove all the
5888 packaging requirements from the image.
5889 This reduction includes both removing the package manager
5890 and its unique dependencies as well as removing the package
5891 management data itself.
5892 </para>
5893
5894 <para>
5895 To eliminate all the packaging requirements for an image,
5896 be sure that "package-management" is not part of your
5897 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5898 statement for the image.
5899 When you remove this feature, you are removing the package
5900 manager as well as its dependencies from the root filesystem.
5901 </para>
5902 </section>
5903
5904 <section id='look-for-other-ways-to-minimize-size'>
5905 <title>Look for Other Ways to Minimize Size</title>
5906
5907 <para>
5908 Depending on your particular circumstances, other areas that you
5909 can trim likely exist.
5910 The key to finding these areas is through tools and methods
5911 described here combined with experimentation and iteration.
5912 Here are a couple of areas to experiment with:
5913 <itemizedlist>
5914 <listitem><para><filename>glibc</filename>:
5915 In general, follow this process:
5916 <orderedlist>
5917 <listitem><para>Remove <filename>glibc</filename>
5918 features from
5919 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5920 that you think you do not need.</para></listitem>
5921 <listitem><para>Build your distribution.
5922 </para></listitem>
5923 <listitem><para>If the build fails due to missing
5924 symbols in a package, determine if you can
5925 reconfigure the package to not need those
5926 features.
5927 For example, change the configuration to not
5928 support wide character support as is done for
5929 <filename>ncurses</filename>.
5930 Or, if support for those characters is needed,
5931 determine what <filename>glibc</filename>
5932 features provide the support and restore the
5933 configuration.
5934 </para></listitem>
5935 <listitem><para>Rebuild and repeat the process.
5936 </para></listitem>
5937 </orderedlist></para></listitem>
5938 <listitem><para><filename>busybox</filename>:
5939 For BusyBox, use a process similar as described for
5940 <filename>glibc</filename>.
5941 A difference is you will need to boot the resulting
5942 system to see if you are able to do everything you
5943 expect from the running system.
5944 You need to be sure to integrate configuration fragments
5945 into Busybox because BusyBox handles its own core
5946 features and then allows you to add configuration
5947 fragments on top.
5948 </para></listitem>
5949 </itemizedlist>
5950 </para>
5951 </section>
5952
5953 <section id='iterate-on-the-process'>
5954 <title>Iterate on the Process</title>
5955
5956 <para>
5957 If you have not reached your goals on system size, you need
5958 to iterate on the process.
5959 The process is the same.
5960 Use the tools and see just what is taking up 90% of the root
5961 filesystem and the kernel.
5962 Decide what you can eliminate without limiting your device
5963 beyond what you need.
5964 </para>
5965
5966 <para>
5967 Depending on your system, a good place to look might be
5968 Busybox, which provides a stripped down
5969 version of Unix tools in a single, executable file.
5970 You might be able to drop virtual terminal services or perhaps
5971 ipv6.
5972 </para>
5973 </section>
5974 </section>
5975
5976 <section id='working-with-packages'>
5977 <title>Working with Packages</title>
5978
5979 <para>
5980 This section describes a few tasks that involve packages:
5981 <itemizedlist>
5982 <listitem><para>
5983 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
5984 </para></listitem>
5985 <listitem><para>
5986 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
5987 </para></listitem>
5988 <listitem><para>
5989 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
5990 </para></listitem>
5991 <listitem><para>
5992 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
5993 </para></listitem>
5994 <listitem><para>
5995 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
5996 </para></listitem>
5997 <listitem><para>
5998 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
5999 </para></listitem>
6000 </itemizedlist>
6001 </para>
6002
6003 <section id='excluding-packages-from-an-image'>
6004 <title>Excluding Packages from an Image</title>
6005
6006 <para>
6007 You might find it necessary to prevent specific packages
6008 from being installed into an image.
6009 If so, you can use several variables to direct the build
6010 system to essentially ignore installing recommended packages
6011 or to not install a package at all.
6012 </para>
6013
6014 <para>
6015 The following list introduces variables you can use to
6016 prevent packages from being installed into your image.
6017 Each of these variables only works with IPK and RPM
6018 package types.
6019 Support for Debian packages does not exist.
6020 Also, you can use these variables from your
6021 <filename>local.conf</filename> file or attach them to a
6022 specific image recipe by using a recipe name override.
6023 For more detail on the variables, see the descriptions in the
6024 Yocto Project Reference Manual's glossary chapter.
6025 <itemizedlist>
6026 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
6027 Use this variable to specify "recommended-only"
6028 packages that you do not want installed.
6029 </para></listitem>
6030 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
6031 Use this variable to prevent all "recommended-only"
6032 packages from being installed.
6033 </para></listitem>
6034 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
6035 Use this variable to prevent specific packages from
6036 being installed regardless of whether they are
6037 "recommended-only" or not.
6038 You need to realize that the build process could
6039 fail with an error when you
6040 prevent the installation of a package whose presence
6041 is required by an installed package.
6042 </para></listitem>
6043 </itemizedlist>
6044 </para>
6045 </section>
6046
6047 <section id='incrementing-a-package-revision-number'>
6048 <title>Incrementing a Package Revision Number</title>
6049
6050 <para>
6051 If a committed change results in changing the package output,
6052 then the value of the
6053 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6054 variable needs to be increased (or "bumped").
6055 Increasing <filename>PR</filename> occurs one of two ways:
6056 <itemizedlist>
6057 <listitem><para>Automatically using a Package Revision
6058 Service (PR Service).</para></listitem>
6059 <listitem><para>Manually incrementing the
6060 <filename>PR</filename> variable.</para></listitem>
6061 </itemizedlist>
6062 </para>
6063
6064 <para>
6065 Given that one of the challenges any build system and its
6066 users face is how to maintain a package feed that is compatible
6067 with existing package manager applications such as
6068 RPM, APT, and OPKG, using an automated system is much
6069 preferred over a manual system.
6070 In either system, the main requirement is that version
6071 numbering increases in a linear fashion and that a number of
6072 version components exist that support that linear progression.
6073 </para>
6074
6075 <para>
6076 The following two sections provide information on the PR Service
6077 and on manual <filename>PR</filename> bumping.
6078 </para>
6079
6080 <section id='working-with-a-pr-service'>
6081 <title>Working With a PR Service</title>
6082
6083 <para>
6084 As mentioned, attempting to maintain revision numbers in the
6085 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
6086 is error prone, inaccurate, and causes problems for people
6087 submitting recipes.
6088 Conversely, the PR Service automatically generates
6089 increasing numbers, particularly the revision field,
6090 which removes the human element.
6091 <note>
6092 For additional information on using a PR Service, you
6093 can see the
6094 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
6095 wiki page.
6096 </note>
6097 </para>
6098
6099 <para>
6100 The Yocto Project uses variables in order of
6101 decreasing priority to facilitate revision numbering (i.e.
6102 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
6103 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
6104 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6105 for epoch, version, and revision, respectively).
6106 The values are highly dependent on the policies and
6107 procedures of a given distribution and package feed.
6108 </para>
6109
6110 <para>
6111 Because the OpenEmbedded build system uses
6112 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
6113 which are unique to a given build, the build system
6114 knows when to rebuild packages.
6115 All the inputs into a given task are represented by a
6116 signature, which can trigger a rebuild when different.
6117 Thus, the build system itself does not rely on the
6118 <filename>PR</filename> numbers to trigger a rebuild.
6119 The signatures, however, can be used to generate
6120 <filename>PR</filename> values.
6121 </para>
6122
6123 <para>
6124 The PR Service works with both
6125 <filename>OEBasic</filename> and
6126 <filename>OEBasicHash</filename> generators.
6127 The value of <filename>PR</filename> bumps when the
6128 checksum changes and the different generator mechanisms
6129 change signatures under different circumstances.
6130 </para>
6131
6132 <para>
6133 As implemented, the build system includes values from
6134 the PR Service into the <filename>PR</filename> field as
6135 an addition using the form "<filename>.x</filename>" so
6136 <filename>r0</filename> becomes <filename>r0.1</filename>,
6137 <filename>r0.2</filename> and so forth.
6138 This scheme allows existing <filename>PR</filename> values
6139 to be used for whatever reasons, which include manual
6140 <filename>PR</filename> bumps, should it be necessary.
6141 </para>
6142
6143 <para>
6144 By default, the PR Service is not enabled or running.
6145 Thus, the packages generated are just "self consistent".
6146 The build system adds and removes packages and
6147 there are no guarantees about upgrade paths but images
6148 will be consistent and correct with the latest changes.
6149 </para>
6150
6151 <para>
6152 The simplest form for a PR Service is for it to exist
6153 for a single host development system that builds the
6154 package feed (building system).
6155 For this scenario, you can enable a local PR Service by
6156 setting
6157 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
6158 in your <filename>local.conf</filename> file in the
6159 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6160 <literallayout class='monospaced'>
6161 PRSERV_HOST = "localhost:0"
6162 </literallayout>
6163 Once the service is started, packages will automatically
6164 get increasing <filename>PR</filename> values and
6165 BitBake will take care of starting and stopping the server.
6166 </para>
6167
6168 <para>
6169 If you have a more complex setup where multiple host
6170 development systems work against a common, shared package
6171 feed, you have a single PR Service running and it is
6172 connected to each building system.
6173 For this scenario, you need to start the PR Service using
6174 the <filename>bitbake-prserv</filename> command:
6175 <literallayout class='monospaced'>
6176 bitbake-prserv &dash;&dash;host <replaceable>ip</replaceable> &dash;&dash;port <replaceable>port</replaceable> &dash;&dash;start
6177 </literallayout>
6178 In addition to hand-starting the service, you need to
6179 update the <filename>local.conf</filename> file of each
6180 building system as described earlier so each system
6181 points to the server and port.
6182 </para>
6183
6184 <para>
6185 It is also recommended you use build history, which adds
6186 some sanity checks to package versions, in conjunction with
6187 the server that is running the PR Service.
6188 To enable build history, add the following to each building
6189 system's <filename>local.conf</filename> file:
6190 <literallayout class='monospaced'>
6191 # It is recommended to activate "buildhistory" for testing the PR service
6192 INHERIT += "buildhistory"
6193 BUILDHISTORY_COMMIT = "1"
6194 </literallayout>
6195 For information on build history, see the
6196 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
6197 section in the Yocto Project Reference Manual.
6198 </para>
6199
6200 <note>
6201 <para>The OpenEmbedded build system does not maintain
6202 <filename>PR</filename> information as part of the
6203 shared state (sstate) packages.
6204 If you maintain an sstate feed, its expected that either
6205 all your building systems that contribute to the sstate
6206 feed use a shared PR Service, or you do not run a PR
6207 Service on any of your building systems.
6208 Having some systems use a PR Service while others do
6209 not leads to obvious problems.</para>
6210 <para>For more information on shared state, see the
6211 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
6212 section in the Yocto Project Reference Manual.</para>
6213 </note>
6214 </section>
6215
6216 <section id='manually-bumping-pr'>
6217 <title>Manually Bumping PR</title>
6218
6219 <para>
6220 The alternative to setting up a PR Service is to manually
6221 bump the
6222 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6223 variable.
6224 </para>
6225
6226 <para>
6227 If a committed change results in changing the package output,
6228 then the value of the PR variable needs to be increased
6229 (or "bumped") as part of that commit.
6230 For new recipes you should add the <filename>PR</filename>
6231 variable and set its initial value equal to "r0", which is the default.
6232 Even though the default value is "r0", the practice of adding it to a new recipe makes
6233 it harder to forget to bump the variable when you make changes
6234 to the recipe in future.
6235 </para>
6236
6237 <para>
6238 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
6239 you can also use the
6240 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
6241 variable to ensure that
6242 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
6243 <filename>.inc</filename> file itself is changed.
6244 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
6245 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
6246 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
6247 If the <filename>.inc</filename> file is changed then its
6248 <filename>INC_PR</filename> should be incremented.
6249 </para>
6250
6251 <para>
6252 When upgrading the version of a package, assuming the
6253 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
6254 changes, the <filename>PR</filename> variable should be
6255 reset to "r0" (or "$(INC_PR).0" if you are using
6256 <filename>INC_PR</filename>).
6257 </para>
6258
6259 <para>
6260 Usually, version increases occur only to packages.
6261 However, if for some reason <filename>PV</filename> changes but does not
6262 increase, you can increase the
6263 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
6264 variable (Package Epoch).
6265 The <filename>PE</filename> variable defaults to "0".
6266 </para>
6267
6268 <para>
6269 Version numbering strives to follow the
6270 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
6271 Debian Version Field Policy Guidelines</ulink>.
6272 These guidelines define how versions are compared and what "increasing" a version means.
6273 </para>
6274 </section>
6275 </section>
6276
6277 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
6278 <title>Handling a Package Name Alias</title>
6279 <para>
6280 Sometimes a package name you are using might exist under
6281 an alias or as a similarly named package in a different
6282 distribution.
6283 The OpenEmbedded build system implements a
6284 <filename>do_distro_check</filename>
6285 task that automatically connects to major distributions
6286 and checks for these situations.
6287 If the package exists under a different name in a different
6288 distribution, you get a <filename>distro_check</filename>
6289 mismatch.
6290 You can resolve this problem by defining a per-distro recipe
6291 name alias using the
6292 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
6293 variable.
6294 </para>
6295
6296 <para>
6297 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
6298 variable:
6299 <literallayout class='monospaced'>
6300 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
6301 distro2=package_name_alias2 \
6302 distro3=package_name_alias3 \
6303 ..."
6304 </literallayout>
6305 </para>
6306
6307 <para>
6308 If you have more than one distribution alias, separate them with a space.
6309 Note that the build system currently automatically checks the
6310 Fedora, OpenSUSE, Debian, Ubuntu,
6311 and Mandriva distributions for source package recipes without having to specify them
6312 using the <filename>DISTRO_PN_ALIAS</filename> variable.
6313 For example, the following command generates a report that lists the Linux distributions
6314 that include the sources for each of the recipes.
6315 <literallayout class='monospaced'>
6316 $ bitbake world -f -c distro_check
6317 </literallayout>
6318 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
6319 file found in the
6320 <link linkend='source-directory'>Source Directory</link>.
6321 </para>
6322 </section>
6323
6324 <section id='handling-optional-module-packaging'>
6325 <title>Handling Optional Module Packaging</title>
6326
6327 <para>
6328 Many pieces of software split functionality into optional
6329 modules (or plug-ins) and the plug-ins that are built
6330 might depend on configuration options.
6331 To avoid having to duplicate the logic that determines what
6332 modules are available in your recipe or to avoid having
6333 to package each module by hand, the OpenEmbedded build system
6334 provides functionality to handle module packaging dynamically.
6335 </para>
6336
6337 <para>
6338 To handle optional module packaging, you need to do two things:
6339 <itemizedlist>
6340 <listitem><para>Ensure the module packaging is actually
6341 done.</para></listitem>
6342 <listitem><para>Ensure that any dependencies on optional
6343 modules from other recipes are satisfied by your recipe.
6344 </para></listitem>
6345 </itemizedlist>
6346 </para>
6347
6348 <section id='making-sure-the-packaging-is-done'>
6349 <title>Making Sure the Packaging is Done</title>
6350
6351 <para>
6352 To ensure the module packaging actually gets done, you use
6353 the <filename>do_split_packages</filename> function within
6354 the <filename>populate_packages</filename> Python function
6355 in your recipe.
6356 The <filename>do_split_packages</filename> function
6357 searches for a pattern of files or directories under a
6358 specified path and creates a package for each one it finds
6359 by appending to the
6360 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
6361 variable and setting the appropriate values for
6362 <filename>FILES_packagename</filename>,
6363 <filename>RDEPENDS_packagename</filename>,
6364 <filename>DESCRIPTION_packagename</filename>, and so forth.
6365 Here is an example from the <filename>lighttpd</filename>
6366 recipe:
6367 <literallayout class='monospaced'>
6368 python populate_packages_prepend () {
6369 lighttpd_libdir = d.expand('${libdir}')
6370 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
6371 'lighttpd-module-%s', 'Lighttpd module for %s',
6372 extra_depends='')
6373 }
6374 </literallayout>
6375 The previous example specifies a number of things in the
6376 call to <filename>do_split_packages</filename>.
6377 <itemizedlist>
6378 <listitem><para>A directory within the files installed
6379 by your recipe through <filename>do_install</filename>
6380 in which to search.</para></listitem>
6381 <listitem><para>A regular expression used to match module
6382 files in that directory.
6383 In the example, note the parentheses () that mark
6384 the part of the expression from which the module
6385 name should be derived.</para></listitem>
6386 <listitem><para>A pattern to use for the package names.
6387 </para></listitem>
6388 <listitem><para>A description for each package.
6389 </para></listitem>
6390 <listitem><para>An empty string for
6391 <filename>extra_depends</filename>, which disables
6392 the default dependency on the main
6393 <filename>lighttpd</filename> package.
6394 Thus, if a file in <filename>${libdir}</filename>
6395 called <filename>mod_alias.so</filename> is found,
6396 a package called <filename>lighttpd-module-alias</filename>
6397 is created for it and the
6398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
6399 is set to "Lighttpd module for alias".</para></listitem>
6400 </itemizedlist>
6401 </para>
6402
6403 <para>
6404 Often, packaging modules is as simple as the previous
6405 example.
6406 However, more advanced options exist that you can use
6407 within <filename>do_split_packages</filename> to modify its
6408 behavior.
6409 And, if you need to, you can add more logic by specifying
6410 a hook function that is called for each package.
6411 It is also perfectly acceptable to call
6412 <filename>do_split_packages</filename> multiple times if
6413 you have more than one set of modules to package.
6414 </para>
6415
6416 <para>
6417 For more examples that show how to use
6418 <filename>do_split_packages</filename>, see the
6419 <filename>connman.inc</filename> file in the
6420 <filename>meta/recipes-connectivity/connman/</filename>
6421 directory of the <filename>poky</filename>
6422 <link linkend='yocto-project-repositories'>source repository</link>.
6423 You can also find examples in
6424 <filename>meta/classes/kernel.bbclass</filename>.
6425 </para>
6426
6427 <para>
6428 Following is a reference that shows
6429 <filename>do_split_packages</filename> mandatory and
6430 optional arguments:
6431 <literallayout class='monospaced'>
6432 Mandatory arguments
6433
6434 root
6435 The path in which to search
6436 file_regex
6437 Regular expression to match searched files.
6438 Use parentheses () to mark the part of this
6439 expression that should be used to derive the
6440 module name (to be substituted where %s is
6441 used in other function arguments as noted below)
6442 output_pattern
6443 Pattern to use for the package names. Must
6444 include %s.
6445 description
6446 Description to set for each package. Must
6447 include %s.
6448
6449 Optional arguments
6450
6451 postinst
6452 Postinstall script to use for all packages
6453 (as a string)
6454 recursive
6455 True to perform a recursive search - default
6456 False
6457 hook
6458 A hook function to be called for every match.
6459 The function will be called with the following
6460 arguments (in the order listed):
6461
6462 f
6463 Full path to the file/directory match
6464 pkg
6465 The package name
6466 file_regex
6467 As above
6468 output_pattern
6469 As above
6470 modulename
6471 The module name derived using file_regex
6472
6473 extra_depends
6474 Extra runtime dependencies (RDEPENDS) to be
6475 set for all packages. The default value of None
6476 causes a dependency on the main package
6477 (${PN}) - if you do not want this, pass empty
6478 string '' for this parameter.
6479 aux_files_pattern
6480 Extra item(s) to be added to FILES for each
6481 package. Can be a single string item or a list
6482 of strings for multiple items. Must include %s.
6483 postrm
6484 postrm script to use for all packages (as a
6485 string)
6486 allow_dirs
6487 True to allow directories to be matched -
6488 default False
6489 prepend
6490 If True, prepend created packages to PACKAGES
6491 instead of the default False which appends them
6492 match_path
6493 match file_regex on the whole relative path to
6494 the root rather than just the file name
6495 aux_files_pattern_verbatim
6496 Extra item(s) to be added to FILES for each
6497 package, using the actual derived module name
6498 rather than converting it to something legal
6499 for a package name. Can be a single string item
6500 or a list of strings for multiple items. Must
6501 include %s.
6502 allow_links
6503 True to allow symlinks to be matched - default
6504 False
6505 summary
6506 Summary to set for each package. Must include %s;
6507 defaults to description if not set.
6508 </literallayout>
6509 </para>
6510 </section>
6511
6512 <section id='satisfying-dependencies'>
6513 <title>Satisfying Dependencies</title>
6514
6515 <para>
6516 The second part for handling optional module packaging
6517 is to ensure that any dependencies on optional modules
6518 from other recipes are satisfied by your recipe.
6519 You can be sure these dependencies are satisfied by
6520 using the
6521 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
6522 Here is an example that continues with the
6523 <filename>lighttpd</filename> recipe shown earlier:
6524 <literallayout class='monospaced'>
6525 PACKAGES_DYNAMIC = "lighttpd-module-.*"
6526 </literallayout>
6527 The name specified in the regular expression can of
6528 course be anything.
6529 In this example, it is <filename>lighttpd-module-</filename>
6530 and is specified as the prefix to ensure that any
6531 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
6532 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
6533 on a package name starting with the prefix are satisfied
6534 during build time.
6535 If you are using <filename>do_split_packages</filename>
6536 as described in the previous section, the value you put in
6537 <filename>PACKAGES_DYNAMIC</filename> should correspond to
6538 the name pattern specified in the call to
6539 <filename>do_split_packages</filename>.
6540 </para>
6541 </section>
6542 </section>
6543
6544 <section id='using-runtime-package-management'>
6545 <title>Using Runtime Package Management</title>
6546
6547 <para>
6548 During a build, BitBake always transforms a recipe into one or
6549 more packages.
6550 For example, BitBake takes the <filename>bash</filename> recipe
6551 and currently produces the <filename>bash-dbg</filename>,
6552 <filename>bash-staticdev</filename>,
6553 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
6554 <filename>bash-locale</filename>, and
6555 <filename>bash</filename> packages.
6556 Not all generated packages are included in an image.
6557 </para>
6558
6559 <para>
6560 In several situations, you might need to update, add, remove,
6561 or query the packages on a target device at runtime
6562 (i.e. without having to generate a new image).
6563 Examples of such situations include:
6564 <itemizedlist>
6565 <listitem><para>
6566 You want to provide in-the-field updates to deployed
6567 devices (e.g. security updates).
6568 </para></listitem>
6569 <listitem><para>
6570 You want to have a fast turn-around development cycle
6571 for one or more applications that run on your device.
6572 </para></listitem>
6573 <listitem><para>
6574 You want to temporarily install the "debug" packages
6575 of various applications on your device so that
6576 debugging can be greatly improved by allowing
6577 access to symbols and source debugging.
6578 </para></listitem>
6579 <listitem><para>
6580 You want to deploy a more minimal package selection of
6581 your device but allow in-the-field updates to add a
6582 larger selection for customization.
6583 </para></listitem>
6584 </itemizedlist>
6585 </para>
6586
6587 <para>
6588 In all these situations, you have something similar to a more
6589 traditional Linux distribution in that in-field devices
6590 are able to receive pre-compiled packages from a server for
6591 installation or update.
6592 Being able to install these packages on a running,
6593 in-field device is what is termed "runtime package
6594 management".
6595 </para>
6596
6597 <para>
6598 In order to use runtime package management, you
6599 need a host/server machine that serves up the pre-compiled
6600 packages plus the required metadata.
6601 You also need package manipulation tools on the target.
6602 The build machine is a likely candidate to act as the server.
6603 However, that machine does not necessarily have to be the
6604 package server.
6605 The build machine could push its artifacts to another machine
6606 that acts as the server (e.g. Internet-facing).
6607 </para>
6608
6609 <para>
6610 A simple build that targets just one device produces
6611 more than one package database.
6612 In other words, the packages produced by a build are separated
6613 out into a couple of different package groupings based on
6614 criteria such as the target's CPU architecture, the target
6615 board, or the C library used on the target.
6616 For example, a build targeting the <filename>qemuarm</filename>
6617 device produces the following three package databases:
6618 <filename>all</filename>, <filename>armv5te</filename>, and
6619 <filename>qemuarm</filename>.
6620 If you wanted your <filename>qemuarm</filename> device to be
6621 aware of all the packages that were available to it,
6622 you would need to point it to each of these databases
6623 individually.
6624 In a similar way, a traditional Linux distribution usually is
6625 configured to be aware of a number of software repositories
6626 from which it retrieves packages.
6627 </para>
6628
6629 <para>
6630 Using runtime package management is completely optional and
6631 not required for a successful build or deployment in any
6632 way.
6633 But if you want to make use of runtime package management,
6634 you need to do a couple things above and beyond the basics.
6635 The remainder of this section describes what you need to do.
6636 </para>
6637
6638 <section id='runtime-package-management-build'>
6639 <title>Build Considerations</title>
6640
6641 <para>
6642 This section describes build considerations that you need
6643 to be aware of in order to provide support for runtime
6644 package management.
6645 </para>
6646
6647 <para>
6648 When BitBake generates packages it needs to know
6649 what format or formats to use.
6650 In your configuration, you use the
6651 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
6652 variable to specify the format.
6653 <note>
6654 You can choose to have more than one format but you must
6655 provide at least one.
6656 </note>
6657 </para>
6658
6659 <para>
6660 If you would like your image to start off with a basic
6661 package database of the packages in your current build
6662 as well as have the relevant tools available on the
6663 target for runtime package management, you can include
6664 "package-management" in the
6665 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6666 variable.
6667 Including "package-management" in this
6668 configuration variable ensures that when the image
6669 is assembled for your target, the image includes
6670 the currently-known package databases as well as
6671 the target-specific tools required for runtime
6672 package management to be performed on the target.
6673 However, this is not strictly necessary.
6674 You could start your image off without any databases
6675 but only include the required on-target package
6676 tool(s).
6677 As an example, you could include "opkg" in your
6678 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
6679 variable if you are using the IPK package format.
6680 You can then initialize your target's package database(s)
6681 later once your image is up and running.
6682 </para>
6683
6684 <para>
6685 Whenever you perform any sort of build step that can
6686 potentially generate a package or modify an existing
6687 package, it is always a good idea to re-generate the
6688 package index with:
6689 <literallayout class='monospaced'>
6690 $ bitbake package-index
6691 </literallayout>
6692 Realize that it is not sufficient to simply do the
6693 following:
6694 <literallayout class='monospaced'>
6695 $ bitbake <replaceable>some-package</replaceable> package-index
6696 </literallayout>
6697 This is because BitBake does not properly schedule the
6698 <filename>package-index</filename> target fully after any
6699 other target has completed.
6700 Thus, be sure to run the package update step separately.
6701 </para>
6702
6703 <para>
6704 As described below in the
6705 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
6706 section, if you are using IPK as your package format, you
6707 can make use of the
6708 <filename>distro-feed-configs</filename> recipe provided
6709 by <filename>meta-oe</filename> in order to configure your
6710 target to use your IPK databases.
6711 </para>
6712
6713 <para>
6714 When your build is complete, your packages reside in the
6715 <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
6716 directory.
6717 For example, if <filename>${TMPDIR}</filename>
6718 is <filename>tmp</filename> and your selected package type
6719 is IPK, then your IPK packages are available in
6720 <filename>tmp/deploy/ipk</filename>.
6721 </para>
6722 </section>
6723
6724 <section id='runtime-package-management-server'>
6725 <title>Host or Server Machine Setup</title>
6726
6727 <para>
6728 Typically, packages are served from a server using
6729 HTTP.
6730 However, other protocols are possible.
6731 If you want to use HTTP, then setup and configure a
6732 web server, such as Apache 2 or lighttpd, on the machine
6733 serving the packages.
6734 </para>
6735
6736 <para>
6737 As previously mentioned, the build machine can act as the
6738 package server.
6739 In the following sections that describe server machine
6740 setups, the build machine is assumed to also be the server.
6741 </para>
6742
6743 <section id='package-server-apache'>
6744 <title>Serving Packages via Apache 2</title>
6745
6746 <para>
6747 This example assumes you are using the Apache 2
6748 server:
6749 <orderedlist>
6750 <listitem><para>
6751 Add the directory to your Apache
6752 configuration, which you can find at
6753 <filename>/etc/httpd/conf/httpd.conf</filename>.
6754 Use commands similar to these on the
6755 development system.
6756 These example commands assume a top-level
6757 <link linkend='source-directory'>Source Directory</link>
6758 named <filename>poky</filename> in your home
6759 directory.
6760 The example also assumes an RPM package type.
6761 If you are using a different package type, such
6762 as IPK, use "ipk" in the pathnames:
6763 <literallayout class='monospaced'>
6764 &lt;VirtualHost *:80&gt;
6765 ....
6766 Alias /rpm ~/poky/build/tmp/deploy/rpm
6767 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
6768 Options +Indexes
6769 &lt;/Directory&gt;
6770 &lt;/VirtualHost&gt;
6771 </literallayout></para></listitem>
6772 <listitem><para>
6773 Reload the Apache configuration as described
6774 in this step.
6775 For all commands, be sure you have root
6776 privileges.
6777 </para>
6778
6779 <para>
6780 If your development system is using Fedora or
6781 CentOS, use the following:
6782 <literallayout class='monospaced'>
6783 # service httpd reload
6784 </literallayout>
6785 For Ubuntu and Debian, use the following:
6786 <literallayout class='monospaced'>
6787 # /etc/init.d/apache2 reload
6788 </literallayout>
6789 For OpenSUSE, use the following:
6790 <literallayout class='monospaced'>
6791 # /etc/init.d/apache2 reload
6792 </literallayout></para></listitem>
6793 <listitem><para>
6794 If you are using Security-Enhanced Linux
6795 (SELinux), you need to label the files as
6796 being accessible through Apache.
6797 Use the following command from the development
6798 host.
6799 This example assumes RPM package types:
6800 <literallayout class='monospaced'>
6801 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
6802 </literallayout></para></listitem>
6803 </orderedlist>
6804 </para>
6805 </section>
6806
6807 <section id='package-server-lighttpd'>
6808 <title>Serving Packages via lighttpd</title>
6809
6810 <para>
6811 If you are using lighttpd, all you need
6812 to do is to provide a link from your
6813 <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
6814 directory to lighttpd's document-root.
6815 You can determine the specifics of your lighttpd
6816 installation by looking through its configuration file,
6817 which is usually found at:
6818 <filename>/etc/lighttpd/lighttpd.conf</filename>.
6819 </para>
6820
6821 <para>
6822 For example, if you are using IPK, lighttpd's
6823 document-root is set to
6824 <filename>/var/www/lighttpd</filename>, and you had
6825 packages for a target named "BOARD",
6826 then you might create a link from your build location
6827 to lighttpd's document-root as follows:
6828 <literallayout class='monospaced'>
6829 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
6830 </literallayout>
6831 </para>
6832
6833 <para>
6834 At this point, you need to start the lighttpd server.
6835 The method used to start the server varies by
6836 distribution.
6837 However, one basic method that starts it by hand is:
6838 <literallayout class='monospaced'>
6839 # lighttpd -f /etc/lighttpd/lighttpd.conf
6840 </literallayout>
6841 </para>
6842 </section>
6843 </section>
6844
6845 <section id='runtime-package-management-target'>
6846 <title>Target Setup</title>
6847
6848 <para>
6849 Setting up the target differs depending on the
6850 package management system.
6851 This section provides information for RPM and IPK.
6852 </para>
6853
6854 <section id='runtime-package-management-target-rpm'>
6855 <title>Using RPM</title>
6856
6857 <para>
6858 The application for performing runtime package
6859 management of RPM packages on the target is called
6860 <filename>smart</filename>.
6861 </para>
6862
6863 <para>
6864 On the target machine, you need to inform
6865 <filename>smart</filename> of every package database
6866 you want to use.
6867 As an example, suppose your target device can use the
6868 following three package databases from a server named
6869 <filename>server.name</filename>:
6870 <filename>all</filename>, <filename>i586</filename>,
6871 and <filename>qemux86</filename>.
6872 Given this example, issue the following commands on the
6873 target:
6874 <literallayout class='monospaced'>
6875 # smart channel &dash;&dash;add all type=rpm-md baseurl=http://server.name/rpm/all
6876 # smart channel &dash;&dash;add i585 type=rpm-md baseurl=http://server.name/rpm/i586
6877 # smart channel &dash;&dash;add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
6878 </literallayout>
6879 Also from the target machine, fetch the repository
6880 information using this command:
6881 <literallayout class='monospaced'>
6882 # smart update
6883 </literallayout>
6884 You can now use the <filename>smart query</filename>
6885 and <filename>smart install</filename> commands to
6886 find and install packages from the repositories.
6887 </para>
6888 </section>
6889
6890 <section id='runtime-package-management-target-ipk'>
6891 <title>Using IPK</title>
6892
6893 <para>
6894 The application for performing runtime package
6895 management of IPK packages on the target is called
6896 <filename>opkg</filename>.
6897 </para>
6898
6899 <para>
6900 In order to inform <filename>opkg</filename> of the
6901 package databases you want to use, simply create one
6902 or more <filename>*.conf</filename> files in the
6903 <filename>/etc/opkg</filename> directory on the target.
6904 The <filename>opkg</filename> application uses them
6905 to find its available package databases.
6906 As an example, suppose you configured your HTTP server
6907 on your machine named
6908 <filename>www.mysite.com</filename> to serve files
6909 from a <filename>BOARD-dir</filename> directory under
6910 its document-root.
6911 In this case, you might create a configuration
6912 file on the target called
6913 <filename>/etc/opkg/base-feeds.conf</filename> that
6914 contains:
6915 <literallayout class='monospaced'>
6916 src/gz all http://www.mysite.com/BOARD-dir/all
6917 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
6918 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
6919 </literallayout>
6920 </para>
6921
6922 <para>
6923 As a way of making it easier to generate and make
6924 these IPK configuration files available on your
6925 target, simply define
6926 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
6927 to point to your server and the location within the
6928 document-root which contains the databases.
6929 For example: if you are serving your packages over
6930 HTTP, your server's IP address is 192.168.7.1, and
6931 your databases are located in a directory called
6932 <filename>BOARD-dir</filename> underneath your HTTP
6933 server's document-root, you need to set
6934 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
6935 <filename>http://192.168.7.1/BOARD-dir</filename> and
6936 a set of configuration files will be generated for you
6937 in your target to work with this feed.
6938 </para>
6939
6940 <para>
6941 On the target machine, fetch (or refresh) the
6942 repository information using this command:
6943 <literallayout class='monospaced'>
6944 # opkg update
6945 </literallayout>
6946 You can now use the <filename>opkg list</filename> and
6947 <filename>opkg install</filename> commands to find and
6948 install packages from the repositories.
6949 </para>
6950 </section>
6951 </section>
6952 </section>
6953
6954 <section id='testing-packages-with-ptest'>
6955 <title>Testing Packages With ptest</title>
6956
6957 <para>
6958 A Package Test (ptest) runs tests against packages built
6959 by the OpenEmbedded build system on the target machine.
6960 A ptest contains at least two items: the actual test, and
6961 a shell script (<filename>run-ptest</filename>) that starts
6962 the test.
6963 The shell script that starts the test must not contain
6964 the actual test - the script only starts the test.
6965 On the other hand, the test can be anything from a simple
6966 shell script that runs a binary and checks the output to
6967 an elaborate system of test binaries and data files.
6968 </para>
6969
6970 <para>
6971 The test generates output in the format used by
6972 Automake:
6973 <literallayout class='monospaced'>
6974 <replaceable>result</replaceable>: <replaceable>testname</replaceable>
6975 </literallayout>
6976 where the result can be <filename>PASS</filename>,
6977 <filename>FAIL</filename>, or <filename>SKIP</filename>,
6978 and the testname can be any identifying string.
6979 </para>
6980
6981 <para>
6982 For a list of Yocto Project recipes that are already
6983 enabled with ptest, see the
6984 <ulink url='https://wiki.yoctoproject.org/wiki/Ptest'>Ptest</ulink>
6985 wiki page.
6986 <note>
6987 A recipe is "ptest-enabled" if it inherits the
6988 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
6989 class.
6990 </note>
6991 </para>
6992
6993 <section id='adding-ptest-to-your-build'>
6994 <title>Adding ptest to Your Build</title>
6995
6996 <para>
6997 To add package testing to your build, add the
6998 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
6999 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
7000 variables to your <filename>local.conf</filename> file,
7001 which is found in the
7002 <link linkend='build-directory'>Build Directory</link>:
7003 <literallayout class='monospaced'>
7004 DISTRO_FEATURES_append = " ptest"
7005 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
7006 </literallayout>
7007 Once your build is complete, the ptest files are installed
7008 into the
7009 <filename>/usr/lib/<replaceable>package</replaceable>/ptest</filename>
7010 directory within the image, where
7011 <filename><replaceable>package</replaceable></filename>
7012 is the name of the package.
7013 </para>
7014 </section>
7015
7016 <section id='running-ptest'>
7017 <title>Running ptest</title>
7018
7019 <para>
7020 The <filename>ptest-runner</filename> package installs a
7021 shell script that loops through all installed ptest test
7022 suites and runs them in sequence.
7023 Consequently, you might want to add this package to
7024 your image.
7025 </para>
7026 </section>
7027
7028 <section id='getting-your-package-ready'>
7029 <title>Getting Your Package Ready</title>
7030
7031 <para>
7032 In order to enable a recipe to run installed ptests
7033 on target hardware,
7034 you need to prepare the recipes that build the packages
7035 you want to test.
7036 Here is what you have to do for each recipe:
7037 <itemizedlist>
7038 <listitem><para><emphasis>Be sure the recipe
7039 inherits the
7040 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
7041 class:</emphasis>
7042 Include the following line in each recipe:
7043 <literallayout class='monospaced'>
7044 inherit ptest
7045 </literallayout>
7046 </para></listitem>
7047 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
7048 This script starts your test.
7049 Locate the script where you will refer to it
7050 using
7051 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
7052 Here is an example that starts a test for
7053 <filename>dbus</filename>:
7054 <literallayout class='monospaced'>
7055 #!/bin/sh
7056 cd test
7057 make -k runtest-TESTS
7058 </literallayout>
7059 </para></listitem>
7060 <listitem><para><emphasis>Ensure dependencies are
7061 met:</emphasis>
7062 If the test adds build or runtime dependencies
7063 that normally do not exist for the package
7064 (such as requiring "make" to run the test suite),
7065 use the
7066 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
7067 and
7068 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
7069 variables in your recipe in order for the package
7070 to meet the dependencies.
7071 Here is an example where the package has a runtime
7072 dependency on "make":
7073 <literallayout class='monospaced'>
7074 RDEPENDS_${PN}-ptest += "make"
7075 </literallayout>
7076 </para></listitem>
7077 <listitem><para><emphasis>Add a function to build the
7078 test suite:</emphasis>
7079 Not many packages support cross-compilation of
7080 their test suites.
7081 Consequently, you usually need to add a
7082 cross-compilation function to the package.
7083 </para>
7084 <para>Many packages based on Automake compile and
7085 run the test suite by using a single command
7086 such as <filename>make check</filename>.
7087 However, the native <filename>make check</filename>
7088 builds and runs on the same computer, while
7089 cross-compiling requires that the package is built
7090 on the host but executed on the target.
7091 The built version of Automake that ships with the
7092 Yocto Project includes a patch that separates
7093 building and execution.
7094 Consequently, packages that use the unaltered,
7095 patched version of <filename>make check</filename>
7096 automatically cross-compiles.</para>
7097 <para>Regardless, you still must add a
7098 <filename>do_compile_ptest</filename> function to
7099 build the test suite.
7100 Add a function similar to the following to your
7101 recipe:
7102 <literallayout class='monospaced'>
7103 do_compile_ptest() {
7104 oe_runmake buildtest-TESTS
7105 }
7106 </literallayout>
7107 </para></listitem>
7108 <listitem><para><emphasis>Ensure special configurations
7109 are set:</emphasis>
7110 If the package requires special configurations
7111 prior to compiling the test code, you must
7112 insert a <filename>do_configure_ptest</filename>
7113 function into the recipe.
7114 </para></listitem>
7115 <listitem><para><emphasis>Install the test
7116 suite:</emphasis>
7117 The <filename>ptest</filename> class
7118 automatically copies the file
7119 <filename>run-ptest</filename> to the target and
7120 then runs make <filename>install-ptest</filename>
7121 to run the tests.
7122 If this is not enough, you need to create a
7123 <filename>do_install_ptest</filename> function and
7124 make sure it gets called after the
7125 "make install-ptest" completes.
7126 </para></listitem>
7127 </itemizedlist>
7128 </para>
7129 </section>
7130 </section>
7131 </section>
7132
7133 <section id='working-with-source-files'>
7134 <title>Working with Source Files</title>
7135
7136 <para>
7137 The OpenEmbedded build system works with source files located
7138 through the
7139 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7140 variable.
7141 When you build something using BitBake, a big part of the operation
7142 is locating and downloading all the source tarballs.
7143 For images, downloading all the source for various packages can
7144 take a significant amount of time.
7145 </para>
7146
7147 <para>
7148 This section presents information for working with source
7149 files that can lead to more efficient use of resources and
7150 time.
7151 </para>
7152
7153 <section id='setting-up-effective-mirrors'>
7154 <title>Setting up Effective Mirrors</title>
7155
7156 <para>
7157 As mentioned, a good deal that goes into a Yocto Project
7158 build is simply downloading all of the source tarballs.
7159 Maybe you have been working with another build system
7160 (OpenEmbedded or Angstrom) for which you have built up a
7161 sizable directory of source tarballs.
7162 Or, perhaps someone else has such a directory for which you
7163 have read access.
7164 If so, you can save time by adding statements to your
7165 configuration file so that the build process checks local
7166 directories first for existing tarballs before checking the
7167 Internet.
7168 </para>
7169
7170 <para>
7171 Here is an efficient way to set it up in your
7172 <filename>local.conf</filename> file:
7173 <literallayout class='monospaced'>
7174 SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/"
7175 INHERIT += "own-mirrors"
7176 BB_GENERATE_MIRROR_TARBALLS = "1"
7177 # BB_NO_NETWORK = "1"
7178 </literallayout>
7179 </para>
7180
7181 <para>
7182 In the previous example, the
7183 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
7184 variable causes the OpenEmbedded build system to generate
7185 tarballs of the Git repositories and store them in the
7186 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
7187 directory.
7188 Due to performance reasons, generating and storing these
7189 tarballs is not the build system's default behavior.
7190 </para>
7191
7192 <para>
7193 You can also use the
7194 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
7195 variable.
7196 For an example, see the variable's glossary entry in the
7197 Yocto Project Reference Manual.
7198 </para>
7199 </section>
7200
7201 <section id='getting-source-files-and-suppressing-the-build'>
7202 <title>Getting Source Files and Suppressing the Build</title>
7203
7204 <para>
7205 Another technique you can use to ready yourself for a
7206 successive string of build operations, is to pre-fetch
7207 all the source files without actually starting a build.
7208 This technique lets you work through any download issues
7209 and ultimately gathers all the source files into your
7210 download directory
7211 <ulink url='&YOCTO_DOCS_REF_URL;#structure-build-downloads'><filename>build/downloads</filename></ulink>,
7212 which is located with
7213 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>.
7214 </para>
7215
7216 <para>
7217 Use the following BitBake command form to fetch all the
7218 necessary sources without starting the build:
7219 <literallayout class='monospaced'>
7220 $ bitbake -c fetchall <replaceable>target</replaceable>
7221 </literallayout>
7222 This variation of the BitBake command guarantees that you
7223 have all the sources for that BitBake target should you
7224 disconnect from the Internet and want to do the build
7225 later offline.
7226 </para>
7227 </section>
7228 </section>
7229
7230 <section id="building-software-from-an-external-source">
7231 <title>Building Software from an External Source</title>
7232
7233 <para>
7234 By default, the OpenEmbedded build system uses the
7235 <link linkend='build-directory'>Build Directory</link> when
7236 building source code.
7237 The build process involves fetching the source files, unpacking
7238 them, and then patching them if necessary before the build takes
7239 place.
7240 </para>
7241
7242 <para>
7243 Situations exist where you might want to build software from source
7244 files that are external to and thus outside of the
7245 OpenEmbedded build system.
7246 For example, suppose you have a project that includes a new BSP with
7247 a heavily customized kernel.
7248 And, you want to minimize exposing the build system to the
7249 development team so that they can focus on their project and
7250 maintain everyone's workflow as much as possible.
7251 In this case, you want a kernel source directory on the development
7252 machine where the development occurs.
7253 You want the recipe's
7254 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7255 variable to point to the external directory and use it as is, not
7256 copy it.
7257 </para>
7258
7259 <para>
7260 To build from software that comes from an external source, all you
7261 need to do is inherit the
7262 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
7263 class and then set the
7264 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
7265 variable to point to your external source code.
7266 Here are the statements to put in your
7267 <filename>local.conf</filename> file:
7268 <literallayout class='monospaced'>
7269 INHERIT += "externalsrc"
7270 EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
7271 </literallayout>
7272 </para>
7273
7274 <para>
7275 This next example shows how to accomplish the same thing by setting
7276 <filename>EXTERNALSRC</filename> in the recipe itself or in the
7277 recipe's append file:
7278 <literallayout class='monospaced'>
7279 EXTERNALSRC = "<replaceable>path</replaceable>"
7280 EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
7281 </literallayout>
7282 <note>
7283 In order for these settings to take effect, you must globally
7284 or locally inherit the
7285 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
7286 class.
7287 </note>
7288 </para>
7289
7290 <para>
7291 By default, <filename>externalsrc.bbclass</filename> builds
7292 the source code in a directory separate from the external source
7293 directory as specified by
7294 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
7295 If you need to have the source built in the same directory in
7296 which it resides, or some other nominated directory, you can set
7297 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
7298 to point to that directory:
7299 <literallayout class='monospaced'>
7300 EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
7301 </literallayout>
7302 </para>
7303 </section>
7304
7305 <section id="selecting-an-initialization-manager">
7306 <title>Selecting an Initialization Manager</title>
7307
7308 <para>
7309 By default, the Yocto Project uses SysVinit as the initialization
7310 manager.
7311 However, support also exists for systemd,
7312 which is a full replacement for init with
7313 parallel starting of services, reduced shell overhead and other
7314 features that are used by many distributions.
7315 </para>
7316
7317 <para>
7318 If you want to use SysVinit, you do
7319 not have to do anything.
7320 But, if you want to use systemd, you must
7321 take some steps as described in the following sections.
7322 </para>
7323
7324 <section id='using-systemd-exclusively'>
7325 <title>Using systemd Exclusively</title>
7326
7327 <para>
7328 Set the these variables in your distribution configuration
7329 file as follows:
7330 <literallayout class='monospaced'>
7331 DISTRO_FEATURES_append = " systemd"
7332 VIRTUAL-RUNTIME_init_manager = "systemd"
7333 </literallayout>
7334 You can also prevent the SysVinit
7335 distribution feature from
7336 being automatically enabled as follows:
7337 <literallayout class='monospaced'>
7338 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
7339 </literallayout>
7340 Doing so removes any redundant SysVinit scripts.
7341 </para>
7342
7343 <para>
7344 To remove initscripts from your image altogether,
7345 set this variable also:
7346 <literallayout class='monospaced'>
7347 VIRTUAL-RUNTIME_initscripts = ""
7348 </literallayout>
7349 </para>
7350
7351 <para>
7352 For information on the backfill variable, see
7353 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
7354 </para>
7355 </section>
7356
7357 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
7358 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
7359
7360 <para>
7361 Set these variables in your distribution configuration
7362 file as follows:
7363 <literallayout class='monospaced'>
7364 DISTRO_FEATURES_append = " systemd"
7365 VIRTUAL-RUNTIME_init_manager = "systemd"
7366 </literallayout>
7367 Doing so causes your main image to use the
7368 <filename>packagegroup-core-boot.bb</filename> recipe and
7369 systemd.
7370 The rescue/minimal image cannot use this package group.
7371 However, it can install SysVinit
7372 and the appropriate packages will have support for both
7373 systemd and SysVinit.
7374 </para>
7375 </section>
7376 </section>
7377
7378 <section id="platdev-appdev-srcrev">
7379 <title>Using an External SCM</title>
7380
7381 <para>
7382 If you're working on a recipe that pulls from an external Source
7383 Code Manager (SCM), it is possible to have the OpenEmbedded build
7384 system notice new recipe changes added to the SCM and then build
7385 the resulting packages that depend on the new recipes by using
7386 the latest versions.
7387 This only works for SCMs from which it is possible to get a
7388 sensible revision number for changes.
7389 Currently, you can do this with Apache Subversion (SVN), Git, and
7390 Bazaar (BZR) repositories.
7391 </para>
7392
7393 <para>
7394 To enable this behavior, the
7395 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
7396 of the recipe needs to reference
7397 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
7398 Here is an example:
7399 <literallayout class='monospaced'>
7400 PV = "1.2.3+git${SRCPV}
7401 </literallayout>
7402 Then, you can add the following to your
7403 <filename>local.conf</filename>:
7404 <literallayout class='monospaced'>
7405 SRCREV_pn-<replaceable>PN</replaceable> = "${AUTOREV}"
7406 </literallayout>
7407 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
7408 is the name of the recipe for which you want to enable automatic source
7409 revision updating.
7410 </para>
7411
7412 <para>
7413 If you do not want to update your local configuration file, you can
7414 add the following directly to the recipe to finish enabling
7415 the feature:
7416 <literallayout class='monospaced'>
7417 SRCREV = "${AUTOREV}"
7418 </literallayout>
7419 </para>
7420
7421 <para>
7422 The Yocto Project provides a distribution named
7423 <filename>poky-bleeding</filename>, whose configuration
7424 file contains the line:
7425 <literallayout class='monospaced'>
7426 require conf/distro/include/poky-floating-revisions.inc
7427 </literallayout>
7428 This line pulls in the listed include file that contains
7429 numerous lines of exactly that form:
7430 <literallayout class='monospaced'>
7431 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
7432 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
7433 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
7434 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
7435 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
7436 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
7437 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
7438 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
7439 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
7440 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
7441 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
7442 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
7443 SRCREV_pn-screenshot ?= "${AUTOREV}"
7444 SRCREV_pn-libfakekey ?= "${AUTOREV}"
7445 SRCREV_pn-oprofileui ?= "${AUTOREV}"
7446 .
7447 .
7448 .
7449 </literallayout>
7450 These lines allow you to experiment with building a
7451 distribution that tracks the latest development source
7452 for numerous packages.
7453 <note><title>Caution</title>
7454 The <filename>poky-bleeding</filename> distribution
7455 is not tested on a regular basis.
7456 Keep this in mind if you use it.
7457 </note>
7458 </para>
7459 </section>
7460
7461 <section id='creating-a-read-only-root-filesystem'>
7462 <title>Creating a Read-Only Root Filesystem</title>
7463
7464 <para>
7465 Suppose, for security reasons, you need to disable
7466 your target device's root filesystem's write permissions
7467 (i.e. you need a read-only root filesystem).
7468 Or, perhaps you are running the device's operating system
7469 from a read-only storage device.
7470 For either case, you can customize your image for
7471 that behavior.
7472 </para>
7473
7474 <note>
7475 Supporting a read-only root filesystem requires that the system and
7476 applications do not try to write to the root filesystem.
7477 You must configure all parts of the target system to write
7478 elsewhere, or to gracefully fail in the event of attempting to
7479 write to the root filesystem.
7480 </note>
7481
7482 <section id='creating-the-root-filesystem'>
7483 <title>Creating the Root Filesystem</title>
7484
7485 <para>
7486 To create the read-only root filesystem, simply add the
7487 "read-only-rootfs" feature to your image.
7488 Using either of the following statements in your
7489 image recipe or from within the
7490 <filename>local.conf</filename> file found in the
7491 <link linkend='build-directory'>Build Directory</link>
7492 causes the build system to create a read-only root filesystem:
7493 <literallayout class='monospaced'>
7494 IMAGE_FEATURES = "read-only-rootfs"
7495 </literallayout>
7496 or
7497 <literallayout class='monospaced'>
7498 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
7499 </literallayout>
7500 </para>
7501
7502 <para>
7503 For more information on how to use these variables, see the
7504 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
7505 section.
7506 For information on the variables, see
7507 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
7508 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
7509 </para>
7510 </section>
7511
7512 <section id='post-installation-scripts'>
7513 <title>Post-Installation Scripts</title>
7514
7515 <para>
7516 It is very important that you make sure all
7517 post-Installation (<filename>pkg_postinst</filename>) scripts
7518 for packages that are installed into the image can be run
7519 at the time when the root filesystem is created during the
7520 build on the host system.
7521 These scripts cannot attempt to run during first-boot on the
7522 target device.
7523 With the "read-only-rootfs" feature enabled,
7524 the build system checks during root filesystem creation to make
7525 sure all post-installation scripts succeed.
7526 If any of these scripts still need to be run after the root
7527 filesystem is created, the build immediately fails.
7528 These build-time checks ensure that the build fails
7529 rather than the target device fails later during its
7530 initial boot operation.
7531 </para>
7532
7533 <para>
7534 Most of the common post-installation scripts generated by the
7535 build system for the out-of-the-box Yocto Project are engineered
7536 so that they can run during root filesystem creation
7537 (e.g. post-installation scripts for caching fonts).
7538 However, if you create and add custom scripts, you need
7539 to be sure they can be run during this file system creation.
7540 </para>
7541
7542 <para>
7543 Here are some common problems that prevent
7544 post-installation scripts from running during root filesystem
7545 creation:
7546 <itemizedlist>
7547 <listitem><para>
7548 <emphasis>Not using $D in front of absolute
7549 paths:</emphasis>
7550 The build system defines
7551 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
7552 when the root filesystem is created.
7553 Furthermore, <filename>$D</filename> is blank when the
7554 script is run on the target device.
7555 This implies two purposes for <filename>$D</filename>:
7556 ensuring paths are valid in both the host and target
7557 environments, and checking to determine which
7558 environment is being used as a method for taking
7559 appropriate actions.
7560 </para></listitem>
7561 <listitem><para>
7562 <emphasis>Attempting to run processes that are
7563 specific to or dependent on the target
7564 architecture:</emphasis>
7565 You can work around these attempts by using native
7566 tools to accomplish the same tasks, or
7567 by alternatively running the processes under QEMU,
7568 which has the <filename>qemu_run_binary</filename>
7569 function.
7570 For more information, see the
7571 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
7572 class.</para></listitem>
7573 </itemizedlist>
7574 </para>
7575 </section>
7576
7577 <section id='areas-with-write-access'>
7578 <title>Areas With Write Access</title>
7579
7580 <para>
7581 With the "read-only-rootfs" feature enabled,
7582 any attempt by the target to write to the root filesystem at
7583 runtime fails.
7584 Consequently, you must make sure that you configure processes
7585 and applications that attempt these types of writes do so
7586 to directories with write access (e.g.
7587 <filename>/tmp</filename> or <filename>/var/run</filename>).
7588 </para>
7589 </section>
7590 </section>
7591
7592 <section id="performing-automated-runtime-testing">
7593 <title>Performing Automated Runtime Testing</title>
7594
7595 <para>
7596 The OpenEmbedded build system makes available a series of automated
7597 tests for images to verify runtime functionality.
7598 You can run these tests on either QEMU or actual target hardware.
7599 Tests are written in Python making use of the
7600 <filename>unittest</filename> module, and the majority of them
7601 run commands on the target system over SSH.
7602 This section describes how you set up the environment to use these
7603 tests, run available tests, and write and add your own tests.
7604 </para>
7605
7606 <section id='enabling-tests'>
7607 <title>Enabling Tests</title>
7608
7609 <para>
7610 Depending on whether you are planning to run tests using
7611 QEMU or on the hardware, you have to take
7612 different steps to enable the tests.
7613 See the following subsections for information on how to
7614 enable both types of tests.
7615 </para>
7616
7617 <section id='qemu-image-enabling-tests'>
7618 <title>Enabling Runtime Tests on QEMU</title>
7619
7620 <para>
7621 In order to run tests, you need to do the following:
7622 <itemizedlist>
7623 <listitem><para><emphasis>Set up to avoid interaction
7624 with <filename>sudo</filename> for networking:</emphasis>
7625 To accomplish this, you must do one of the
7626 following:
7627 <itemizedlist>
7628 <listitem><para>Add
7629 <filename>NOPASSWD</filename> for your user
7630 in <filename>/etc/sudoers</filename> either for
7631 all commands or just for
7632 <filename>runqemu-ifup</filename>.
7633 You must provide the full path as that can
7634 change if you are using multiple clones of the
7635 source repository.
7636 <note>
7637 On some distributions, you also need to
7638 comment out "Defaults requiretty" in
7639 <filename>/etc/sudoers</filename>.
7640 </note></para></listitem>
7641 <listitem><para>Manually configure a tap interface
7642 for your system.</para></listitem>
7643 <listitem><para>Run as root the script in
7644 <filename>scripts/runqemu-gen-tapdevs</filename>,
7645 which should generate a list of tap devices.
7646 This is the option typically chosen for
7647 Autobuilder-type environments.
7648 </para></listitem>
7649 </itemizedlist></para></listitem>
7650 <listitem><para><emphasis>Set the
7651 <filename>DISPLAY</filename> variable:</emphasis>
7652 You need to set this variable so that you have an X
7653 server available (e.g. start
7654 <filename>vncserver</filename> for a headless machine).
7655 </para></listitem>
7656 <listitem><para><emphasis>Be sure your host's firewall
7657 accepts incoming connections from
7658 192.168.7.0/24:</emphasis>
7659 Some of the tests (in particular smart tests) start an
7660 HTTP server on a random high number port, which is
7661 used to serve files to the target.
7662 The smart module serves
7663 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
7664 smart channel commands. That means your host's firewall
7665 must accept incoming connections from 192.168.7.0/24,
7666 which is the default IP range used for tap devices
7667 by <filename>runqemu</filename>.</para></listitem>
7668 </itemizedlist>
7669 </para>
7670
7671 <para>
7672 Once you start running the tests, the following happens:
7673 <orderedlist>
7674 <listitem><para>A copy of the root filesystem is written
7675 to <filename>${WORKDIR}/testimage</filename>.
7676 </para></listitem>
7677 <listitem><para>The image is booted under QEMU using the
7678 standard <filename>runqemu</filename> script.
7679 </para></listitem>
7680 <listitem><para>A default timeout of 500 seconds occurs
7681 to allow for the boot process to reach the login prompt.
7682 You can change the timeout period by setting
7683 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
7684 in the <filename>local.conf</filename> file.
7685 </para></listitem>
7686 <listitem><para>Once the boot process is reached and the
7687 login prompt appears, the tests run.
7688 The full boot log is written to
7689 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
7690 </para></listitem>
7691 <listitem><para>Each test module loads in the order found
7692 in <filename>TEST_SUITES</filename>.
7693 You can find the full output of the commands run over
7694 SSH in
7695 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
7696 </para></listitem>
7697 <listitem><para>If no failures occur, the task running the
7698 tests ends successfully.
7699 You can find the output from the
7700 <filename>unittest</filename> in the task log at
7701 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
7702 </para></listitem>
7703 </orderedlist>
7704 </para>
7705 </section>
7706
7707 <section id='hardware-image-enabling-tests'>
7708 <title>Enabling Runtime Tests on Hardware</title>
7709
7710 <para>
7711 The OpenEmbedded build system can run tests on real
7712 hardware, and for certain devices it can also deploy
7713 the image to be tested onto the device beforehand.
7714 </para>
7715
7716 <para>
7717 For automated deployment, a "master image" is installed
7718 onto the hardware once as part of setup.
7719 Then, each time tests are to be run, the following
7720 occurs:
7721 <orderedlist>
7722 <listitem><para>The master image is booted into and
7723 used to write the image to be tested to
7724 a second partition.
7725 </para></listitem>
7726 <listitem><para>The device is then rebooted using an
7727 external script that you need to provide.
7728 </para></listitem>
7729 <listitem><para>The device boots into the image to be
7730 tested.
7731 </para></listitem>
7732 </orderedlist>
7733 </para>
7734
7735 <para>
7736 When running tests (independent of whether the image
7737 has been deployed automatically or not), the device is
7738 expected to be connected to a network on a
7739 pre-determined IP address.
7740 You can either use static IP addresses written into
7741 the image, or set the image to use DHCP and have your
7742 DHCP server on the test network assign a known IP address
7743 based on the MAC address of the device.
7744 </para>
7745
7746 <para>
7747 In order to run tests on hardware, you need to set
7748 <filename>TEST_TARGET</filename> to an appropriate value.
7749 For QEMU, you do not have to change anything, the default
7750 value is "QemuTarget".
7751 For running tests on hardware, the following options exist:
7752 <itemizedlist>
7753 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
7754 Choose "SimpleRemoteTarget" if you are going to
7755 run tests on a target system that is already
7756 running the image to be tested and is available
7757 on the network.
7758 You can use "SimpleRemoteTarget" in conjunction
7759 with either real hardware or an image running
7760 within a separately started QEMU or any
7761 other virtual machine manager.
7762 </para></listitem>
7763 <listitem><para><emphasis>"GummibootTarget":</emphasis>
7764 Choose "GummibootTarget" if your hardware is
7765 an EFI-based machine with
7766 <filename>gummiboot</filename> as bootloader and
7767 <filename>core-image-testmaster</filename>
7768 (or something similar) is installed.
7769 Also, your hardware under test must be in a
7770 DHCP-enabled network that gives it the same IP
7771 address for each reboot.</para>
7772 <para>If you choose "GummibootTarget", there are
7773 additional requirements and considerations.
7774 See the
7775 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
7776 section, which follows, for more information.
7777 </para></listitem>
7778 <listitem><para><emphasis>"BeagleBoneTarget":</emphasis>
7779 Choose "BeagleBoneTarget" if you are deploying
7780 images and running tests on the BeagleBone
7781 "Black" or original "White" hardware.
7782 For information on how to use these tests, see the
7783 comments at the top of the BeagleBoneTarget
7784 <filename>meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py</filename>
7785 file.
7786 </para></listitem>
7787 <listitem><para><emphasis>"EdgeRouterTarget":</emphasis>
7788 Choose "EdgeRouterTarget" is you are deploying
7789 images and running tests on the Ubiquiti Networks
7790 EdgeRouter Lite.
7791 For information on how to use these tests, see the
7792 comments at the top of the EdgeRouterTarget
7793 <filename>meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py</filename>
7794 file.
7795 </para></listitem>
7796 <listitem><para><emphasis>"GrubTarget":</emphasis>
7797 Choose the "supports deploying images and running
7798 tests on any generic PC that boots using GRUB.
7799 For information on how to use these tests, see the
7800 comments at the top of the GrubTarget
7801 <filename>meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py</filename>
7802 file.
7803 </para></listitem>
7804 <listitem><para><emphasis>"<replaceable>your-target</replaceable>":</emphasis>
7805 Create your own custom target if you want to run
7806 tests when you are deploying images and running
7807 tests on a custom machine within your BSP layer.
7808 To do this, you need to add a Python unit that
7809 defines the target class under
7810 <filename>lib/oeqa/controllers/</filename> within
7811 your layer.
7812 You must also provide an empty
7813 <filename>__init__.py</filename>.
7814 For examples, see files in
7815 <filename>meta-yocto-bsp/lib/oeqa/controllers/</filename>.
7816 </para></listitem>
7817 </itemizedlist>
7818 </para>
7819 </section>
7820
7821 <section id='selecting-gummiboottarget'>
7822 <title>Selecting GummibootTarget</title>
7823
7824 <para>
7825 If you did not set <filename>TEST_TARGET</filename> to
7826 "GummibootTarget", then you do not need any information
7827 in this section.
7828 You can skip down to the
7829 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
7830 section.
7831 </para>
7832
7833 <para>
7834 If you did set <filename>TEST_TARGET</filename> to
7835 "GummibootTarget", you also need to perform a one-time
7836 setup of your master image by doing the following:
7837 <orderedlist>
7838 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
7839 Be sure that <filename>EFI_PROVIDER</filename>
7840 is as follows:
7841 <literallayout class='monospaced'>
7842 EFI_PROVIDER = "gummiboot"
7843 </literallayout>
7844 </para></listitem>
7845 <listitem><para><emphasis>Build the master image:</emphasis>
7846 Build the <filename>core-image-testmaster</filename>
7847 image.
7848 The <filename>core-image-testmaster</filename>
7849 recipe is provided as an example for a
7850 "master" image and you can customize the image
7851 recipe as you would any other recipe.
7852 </para>
7853 <para>Here are the image recipe requirements:
7854 <itemizedlist>
7855 <listitem><para>Inherits
7856 <filename>core-image</filename>
7857 so that kernel modules are installed.
7858 </para></listitem>
7859 <listitem><para>Installs normal linux utilities
7860 not busybox ones (e.g.
7861 <filename>bash</filename>,
7862 <filename>coreutils</filename>,
7863 <filename>tar</filename>,
7864 <filename>gzip</filename>, and
7865 <filename>kmod</filename>).
7866 </para></listitem>
7867 <listitem><para>Uses a custom
7868 Initial RAM Disk (initramfs) image with a
7869 custom installer.
7870 A normal image that you can install usually
7871 creates a single rootfs partition.
7872 This image uses another installer that
7873 creates a specific partition layout.
7874 Not all Board Support Packages (BSPs)
7875 can use an installer.
7876 For such cases, you need to manually create
7877 the following partition layout on the
7878 target:
7879 <itemizedlist>
7880 <listitem><para>First partition mounted
7881 under <filename>/boot</filename>,
7882 labeled "boot".
7883 </para></listitem>
7884 <listitem><para>The main rootfs
7885 partition where this image gets
7886 installed, which is mounted under
7887 <filename>/</filename>.
7888 </para></listitem>
7889 <listitem><para>Another partition
7890 labeled "testrootfs" where test
7891 images get deployed.
7892 </para></listitem>
7893 </itemizedlist>
7894 </para></listitem>
7895 </itemizedlist>
7896 </para></listitem>
7897 <listitem><para><emphasis>Install image:</emphasis>
7898 Install the image that you just built on the target
7899 system.
7900 </para></listitem>
7901 </orderedlist>
7902 </para>
7903
7904 <para>
7905 The final thing you need to do when setting
7906 <filename>TEST_TARGET</filename> to "GummibootTarget" is
7907 to set up the test image:
7908 <orderedlist>
7909 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
7910 Make sure you have the following statements in
7911 your <filename>local.conf</filename> file:
7912 <literallayout class='monospaced'>
7913 IMAGE_FSTYPES += "tar.gz"
7914 INHERIT += "testimage"
7915 TEST_TARGET = "GummibootTarget"
7916 TEST_TARGET_IP = "192.168.2.3"
7917 </literallayout>
7918 </para></listitem>
7919 <listitem><para><emphasis>Build your test image:</emphasis>
7920 Use BitBake to build the image:
7921 <literallayout class='monospaced'>
7922 $ bitbake core-image-sato
7923 </literallayout>
7924 </para></listitem>
7925 </orderedlist>
7926 </para>
7927 </section>
7928
7929 <section id='power-control'>
7930 <title>Power Control</title>
7931
7932 <para>
7933 For most hardware targets other than SimpleRemoteTarget,
7934 you can control power:
7935 <itemizedlist>
7936 <listitem><para>
7937 You can use
7938 <filename>TEST_POWERCONTROL_CMD</filename>
7939 together with
7940 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
7941 as a command that runs on the host and does power
7942 cycling.
7943 The test code passes one argument to that command:
7944 off, on or cycle (off then on).
7945 Here is an example that could appear in your
7946 <filename>local.conf</filename> file:
7947 <literallayout class='monospaced'>
7948 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
7949 </literallayout>
7950 In this example, the expect script does the
7951 following:
7952 <literallayout class='monospaced'>
7953 ssh test@10.11.12.1 "pyctl nuc1 <replaceable>arg</replaceable>"
7954 </literallayout>
7955 It then runs a Python script that controls power
7956 for a label called <filename>nuc1</filename>.
7957 <note>
7958 You need to customize
7959 <filename>TEST_POWERCONTROL_CMD</filename>
7960 and
7961 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
7962 for your own setup.
7963 The one requirement is that it accepts
7964 "on", "off", and "cycle" as the last argument.
7965 </note>
7966 </para></listitem>
7967 <listitem><para>
7968 When no command is defined, it connects to the
7969 device over SSH and uses the classic reboot command
7970 to reboot the device.
7971 Classic reboot is fine as long as the machine
7972 actually reboots (i.e. the SSH test has not
7973 failed).
7974 It is useful for scenarios where you have a simple
7975 setup, typically with a single board, and where
7976 some manual interaction is okay from time to time.
7977 </para></listitem>
7978 </itemizedlist>
7979 If you have no hardware to automatically perform power
7980 control but still wish to experiment with automated
7981 hardware testing, you can use the dialog-power-control
7982 script that shows a dialog prompting you to perform the
7983 required power action.
7984 This script requires either KDialog or Zenity to be
7985 installed.
7986 To use this script, set the
7987 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
7988 variable as follows:
7989 <literallayout class='monospaced'>
7990 TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control"
7991 </literallayout>
7992 </para>
7993 </section>
7994
7995 <section id='serial-console-connection'>
7996 <title>Serial Console Connection</title>
7997
7998 <para>
7999 For test target classes requiring a serial console
8000 to interact with the bootloader (e.g. BeagleBoneTarget,
8001 EdgeRouterTarget, and GrubTarget), you need to
8002 specify a command to use to connect to the serial console
8003 of the target machine by using the
8004 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
8005 variable and optionally the
8006 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink>
8007 variable.
8008 </para>
8009
8010 <para>
8011 These cases could be a serial terminal program if the
8012 machine is connected to a local serial port, or a
8013 <filename>telnet</filename> or
8014 <filename>ssh</filename> command connecting to a remote
8015 console server.
8016 Regardless of the case, the command simply needs to
8017 connect to the serial console and forward that connection
8018 to standard input and output as any normal terminal
8019 program does.
8020 For example, to use the picocom terminal program on
8021 serial device <filename>/dev/ttyUSB0</filename>
8022 at 115200bps, you would set the variable as follows:
8023 <literallayout class='monospaced'>
8024 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
8025 </literallayout>
8026 For local devices where the serial port device disappears
8027 when the device reboots, an additional "serdevtry" wrapper
8028 script is provided.
8029 To use this wrapper, simply prefix the terminal command
8030 with
8031 <filename>${COREBASE}/scripts/contrib/serdevtry</filename>:
8032 <literallayout class='monospaced'>
8033 TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b
8034115200 /dev/ttyUSB0"
8035 </literallayout>
8036 </para>
8037 </section>
8038 </section>
8039
8040 <section id="qemu-image-running-tests">
8041 <title>Running Tests</title>
8042
8043 <para>
8044 You can start the tests automatically or manually:
8045 <itemizedlist>
8046 <listitem><para><emphasis>Automatically running tests:</emphasis>
8047 To run the tests automatically after the
8048 OpenEmbedded build system successfully creates an image,
8049 first set the
8050 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
8051 variable to "1" in your <filename>local.conf</filename>
8052 file in the
8053 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
8054 <literallayout class='monospaced'>
8055 TEST_IMAGE = "1"
8056 </literallayout>
8057 Next, build your image.
8058 If the image successfully builds, the tests will be
8059 run:
8060 <literallayout class='monospaced'>
8061 bitbake core-image-sato
8062 </literallayout></para></listitem>
8063 <listitem><para><emphasis>Manually running tests:</emphasis>
8064 To manually run the tests, first globally inherit the
8065 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
8066 class by editing your <filename>local.conf</filename>
8067 file:
8068 <literallayout class='monospaced'>
8069 INHERIT += "testimage"
8070 </literallayout>
8071 Next, use BitBake to run the tests:
8072 <literallayout class='monospaced'>
8073 bitbake -c testimage <replaceable>image</replaceable>
8074 </literallayout></para></listitem>
8075 </itemizedlist>
8076 </para>
8077
8078 <para>
8079 All test files reside in
8080 <filename>meta/lib/oeqa/runtime</filename> in the
8081 <link linkend='source-directory'>Source Directory</link>.
8082 A test name maps directly to a Python module.
8083 Each test module may contain a number of individual tests.
8084 Tests are usually grouped together by the area
8085 tested (e.g tests for systemd reside in
8086 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
8087 </para>
8088
8089 <para>
8090 You can add tests to any layer provided you place them in the
8091 proper area and you extend
8092 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
8093 in the <filename>local.conf</filename> file as normal.
8094 Be sure that tests reside in
8095 <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>.
8096 <note>
8097 Be sure that module names do not collide with module names
8098 used in the default set of test modules in
8099 <filename>meta/lib/oeqa/runtime</filename>.
8100 </note>
8101 </para>
8102
8103 <para>
8104 You can change the set of tests run by appending or overriding
8105 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
8106 variable in <filename>local.conf</filename>.
8107 Each name in <filename>TEST_SUITES</filename> represents a
8108 required test for the image.
8109 Test modules named within <filename>TEST_SUITES</filename>
8110 cannot be skipped even if a test is not suitable for an image
8111 (e.g. running the RPM tests on an image without
8112 <filename>rpm</filename>).
8113 Appending "auto" to <filename>TEST_SUITES</filename> causes the
8114 build system to try to run all tests that are suitable for the
8115 image (i.e. each test module may elect to skip itself).
8116 </para>
8117
8118 <para>
8119 The order you list tests in <filename>TEST_SUITES</filename>
8120 is important and influences test dependencies.
8121 Consequently, tests that depend on other tests should be added
8122 after the test on which they depend.
8123 For example, since the <filename>ssh</filename> test
8124 depends on the
8125 <filename>ping</filename> test, "ssh" needs to come after
8126 "ping" in the list.
8127 The test class provides no re-ordering or dependency handling.
8128 <note>
8129 Each module can have multiple classes with multiple test
8130 methods.
8131 And, Python <filename>unittest</filename> rules apply.
8132 </note>
8133 </para>
8134
8135 <para>
8136 Here are some things to keep in mind when running tests:
8137 <itemizedlist>
8138 <listitem><para>The default tests for the image are defined
8139 as:
8140 <literallayout class='monospaced'>
8141 DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
8142 </literallayout></para></listitem>
8143 <listitem><para>Add your own test to the list of the
8144 by using the following:
8145 <literallayout class='monospaced'>
8146 TEST_SUITES_append = " mytest"
8147 </literallayout></para></listitem>
8148 <listitem><para>Run a specific list of tests as follows:
8149 <literallayout class='monospaced'>
8150 TEST_SUITES = "test1 test2 test3"
8151 </literallayout>
8152 Remember, order is important.
8153 Be sure to place a test that is dependent on another test
8154 later in the order.</para></listitem>
8155 </itemizedlist>
8156 </para>
8157 </section>
8158
8159 <section id="exporting-tests">
8160 <title>Exporting Tests</title>
8161
8162 <para>
8163 You can export tests so that they can run independently of
8164 the build system.
8165 Exporting tests is required if you want to be able to hand
8166 the test execution off to a scheduler.
8167 You can only export tests that are defined in
8168 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
8169 </para>
8170
8171 <para>
8172 If your image is already built, make sure the following are set
8173 in your <filename>local.conf</filename> file.
8174 Be sure to provide the IP address you need:
8175 <literallayout class='monospaced'>
8176 TEST_EXPORT_ONLY = "1"
8177 TEST_TARGET = "simpleremote"
8178 TEST_TARGET_IP = "192.168.7.2"
8179 TEST_SERVER_IP = "192.168.7.1"
8180 </literallayout>
8181 You can then export the tests with the following:
8182 <literallayout class='monospaced'>
8183 $ bitbake core-image-sato -c testimage
8184 </literallayout>
8185 Exporting the tests places them in the
8186 <link linkend='build-directory'>Build Directory</link> in
8187 <filename>tmp/testimage/core-image-sato</filename>, which
8188 is controlled by the
8189 <filename>TEST_EXPORT_DIR</filename> variable.
8190 </para>
8191
8192 <para>
8193 You can now run the tests outside of the build environment:
8194 <literallayout class='monospaced'>
8195 $ cd tmp/testimage/core-image-sato
8196 $ ./runexported.py testdata.json
8197 </literallayout>
8198 <note>
8199 This "export" feature does not deploy or boot the target
8200 image.
8201 Your target (be it a Qemu or hardware one)
8202 has to already be up and running when you call
8203 <filename>runexported.py</filename>
8204 </note>
8205 </para>
8206
8207 <para>
8208 The exported data (i.e. <filename>testdata.json</filename>)
8209 contains paths to the Build Directory.
8210 Thus, the contents of the directory can be moved
8211 to another machine as long as you update some paths in the
8212 JSON.
8213 Usually, you only care about the
8214 <filename>${DEPLOY_DIR}/rpm</filename> directory
8215 (assuming the RPM and Smart tests are enabled).
8216 Consequently, running the tests on other machine
8217 means that you have to move the contents and call
8218 <filename>runexported.py</filename> with
8219 "&dash;&dash;deploy-dir <replaceable>path</replaceable>" as
8220 follows:
8221 <literallayout class='monospaced'>
8222 ./runexported.py &dash;&dash;deploy-dir /new/path/on/this/machine testdata.json
8223 </literallayout>
8224 <filename>runexported.py</filename> accepts other arguments
8225 as well as described using <filename>&dash;&dash;help</filename>.
8226 </para>
8227 </section>
8228
8229 <section id="qemu-image-writing-new-tests">
8230 <title>Writing New Tests</title>
8231
8232 <para>
8233 As mentioned previously, all new test files need to be in the
8234 proper place for the build system to find them.
8235 New tests for additional functionality outside of the core
8236 should be added to the layer that adds the functionality, in
8237 <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>
8238 (as long as
8239 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
8240 is extended in the layer's
8241 <filename>layer.conf</filename> file as normal).
8242 Just remember that filenames need to map directly to test
8243 (module) names and that you do not use module names that
8244 collide with existing core tests.
8245 </para>
8246
8247 <para>
8248 To create a new test, start by copying an existing module
8249 (e.g. <filename>syslog.py</filename> or
8250 <filename>gcc.py</filename> are good ones to use).
8251 Test modules can use code from
8252 <filename>meta/lib/oeqa/utils</filename>, which are helper
8253 classes.
8254 </para>
8255
8256 <note>
8257 Structure shell commands such that you rely on them and they
8258 return a single code for success.
8259 Be aware that sometimes you will need to parse the output.
8260 See the <filename>df.py</filename> and
8261 <filename>date.py</filename> modules for examples.
8262 </note>
8263
8264 <para>
8265 You will notice that all test classes inherit
8266 <filename>oeRuntimeTest</filename>, which is found in
8267 <filename>meta/lib/oetest.py</filename>.
8268 This base class offers some helper attributes, which are
8269 described in the following sections:
8270 </para>
8271
8272 <section id='qemu-image-writing-tests-class-methods'>
8273 <title>Class Methods</title>
8274
8275 <para>
8276 Class methods are as follows:
8277 <itemizedlist>
8278 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
8279 Returns "True" if <filename>pkg</filename> is in the
8280 installed package list of the image, which is based
8281 on the manifest file that is generated during the
8282 <filename>do_rootfs</filename> task.
8283 </para></listitem>
8284 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
8285 Returns "True" if the feature is in
8286 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
8287 or
8288 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
8289 </para></listitem>
8290 </itemizedlist>
8291 </para>
8292 </section>
8293
8294 <section id='qemu-image-writing-tests-class-attributes'>
8295 <title>Class Attributes</title>
8296
8297 <para>
8298 Class attributes are as follows:
8299 <itemizedlist>
8300 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
8301 Equals "ps -ef" if <filename>procps</filename> is
8302 installed in the image.
8303 Otherwise, <filename>pscmd</filename> equals
8304 "ps" (busybox).
8305 </para></listitem>
8306 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
8307 The called text context, which gives access to the
8308 following attributes:
8309 <itemizedlist>
8310 <listitem><para><emphasis><filename>d</filename>:</emphasis>
8311 The BitBake datastore, which allows you to
8312 use stuff such as
8313 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
8314 </para></listitem>
8315 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
8316 Used internally.
8317 The tests do not need these.
8318 </para></listitem>
8319 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
8320 The absolute path to
8321 <filename>meta/lib/oeqa/runtime/files</filename>,
8322 which contains helper files for tests meant
8323 for copying on the target such as small
8324 files written in C for compilation.
8325 </para></listitem>
8326 <listitem><para><emphasis><filename>target</filename>:</emphasis>
8327 The target controller object used to deploy
8328 and start an image on a particular target
8329 (e.g. QemuTarget, SimpleRemote, and
8330 GummibootTarget).
8331 Tests usually use the following:
8332 <itemizedlist>
8333 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
8334 The target's IP address.
8335 </para></listitem>
8336 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
8337 The host's IP address, which is
8338 usually used by the "smart" test
8339 suite.
8340 </para></listitem>
8341 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
8342 The single, most used method.
8343 This command is a wrapper for:
8344 <filename>ssh root@host "cmd"</filename>.
8345 The command returns a tuple:
8346 (status, output), which are what
8347 their names imply - the return code
8348 of "cmd" and whatever output
8349 it produces.
8350 The optional timeout argument
8351 represents the number of seconds the
8352 test should wait for "cmd" to
8353 return.
8354 If the argument is "None", the
8355 test uses the default instance's
8356 timeout period, which is 300
8357 seconds.
8358 If the argument is "0", the test
8359 runs until the command returns.
8360 </para></listitem>
8361 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
8362 <filename>scp localpath root@ip:remotepath</filename>.
8363 </para></listitem>
8364 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
8365 <filename>scp root@host:remotepath localpath</filename>.
8366 </para></listitem>
8367 </itemizedlist></para></listitem>
8368 </itemizedlist></para></listitem>
8369 </itemizedlist>
8370 </para>
8371 </section>
8372
8373 <section id='qemu-image-writing-tests-instance-attributes'>
8374 <title>Instance Attributes</title>
8375
8376 <para>
8377 A single instance attribute exists, which is
8378 <filename>target</filename>.
8379 The <filename>target</filename> instance attribute is
8380 identical to the class attribute of the same name, which
8381 is described in the previous section.
8382 This attribute exists as both an instance and class
8383 attribute so tests can use
8384 <filename>self.target.run(cmd)</filename> in instance
8385 methods instead of
8386 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
8387 </para>
8388 </section>
8389 </section>
8390 </section>
8391
8392 <section id="platdev-gdb-remotedebug">
8393 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
8394
8395 <para>
8396 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
8397 It also allows you to perform post-mortem style analysis of program crashes.
8398 GDB is available as a package within the Yocto Project and is
8399 installed in SDK images by default.
8400 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
8401 in the Yocto Project Reference Manual for a description of these images.
8402 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
8403 </para>
8404
8405 <tip>
8406 For best results, install debug (<filename>-dbg</filename>) packages
8407 for the applications you are going to debug.
8408 Doing so makes extra debug symbols available that give you more
8409 meaningful output.
8410 </tip>
8411
8412 <para>
8413 Sometimes, due to memory or disk space constraints, it is not possible
8414 to use GDB directly on the remote target to debug applications.
8415 These constraints arise because GDB needs to load the debugging information and the
8416 binaries of the process being debugged.
8417 Additionally, GDB needs to perform many computations to locate information such as function
8418 names, variable names and values, stack traces and so forth - even before starting the
8419 debugging process.
8420 These extra computations place more load on the target system and can alter the
8421 characteristics of the program being debugged.
8422 </para>
8423
8424 <para>
8425 To help get past the previously mentioned constraints, you can use Gdbserver.
8426 Gdbserver runs on the remote target and does not load any debugging information
8427 from the debugged process.
8428 Instead, a GDB instance processes the debugging information that is run on a
8429 remote computer - the host GDB.
8430 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
8431 program, as well as read or write memory regions of that debugged program.
8432 All the debugging information loaded and processed as well
8433 as all the heavy debugging is done by the host GDB.
8434 Offloading these processes gives the Gdbserver running on the target a chance to remain
8435 small and fast.
8436 <note>
8437 By default, source files are part of the
8438 <filename>*-dbg</filename> packages in order to enable GDB
8439 to show source lines in its output.
8440 You can save further space on the target by setting the
8441 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink>
8442 variable to "debug-without-src" so that these packages do not
8443 include the source files.
8444 </note>
8445 </para>
8446
8447 <para>
8448 Because the host GDB is responsible for loading the debugging information and
8449 for doing the necessary processing to make actual debugging happen,
8450 you have to make sure the host can access the unstripped binaries complete
8451 with their debugging information and also be sure the target is compiled with no optimizations.
8452 The host GDB must also have local access to all the libraries used by the
8453 debugged program.
8454 Because Gdbserver does not need any local debugging information, the binaries on
8455 the remote target can remain stripped.
8456 However, the binaries must also be compiled without optimization
8457 so they match the host's binaries.
8458 </para>
8459
8460 <para>
8461 To remain consistent with GDB documentation and terminology, the binary being debugged
8462 on the remote target machine is referred to as the "inferior" binary.
8463 For documentation on GDB see the
8464 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
8465 </para>
8466
8467 <para>
8468 The remainder of this section describes the steps you need to take
8469 to debug using the GNU project debugger.
8470 </para>
8471
8472 <section id='platdev-gdb-remotedebug-setup'>
8473 <title>Set Up the Cross-Development Debugging Environment</title>
8474
8475 <para>
8476 Before you can initiate a remote debugging session, you need
8477 to be sure you have set up the cross-development environment,
8478 toolchain, and sysroot.
8479 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
8480 chapter of the Yocto Project Application Developer's Guide
8481 describes this process.
8482 Be sure you have read that chapter and have set up
8483 your environment.
8484 </para>
8485 </section>
8486
8487 <section id="platdev-gdb-remotedebug-launch-gdbserver">
8488 <title>Launch Gdbserver on the Target</title>
8489
8490 <para>
8491 Make sure Gdbserver is installed on the target.
8492 If it is not, install the package
8493 <filename>gdbserver</filename>, which needs the
8494 <filename>libthread-db1</filename> package.
8495 </para>
8496
8497 <para>
8498 Here is an example, that when entered from the host,
8499 connects to the target and launches Gdbserver in order to
8500 "debug" a binary named <filename>helloworld</filename>:
8501 <literallayout class='monospaced'>
8502 $ gdbserver localhost:2345 /usr/bin/helloworld
8503 </literallayout>
8504 Gdbserver should now be listening on port 2345 for debugging
8505 commands coming from a remote GDB process that is running on
8506 the host computer.
8507 Communication between Gdbserver and the host GDB are done
8508 using TCP.
8509 To use other communication protocols, please refer to the
8510 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
8511 </para>
8512 </section>
8513
8514 <section id="platdev-gdb-remotedebug-launch-gdb">
8515 <title>Launch GDB on the Host Computer</title>
8516
8517 <para>
8518 Running GDB on the host computer takes a number of stages, which
8519 this section describes.
8520 </para>
8521
8522 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
8523 <title>Build the Cross-GDB Package</title>
8524 <para>
8525 A suitable GDB cross-binary is required that runs on your
8526 host computer but also knows about the the ABI of the
8527 remote target.
8528 You can get this binary from the
8529 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
8530 Here is an example where the toolchain has been installed
8531 in the default directory
8532 <filename>/opt/poky/&DISTRO;</filename>:
8533 <literallayout class='monospaced'>
8534 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
8535 </literallayout>
8536 where <filename>arm</filename> is the target architecture
8537 and <filename>linux-gnueabi</filename> is the target ABI.
8538 </para>
8539
8540 <para>
8541 Alternatively, you can use BitBake to build the
8542 <filename>gdb-cross</filename> binary.
8543 Here is an example:
8544 <literallayout class='monospaced'>
8545 $ bitbake gdb-cross
8546 </literallayout>
8547 Once the binary is built, you can find it here:
8548 <literallayout class='monospaced'>
8549 tmp/sysroots/<replaceable>host-arch</replaceable>/usr/bin/<replaceable>target-platform</replaceable>/<replaceable>target-abi</replaceable>-gdb
8550 </literallayout>
8551 </para>
8552 </section>
8553
8554 <section id='create-the-gdb-initialization-file'>
8555 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
8556
8557 <para>
8558 Aside from the GDB cross-binary, you also need a GDB
8559 initialization file in the same top directory in which
8560 your binary resides.
8561 When you start GDB on your host development system, GDB
8562 finds this initialization file and executes all the
8563 commands within.
8564 For information on the <filename>.gdbinit</filename>, see
8565 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
8566 which is maintained by
8567 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
8568 </para>
8569
8570 <para>
8571 You need to add a statement in the
8572 <filename>~/.gdbinit</filename> file that points to your
8573 root filesystem.
8574 Here is an example that points to the root filesystem for
8575 an ARM-based target device:
8576 <literallayout class='monospaced'>
8577 set sysroot ~/sysroot_arm
8578 </literallayout>
8579 </para>
8580 </section>
8581
8582 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
8583 <title>Launch the Host GDB</title>
8584
8585 <para>
8586 Before launching the host GDB, you need to be sure
8587 you have sourced the cross-debugging environment script,
8588 which if you installed the root filesystem in the default
8589 location is at <filename>/opt/poky/&DISTRO;</filename>
8590 and begins with the string "environment-setup".
8591 For more information, see the
8592 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
8593 section in the Yocto Project Application Developer's
8594 Guide.
8595 </para>
8596
8597 <para>
8598 Finally, switch to the directory where the binary resides
8599 and run the <filename>cross-gdb</filename> binary.
8600 Provide the binary file you are going to debug.
8601 For example, the following command continues with the
8602 example used in the previous section by loading
8603 the <filename>helloworld</filename> binary as well as the
8604 debugging information:
8605 <literallayout class='monospaced'>
8606 $ arm-poky-linux-gnuabi-gdb helloworld
8607 </literallayout>
8608 The commands in your <filename>.gdbinit</filename> execute
8609 and the GDB prompt appears.
8610 </para>
8611 </section>
8612 </section>
8613
8614 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
8615 <title>Connect to the Remote GDB Server</title>
8616
8617 <para>
8618 From the target, you need to connect to the remote GDB
8619 server that is running on the host.
8620 You need to specify the remote host and port.
8621 Here is the command continuing with the example:
8622 <literallayout class='monospaced'>
8623 target remote 192.168.7.2:2345
8624 </literallayout>
8625 </para>
8626 </section>
8627
8628 <section id="platdev-gdb-remotedebug-launch-gdb-using">
8629 <title>Use the Debugger</title>
8630
8631 <para>
8632 You can now proceed with debugging as normal - as if you were debugging
8633 on the local machine.
8634 For example, to instruct GDB to break in the "main" function and then
8635 continue with execution of the inferior binary use the following commands
8636 from within GDB:
8637 <literallayout class='monospaced'>
8638 (gdb) break main
8639 (gdb) continue
8640 </literallayout>
8641 </para>
8642
8643 <para>
8644 For more information about using GDB, see the project's online documentation at
8645 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
8646 </para>
8647 </section>
8648 </section>
8649
8650 <section id='debugging-parallel-make-races'>
8651 <title>Debugging Parallel Make Races</title>
8652
8653 <para>
8654 A parallel <filename>make</filename> race occurs when the build
8655 consists of several parts that are run simultaneously and
8656 a situation occurs when the output or result of one
8657 part is not ready for use with a different part of the build that
8658 depends on that output.
8659 Parallel make races are annoying and can sometimes be difficult
8660 to reproduce and fix.
8661 However, some simple tips and tricks exist that can help
8662 you debug and fix them.
8663 This section presents a real-world example of an error encountered
8664 on the Yocto Project autobuilder and the process used to fix it.
8665 </para>
8666
8667 <section id='the-failure'>
8668 <title>The Failure</title>
8669
8670 <para>
8671 For this example, assume that you are building an image that
8672 depends on the "neard" package.
8673 And, during the build, BitBake runs into problems and
8674 creates the following output.
8675 <note>
8676 This example log file has longer lines artificially
8677 broken to make the listing easier to read.
8678 </note>
8679 If you examine the output or the log file, you see the
8680 failure during <filename>make</filename>:
8681 <literallayout class='monospaced'>
8682 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
8683 | DEBUG: Executing shell function do_compile
8684 | NOTE: make -j 16
8685 | make &dash;&dash;no-print-directory all-am
8686 | /bin/mkdir -p include/near
8687 | /bin/mkdir -p include/near
8688 | /bin/mkdir -p include/near
8689 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8690 0.14-r0/neard-0.14/include/types.h include/near/types.h
8691 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8692 0.14-r0/neard-0.14/include/log.h include/near/log.h
8693 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8694 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h
8695 | /bin/mkdir -p include/near
8696 | /bin/mkdir -p include/near
8697 | /bin/mkdir -p include/near
8698 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8699 0.14-r0/neard-0.14/include/tag.h include/near/tag.h
8700 | /bin/mkdir -p include/near
8701 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8702 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h
8703 | /bin/mkdir -p include/near
8704 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8705 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h
8706 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8707 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h
8708 | /bin/mkdir -p include/near
8709 | /bin/mkdir -p include/near
8710 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8711 0.14-r0/neard-0.14/include/setting.h include/near/setting.h
8712 | /bin/mkdir -p include/near
8713 | /bin/mkdir -p include/near
8714 | /bin/mkdir -p include/near
8715 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8716 0.14-r0/neard-0.14/include/device.h include/near/device.h
8717 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8718 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h
8719 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8720 0.14-r0/neard-0.14/include/snep.h include/near/snep.h
8721 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8722 0.14-r0/neard-0.14/include/version.h include/near/version.h
8723 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8724 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h
8725 | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h
8726 | i586-poky-linux-gcc -m32 -march=i586 &dash;&dash;sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/
8727 build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/
8728 yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0
8729 -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/
8730 lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/
8731 tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/
8732 nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/
8733 yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3
8734 -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\"
8735 -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c
8736 -o tools/snep-send.o tools/snep-send.c
8737 | In file included from tools/snep-send.c:16:0:
8738 | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
8739 | #include &lt;near/dbus.h&gt;
8740 | ^
8741 | compilation terminated.
8742 | make[1]: *** [tools/snep-send.o] Error 1
8743 | make[1]: *** Waiting for unfinished jobs....
8744 | make: *** [all] Error 2
8745 | ERROR: oe_runmake failed
8746 </literallayout>
8747 </para>
8748 </section>
8749
8750 <section id='reproducing-the-error'>
8751 <title>Reproducing the Error</title>
8752
8753 <para>
8754 Because race conditions are intermittent, they do not
8755 manifest themselves every time you do the build.
8756 In fact, most times the build will complete without problems
8757 even though the potential race condition exists.
8758 Thus, once the error surfaces, you need a way to reproduce it.
8759 </para>
8760
8761 <para>
8762 In this example, compiling the "neard" package is causing the
8763 problem.
8764 So the first thing to do is build "neard" locally.
8765 Before you start the build, set the
8766 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
8767 variable in your <filename>local.conf</filename> file to
8768 a high number (e.g. "-j 20").
8769 Using a high value for <filename>PARALLEL_MAKE</filename>
8770 increases the chances of the race condition showing up:
8771 <literallayout class='monospaced'>
8772 $ bitbake neard
8773 </literallayout>
8774 </para>
8775
8776 <para>
8777 Once the local build for "neard" completes, start a
8778 <filename>devshell</filename> build:
8779 <literallayout class='monospaced'>
8780 $ bitbake neard -c devshell
8781 </literallayout>
8782 For information on how to use a
8783 <filename>devshell</filename>, see the
8784 "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
8785 section.
8786 </para>
8787
8788 <para>
8789 In the <filename>devshell</filename>, do the following:
8790 <literallayout class='monospaced'>
8791 $ make clean
8792 $ make tools/snep-send.o
8793 </literallayout>
8794 The <filename>devshell</filename> commands cause the failure
8795 to clearly be visible.
8796 In this case, a missing dependency exists for the "neard"
8797 Makefile target.
8798 Here is some abbreviated, sample output with the
8799 missing dependency clearly visible at the end:
8800 <literallayout class='monospaced'>
8801 i586-poky-linux-gcc -m32 -march=i586 &dash;&dash;sysroot=/home/scott-lenovo/......
8802 .
8803 .
8804 .
8805 tools/snep-send.c
8806 In file included from tools/snep-send.c:16:0:
8807 tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
8808 #include &lt;near/dbus.h&gt;
8809 ^
8810 compilation terminated.
8811 make: *** [tools/snep-send.o] Error 1
8812 $
8813 </literallayout>
8814 </para>
8815 </section>
8816
8817 <section id='creating-a-patch-for-the-fix'>
8818 <title>Creating a Patch for the Fix</title>
8819
8820 <para>
8821 Because there is a missing dependency for the Makefile
8822 target, you need to patch the
8823 <filename>Makefile.am</filename> file, which is generated
8824 from <filename>Makefile.in</filename>.
8825 You can use Quilt to create the patch:
8826 <literallayout class='monospaced'>
8827 $ quilt new parallelmake.patch
8828 Patch patches/parallelmake.patch is now on top
8829 $ quilt add Makefile.am
8830 File Makefile.am added to patch patches/parallelmake.patch
8831 </literallayout>
8832 For more information on using Quilt, see the
8833 "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>"
8834 section.
8835 </para>
8836
8837 <para>
8838 At this point you need to make the edits to
8839 <filename>Makefile.am</filename> to add the missing
8840 dependency.
8841 For our example, you have to add the following line
8842 to the file:
8843 <literallayout class='monospaced'>
8844 tools/snep-send.$(OBJEXT): include/near/dbus.h
8845 </literallayout>
8846 </para>
8847
8848 <para>
8849 Once you have edited the file, use the
8850 <filename>refresh</filename> command to create the patch:
8851 <literallayout class='monospaced'>
8852 $ quilt refresh
8853 Refreshed patch patches/parallelmake.patch
8854 </literallayout>
8855 Once the patch file exists, you need to add it back to the
8856 originating recipe folder.
8857 Here is an example assuming a top-level
8858 <link linkend='source-directory'>Source Directory</link>
8859 named <filename>poky</filename>:
8860 <literallayout class='monospaced'>
8861 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
8862 </literallayout>
8863 The final thing you need to do to implement the fix in the
8864 build is to update the "neard" recipe (i.e.
8865 <filename>neard-0.14.bb</filename>) so that the
8866 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
8867 statement includes the patch file.
8868 The recipe file is in the folder above the patch.
8869 Here is what the edited <filename>SRC_URI</filename>
8870 statement would look like:
8871 <literallayout class='monospaced'>
8872 SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
8873 file://neard.in \
8874 file://neard.service.in \
8875 file://parallelmake.patch \
8876 "
8877 </literallayout>
8878 </para>
8879
8880 <para>
8881 With the patch complete and moved to the correct folder and
8882 the <filename>SRC_URI</filename> statement updated, you can
8883 exit the <filename>devshell</filename>:
8884 <literallayout class='monospaced'>
8885 $ exit
8886 </literallayout>
8887 </para>
8888 </section>
8889
8890 <section id='testing-the-build'>
8891 <title>Testing the Build</title>
8892
8893 <para>
8894 With everything in place, you can get back to trying the
8895 build again locally:
8896 <literallayout class='monospaced'>
8897 $ bitbake neard
8898 </literallayout>
8899 This build should succeed.
8900 </para>
8901
8902 <para>
8903 Now you can open up a <filename>devshell</filename> again
8904 and repeat the clean and make operations as follows:
8905 <literallayout class='monospaced'>
8906 $ bitbake neard -c devshell
8907 $ make clean
8908 $ make tools/snep-send.o
8909 </literallayout>
8910 The build should work without issue.
8911 </para>
8912
8913 <para>
8914 As with all solved problems, if they originated upstream, you
8915 need to submit the fix for the recipe in OE-Core and upstream
8916 so that the problem is taken care of at its source.
8917 See the
8918 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
8919 section for more information.
8920 </para>
8921 </section>
8922 </section>
8923
8924 <section id="examining-builds-using-toaster">
8925 <title>Examining Builds Using the Toaster API</title>
8926
8927 <para>
8928 Toaster is an Application Programming Interface (API) and
8929 web-based interface to the OpenEmbedded build system, which uses
8930 BitBake.
8931 Both interfaces are based on a Representational State Transfer
8932 (REST) API that queries for and returns build information using
8933 <filename>GET</filename> and <filename>JSON</filename>.
8934 These types of search operations retrieve sets of objects from
8935 a datastore used to collect build information.
8936 The results contain all the data for the objects being returned.
8937 You can order the results of the search by key and the search
8938 parameters are consistent for all object types.
8939 </para>
8940
8941 <para>
8942 Using the interfaces you can do the following:
8943 <itemizedlist>
8944 <listitem><para>See information about the tasks executed
8945 and reused during the build.</para></listitem>
8946 <listitem><para>See what is built (recipes and
8947 packages) and what packages were installed into the final
8948 image.</para></listitem>
8949 <listitem><para>See performance-related information such
8950 as build time, CPU usage, and disk I/O.</para></listitem>
8951 <listitem><para>Examine error, warning and trace messages
8952 to aid in debugging.</para></listitem>
8953 </itemizedlist>
8954 </para>
8955
8956 <note>
8957 <para>This release of Toaster provides you with information
8958 about a BitBake run.
8959 The tool does not allow you to configure and launch a build.
8960 However, future development includes plans to integrate the
8961 configuration and build launching capabilities of
8962 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
8963 </para>
8964 <para>For more information on using Hob to build an image,
8965 see the
8966 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
8967 section.</para>
8968 </note>
8969
8970 <para>
8971 The remainder of this section describes what you need to have in
8972 place to use Toaster, how to start it, use it, and stop it.
8973 For additional information on installing and running Toaster, see the
8974 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
8975 section of the "Toaster" wiki page.
8976 For complete information on the API and its search operation
8977 URI, parameters, and responses, see the
8978 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
8979 Wiki page.
8980 </para>
8981
8982 <section id='starting-toaster'>
8983 <title>Starting Toaster</title>
8984
8985 <para>
8986 Getting set up to use and start Toaster is simple.
8987 First, be sure you have met the following requirements:
8988 <itemizedlist>
8989 <listitem><para>You have set up your
8990 <link linkend='source-directory'>Source Directory</link>
8991 by cloning the upstream <filename>poky</filename>
8992 repository.
8993 See the
8994 <link linkend='local-yp-release'>Yocto Project Release</link>
8995 item for information on how to set up the Source
8996 Directory.</para></listitem>
8997 <listitem><para>Be sure your build machine has
8998 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
8999 version 1.5 installed.</para></listitem>
9000 <listitem><para>Make sure that port 8000 and 8200 are
9001 free (i.e. they have no servers on them).
9002 </para></listitem>
9003 </itemizedlist>
9004 </para>
9005
9006 <para>
9007 Once you have met the requirements, follow these steps to
9008 start Toaster running in the background of your shell:
9009 <orderedlist>
9010 <listitem><para><emphasis>Set up your build environment:</emphasis>
9011 Source a build environment script (i.e.
9012 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
9013 or
9014 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
9015 </para></listitem>
9016 <listitem><para><emphasis>Start Toaster:</emphasis>
9017 Start the Toaster service using this
9018 command from within your
9019 <link linkend='build-directory'>Build Directory</link>:
9020 <literallayout class='monospaced'>
9021 $ source toaster start
9022 </literallayout></para></listitem>
9023 <note>
9024 The Toaster must be started and running in order
9025 for it to collect data.
9026 </note>
9027 </orderedlist>
9028 </para>
9029
9030 <para>
9031 When Toaster starts, it creates some additional files in your
9032 Build Directory.
9033 Deleting these files will cause you to lose data or interrupt
9034 Toaster:
9035 <itemizedlist>
9036 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
9037 Toaster's database file.</para></listitem>
9038 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
9039 The log file of the web server.</para></listitem>
9040 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
9041 The log file of the user interface component.
9042 </para></listitem>
9043 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
9044 The PID of the web server.</para></listitem>
9045 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
9046 The PID of the DSI data bridge.</para></listitem>
9047 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
9048 The BitBake server's log file.</para></listitem>
9049 </itemizedlist>
9050 </para>
9051 </section>
9052
9053 <section id='using-toaster'>
9054 <title>Using Toaster</title>
9055
9056 <para>
9057 Once Toaster is running, it logs information for any BitBake
9058 run from your Build Directory.
9059 This logging is automatic.
9060 All you need to do is access and use the information.
9061 </para>
9062
9063 <para>
9064 You access the information one of two ways:
9065 <itemizedlist>
9066 <listitem><para>Open a Browser and enter
9067 <filename>http://localhost:8000</filename>
9068 for the URL.
9069 </para></listitem>
9070 <listitem><para>Use the <filename>xdg-open</filename>
9071 tool from the shell and pass it the same URL.
9072 </para></listitem>
9073 </itemizedlist>
9074 Either method opens the home page for the Toaster interface.
9075 </para>
9076
9077 <note><title>Notes</title>
9078 <itemizedlist>
9079 <listitem><para>
9080 For information on how to delete information from the
9081 Toaster database, see the
9082 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
9083 wiki page.
9084 </para></listitem>
9085 <listitem><para>
9086 For information on how to set up an instance of Toaster
9087 on a remote host, see the
9088 <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>
9089 wiki page.
9090 </para></listitem>
9091 </itemizedlist>
9092 </note>
9093 </section>
9094
9095 <section id='examining-toaster-data'>
9096 <title>Examining Toaster Data</title>
9097
9098 <para>
9099 The Toaster database is persistent regardless of whether you
9100 start or stop the service.
9101 </para>
9102
9103 <para>
9104 Toaster's interface shows you a list of builds
9105 (successful and unsuccessful) for which it has data.
9106 You can click on any build to see related information.
9107 This information includes configuration details, information
9108 about tasks, all recipes and packages built and their
9109 dependencies, packages and their directory structure as
9110 installed in your final image,
9111 execution time, CPU usage and disk I/O per task.
9112 </para>
9113
9114 <para>
9115 For details on the interface, see the
9116 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
9117 </para>
9118 </section>
9119
9120 <section id='stopping-toaster'>
9121 <title>Stopping Toaster</title>
9122
9123 <para>
9124 Stop the Toaster service with the following command
9125 from with the
9126 <link linkend='build-directory'>Build Directory</link>:
9127 <literallayout class='monospaced'>
9128 $ source toaster stop
9129 </literallayout>
9130 The service stops but the Toaster database remains persistent.
9131 </para>
9132 </section>
9133 </section>
9134
9135 <section id="platdev-oprofile">
9136 <title>Profiling with OProfile</title>
9137
9138 <para>
9139 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
9140 statistical profiler well suited for finding performance
9141 bottlenecks in both user-space software and in the kernel.
9142 This profiler provides answers to questions like "Which functions does my application spend
9143 the most time in when doing X?"
9144 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
9145 applications on target hardware straight forward.
9146 <note>
9147 For more information on how to set up and run OProfile, see the
9148 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
9149 section in the Yocto Project Profiling and Tracing Manual.
9150 </note>
9151 </para>
9152
9153 <para>
9154 To use OProfile, you need an image that has OProfile installed.
9155 The easiest way to do this is with "tools-profile" in the
9156 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
9157 You also need debugging symbols to be available on the system where the analysis
9158 takes place.
9159 You can gain access to the symbols by using "dbg-pkgs" in the
9160 <filename>IMAGE_FEATURES</filename> variable or by
9161 installing the appropriate debug (<filename>-dbg</filename>)
9162 packages.
9163 </para>
9164
9165 <para>
9166 For successful call graph analysis, the binaries must preserve the frame
9167 pointer register and should also be compiled with the
9168 <filename>-fno-omit-framepointer</filename> flag.
9169 You can achieve this by setting the
9170 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
9171 variable with the following options:
9172 <literallayout class='monospaced'>
9173 -fexpensive-optimizations
9174 -fno-omit-framepointer
9175 -frename-registers
9176 -O2
9177 </literallayout>
9178 You can also achieve it by setting the
9179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
9180 variable to "1" in the <filename>local.conf</filename> configuration file.
9181 If you use the <filename>DEBUG_BUILD</filename> variable,
9182 you also add extra debugging information that can make the debug
9183 packages large.
9184 </para>
9185
9186 <section id="platdev-oprofile-target">
9187 <title>Profiling on the Target</title>
9188
9189 <para>
9190 Using OProfile, you can perform all the profiling work on the target device.
9191 A simple OProfile session might look like the following:
9192 </para>
9193
9194 <para>
9195 <literallayout class='monospaced'>
9196 # opcontrol &dash;&dash;reset
9197 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
9198 .
9199 .
9200 [do whatever is being profiled]
9201 .
9202 .
9203 # opcontrol &dash;&dash;stop
9204 $ opreport -cl
9205 </literallayout>
9206 </para>
9207
9208 <para>
9209 In this example, the <filename>reset</filename> command clears any previously profiled data.
9210 The next command starts OProfile.
9211 The options used when starting the profiler separate dynamic library data
9212 within applications, disable kernel profiling, and enable callgraphing up to
9213 five levels deep.
9214 <note>
9215 To profile the kernel, you would specify the
9216 <filename>&dash;&dash;vmlinux=/path/to/vmlinux</filename> option.
9217 The <filename>vmlinux</filename> file is usually in the source directory in the
9218 <filename>/boot/</filename> directory and must match the running kernel.
9219 </note>
9220 </para>
9221
9222 <para>
9223 After you perform your profiling tasks, the next command stops the profiler.
9224 After that, you can view results with the <filename>opreport</filename> command with options
9225 to see the separate library symbols and callgraph information.
9226 </para>
9227
9228 <para>
9229 Callgraphing logs information about time spent in functions and about a function's
9230 calling function (parent) and called functions (children).
9231 The higher the callgraphing depth, the more accurate the results.
9232 However, higher depths also increase the logging overhead.
9233 Consequently, you should take care when setting the callgraphing depth.
9234 <note>
9235 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
9236 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
9237 with <filename>gcc</filename>.
9238 </note>
9239 </para>
9240
9241 <para>
9242 For more information on using OProfile, see the OProfile
9243 online documentation at
9244 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
9245 </para>
9246 </section>
9247
9248 <section id="platdev-oprofile-oprofileui">
9249 <title>Using OProfileUI</title>
9250
9251 <para>
9252 A graphical user interface for OProfile is also available.
9253 You can download and build this interface from the Yocto Project at
9254 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
9255 If the "tools-profile" image feature is selected, all necessary binaries
9256 are installed onto the target device for OProfileUI interaction.
9257 For a list of image features that ship with the Yocto Project,
9258 see the
9259 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
9260 section in the Yocto Project Reference Manual.
9261 </para>
9262
9263 <para>
9264 Even though the source directory usually includes all needed patches on the target device, you
9265 might find you need other OProfile patches for recent OProfileUI features.
9266 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
9267 OProfileUI README</ulink> for the most recent information.
9268 </para>
9269
9270 <section id="platdev-oprofile-oprofileui-online">
9271 <title>Online Mode</title>
9272
9273 <para>
9274 Using OProfile in online mode assumes a working network connection with the target
9275 hardware.
9276 With this connection, you just need to run "oprofile-server" on the device.
9277 By default, OProfile listens on port 4224.
9278 <note>
9279 You can change the port using the <filename>&dash;&dash;port</filename> command-line
9280 option.
9281 </note>
9282 </para>
9283
9284 <para>
9285 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
9286 straight forward.
9287 You access key functionality through the buttons on the toolbar, which
9288 are duplicated in the menus.
9289 Here are the buttons:
9290 <itemizedlist>
9291 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
9292 You can also supply the IP address or hostname.</para></listitem>
9293 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
9294 </para></listitem>
9295 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
9296 </para></listitem>
9297 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
9298 downloads the data to the local host.
9299 Stopping the profiler generates the profile and displays it in the viewer.
9300 </para></listitem>
9301 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
9302 target and generates the profile, which appears in the viewer.</para></listitem>
9303 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
9304 Resetting the data removes sample information collected from previous
9305 sampling runs.
9306 Be sure you reset the data if you do not want to include old sample information.
9307 </para></listitem>
9308 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
9309 target to another directory for later examination.</para></listitem>
9310 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
9311 </para></listitem>
9312 </itemizedlist>
9313 </para>
9314
9315 <para>
9316 The client downloads the complete profile archive from
9317 the target to the host for processing.
9318 This archive is a directory that contains the sample data, the object files,
9319 and the debug information for the object files.
9320 The archive is then converted using the <filename>oparchconv</filename> script, which is
9321 included in this distribution.
9322 The script uses <filename>opimport</filename> to convert the archive from
9323 the target to something that can be processed on the host.
9324 </para>
9325
9326 <para>
9327 Downloaded archives reside in the
9328 <link linkend='build-directory'>Build Directory</link> in
9329 <filename>tmp</filename> and are cleared up when they are no longer in use.
9330 </para>
9331
9332 <para>
9333 If you wish to perform kernel profiling, you need to be sure
9334 a <filename>vmlinux</filename> file that matches the running kernel is available.
9335 In the source directory, that file is usually located in
9336 <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where
9337 <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel.
9338 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
9339 packages for each kernel it builds.
9340 Thus, it should just be a question of making sure a matching package is
9341 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
9342 The files are automatically installed into development and profiling images
9343 alongside OProfile.
9344 A configuration option exists within the OProfileUI settings page that you can use to
9345 enter the location of the <filename>vmlinux</filename> file.
9346 </para>
9347
9348 <para>
9349 Waiting for debug symbols to transfer from the device can be slow, and it
9350 is not always necessary to actually have them on the device for OProfile use.
9351 All that is needed is a copy of the filesystem with the debug symbols present
9352 on the viewer system.
9353 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
9354 section covers how to create such a directory within
9355 the source directory and how to use the OProfileUI Settings
9356 Dialog to specify the location.
9357 If you specify the directory, it will be used when the file checksums
9358 match those on the system you are profiling.
9359 </para>
9360 </section>
9361
9362 <section id="platdev-oprofile-oprofileui-offline">
9363 <title>Offline Mode</title>
9364
9365 <para>
9366 If network access to the target is unavailable, you can generate
9367 an archive for processing in <filename>oprofile-viewer</filename> as follows:
9368 <literallayout class='monospaced'>
9369 # opcontrol &dash;&dash;reset
9370 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
9371 .
9372 .
9373 [do whatever is being profiled]
9374 .
9375 .
9376 # opcontrol &dash;&dash;stop
9377 # oparchive -o my_archive
9378 </literallayout>
9379 </para>
9380
9381 <para>
9382 In the above example, <filename>my_archive</filename> is the name of the
9383 archive directory where you would like the profile archive to be kept.
9384 After the directory is created, you can copy it to another host and load it
9385 using <filename>oprofile-viewer</filename> open functionality.
9386 If necessary, the archive is converted.
9387 </para>
9388 </section>
9389 </section>
9390 </section>
9391
9392 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
9393 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
9394
9395 <para>
9396 One of the concerns for a development organization using open source
9397 software is how to maintain compliance with various open source
9398 licensing during the lifecycle of the product.
9399 While this section does not provide legal advice or
9400 comprehensively cover all scenarios, it does
9401 present methods that you can use to
9402 assist you in meeting the compliance requirements during a software
9403 release.
9404 </para>
9405
9406 <para>
9407 With hundreds of different open source licenses that the Yocto
9408 Project tracks, it is difficult to know the requirements of each
9409 and every license.
9410 However, the requirements of the major FLOSS licenses can begin
9411 to be covered by
9412 assuming that three main areas of concern exist:
9413 <itemizedlist>
9414 <listitem><para>Source code must be provided.</para></listitem>
9415 <listitem><para>License text for the software must be
9416 provided.</para></listitem>
9417 <listitem><para>Compilation scripts and modifications to the
9418 source code must be provided.
9419 </para></listitem>
9420 </itemizedlist>
9421 There are other requirements beyond the scope of these
9422 three and the methods described in this section
9423 (e.g. the mechanism through which source code is distributed).
9424 </para>
9425
9426 <para>
9427 As different organizations have different methods of complying with
9428 open source licensing, this section is not meant to imply that
9429 there is only one single way to meet your compliance obligations,
9430 but rather to describe one method of achieving compliance.
9431 The remainder of this section describes methods supported to meet the
9432 previously mentioned three requirements.
9433 Once you take steps to meet these requirements,
9434 and prior to releasing images, sources, and the build system,
9435 you should audit all artifacts to ensure completeness.
9436 <note>
9437 The Yocto Project generates a license manifest during
9438 image creation that is located
9439 in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
9440 to assist with any audits.
9441 </note>
9442 </para>
9443
9444 <section id='providing-the-source-code'>
9445 <title>Providing the Source Code</title>
9446
9447 <para>
9448 Compliance activities should begin before you generate the
9449 final image.
9450 The first thing you should look at is the requirement that
9451 tops the list for most compliance groups - providing
9452 the source.
9453 The Yocto Project has a few ways of meeting this
9454 requirement.
9455 </para>
9456
9457 <para>
9458 One of the easiest ways to meet this requirement is
9459 to provide the entire
9460 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
9461 used by the build.
9462 This method, however, has a few issues.
9463 The most obvious is the size of the directory since it includes
9464 all sources used in the build and not just the source used in
9465 the released image.
9466 It will include toolchain source, and other artifacts, which
9467 you would not generally release.
9468 However, the more serious issue for most companies is accidental
9469 release of proprietary software.
9470 The Yocto Project provides an
9471 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
9472 class to help avoid some of these concerns.
9473 </para>
9474
9475 <para>
9476 Before you employ <filename>DL_DIR</filename> or the
9477 archiver class, you need to decide how you choose to
9478 provide source.
9479 The source archiver class can generate tarballs and SRPMs
9480 and can create them with various levels of compliance in mind.
9481 </para>
9482
9483 <para>
9484 One way of doing this (but certainly not the only way) is to
9485 release just the source as a tarball.
9486 You can do this by adding the following to the
9487 <filename>local.conf</filename> file found in the
9488 <link linkend='build-directory'>Build Directory</link>:
9489 <literallayout class='monospaced'>
9490 INHERIT += "archiver"
9491 ARCHIVER_MODE[src] = "original"
9492 </literallayout>
9493 During the creation of your image, the source from all
9494 recipes that deploy packages to the image is placed within
9495 subdirectories of
9496 <filename>DEPLOY_DIR/sources</filename> based on the
9497 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
9498 for each recipe.
9499 Releasing the entire directory enables you to comply with
9500 requirements concerning providing the unmodified source.
9501 It is important to note that the size of the directory can
9502 get large.
9503 </para>
9504
9505 <para>
9506 A way to help mitigate the size issue is to only release
9507 tarballs for licenses that require the release of
9508 source.
9509 Let us assume you are only concerned with GPL code as
9510 identified with the following:
9511 <literallayout class='monospaced'>
9512 $ cd poky/build/tmp/deploy/sources
9513 $ mkdir ~/gpl_source_release
9514 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
9515 </literallayout>
9516 At this point, you could create a tarball from the
9517 <filename>gpl_source_release</filename> directory and
9518 provide that to the end user.
9519 This method would be a step toward achieving compliance
9520 with section 3a of GPLv2 and with section 6 of GPLv3.
9521 </para>
9522 </section>
9523
9524 <section id='providing-license-text'>
9525 <title>Providing License Text</title>
9526
9527 <para>
9528 One requirement that is often overlooked is inclusion
9529 of license text.
9530 This requirement also needs to be dealt with prior to
9531 generating the final image.
9532 Some licenses require the license text to accompany
9533 the binary.
9534 You can achieve this by adding the following to your
9535 <filename>local.conf</filename> file:
9536 <literallayout class='monospaced'>
9537 COPY_LIC_MANIFEST = "1"
9538 COPY_LIC_DIRS = "1"
9539 </literallayout>
9540 Adding these statements to the configuration file ensures
9541 that the licenses collected during package generation
9542 are included on your image.
9543 As the source archiver has already archived the original
9544 unmodified source that contains the license files,
9545 you would have already met the requirements for inclusion
9546 of the license information with source as defined by the GPL
9547 and other open source licenses.
9548 </para>
9549 </section>
9550
9551 <section id='providing-compilation-scripts-and-source-code-modifications'>
9552 <title>Providing Compilation Scripts and Source Code Modifications</title>
9553
9554 <para>
9555 At this point, we have addressed all we need to address
9556 prior to generating the image.
9557 The next two requirements are addressed during the final
9558 packaging of the release.
9559 </para>
9560
9561 <para>
9562 By releasing the version of the OpenEmbedded build system
9563 and the layers used during the build, you will be providing both
9564 compilation scripts and the source code modifications in one
9565 step.
9566 </para>
9567
9568 <para>
9569 If the deployment team has a
9570 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
9571 and a distro layer, and those those layers are used to patch,
9572 compile, package, or modify (in any way) any open source
9573 software included in your released images, you
9574 might be required to to release those layers under section 3 of
9575 GPLv2 or section 1 of GPLv3.
9576 One way of doing that is with a clean
9577 checkout of the version of the Yocto Project and layers used
9578 during your build.
9579 Here is an example:
9580 <literallayout class='monospaced'>
9581 # We built using the &DISTRO_NAME; branch of the poky repo
9582 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
9583 $ cd poky
9584 # We built using the release_branch for our layers
9585 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
9586 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
9587 # clean up the .git repos
9588 $ find . -name ".git" -type d -exec rm -rf {} \;
9589 </literallayout>
9590 One thing a development organization might want to consider
9591 for end-user convenience is to modify
9592 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
9593 ensure that when the end user utilizes the released build
9594 system to build an image, the development organization's
9595 layers are included in the <filename>bblayers.conf</filename>
9596 file automatically:
9597 <literallayout class='monospaced'>
9598 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
9599 # changes incompatibly
9600 LCONF_VERSION = "6"
9601
9602 BBPATH = "${TOPDIR}"
9603 BBFILES ?= ""
9604
9605 BBLAYERS ?= " \
9606 ##OEROOT##/meta \
9607 ##OEROOT##/meta-yocto \
9608 ##OEROOT##/meta-yocto-bsp \
9609 ##OEROOT##/meta-mylayer \
9610 "
9611
9612 BBLAYERS_NON_REMOVABLE ?= " \
9613 ##OEROOT##/meta \
9614 ##OEROOT##/meta-yocto \
9615 "
9616 </literallayout>
9617 Creating and providing an archive of the
9618 <link linkend='metadata'>Metadata</link> layers
9619 (recipes, configuration files, and so forth)
9620 enables you to meet your
9621 requirements to include the scripts to control compilation
9622 as well as any modifications to the original source.
9623 </para>
9624 </section>
9625 </section>
9626
9627 <section id='using-the-error-reporting-tool'>
9628 <title>Using the Error Reporting Tool</title>
9629
9630 <para>
9631 The error reporting tool allows you to
9632 submit errors encountered during builds to a central database.
9633 Outside of the build environment, you can use a web interface to
9634 browse errors, view statistics, and query for errors.
9635 The tool works using a client-server system where the client
9636 portion is integrated with the installed Yocto Project
9637 <link linkend='source-directory'>Source Directory</link>
9638 (e.g. <filename>poky</filename>).
9639 The server receives the information collected and saves it in a
9640 database.
9641 </para>
9642
9643 <para>
9644 A live instance of the error reporting server exists at
9645 <ulink url='http://errors.yoctoproject.org'></ulink>.
9646 This server exists so that when you want to get help with
9647 build failures, you can submit all of the information on the
9648 failure easily and then point to the URL in your bug report
9649 or send an email to the mailing list.
9650 <note>
9651 If you send error reports to this server, the reports become
9652 publicly visible.
9653 </note>
9654 </para>
9655
9656 <section id='enabling-and-using-the-tool'>
9657 <title>Enabling and Using the Tool</title>
9658
9659 <para>
9660 By default, the error reporting tool is disabled.
9661 You can enable it by inheriting the
9662 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
9663 class by adding the following statement to the end of
9664 your <filename>local.conf</filename> file in your
9665 <link linkend='build-directory'>Build Directory</link>.
9666 <literallayout class='monospaced'>
9667 INHERIT += "report-error"
9668 </literallayout>
9669 </para>
9670
9671 <para>
9672 By default, the error reporting feature stores information in
9673 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
9674 However, you can specify a directory to use by adding the following
9675 to your <filename>local.conf</filename> file:
9676 <literallayout class='monospaced'>
9677 ERR_REPORT_DIR = "path"
9678 </literallayout>
9679 Enabling error reporting causes the build process to collect
9680 the errors and store them in a file as previously described.
9681 When the build system encounters an error, it includes a command
9682 as part of the console output.
9683 You can run the command to send the error file to the server.
9684 For example, the following command sends the errors to an upstream
9685 server:
9686 <literallayout class='monospaced'>
9687 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
9688 </literallayout>
9689 In the above example, the <filename>server</filename> parameter is
9690 optional.
9691 By default, the errors are sent to a database used by the entire
9692 community.
9693 If you specify a particular server, you can send them to a different
9694 database.
9695 </para>
9696
9697 <para>
9698 When sending the error file, you receive a link that corresponds
9699 to your entry in the database.
9700 For example, here is a typical link:
9701 <literallayout class='monospaced'>
9702 http://localhost:8000/Errors/Search/1/158
9703 </literallayout>
9704 Following the link takes you to a web interface where you can
9705 browse, query the errors, and view statistics.
9706 </para>
9707 </section>
9708
9709 <section id='disabling-the-tool'>
9710 <title>Disabling the Tool</title>
9711
9712 <para>
9713 To disable the error reporting feature, simply remove or comment
9714 out the following statement from the end of your
9715 <filename>local.conf</filename> file in your
9716 <link linkend='build-directory'>Build Directory</link>.
9717 <literallayout class='monospaced'>
9718 INHERIT += "report-error"
9719 </literallayout>
9720 </para>
9721 </section>
9722
9723 <section id='setting-up-your-own-error-reporting-server'>
9724 <title>Setting Up Your Own Error Reporting Server</title>
9725
9726 <para>
9727 If you want to set up your own error reporting server, you
9728 can obtain the code from the Git repository at
9729 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
9730 Instructions on how to set it up are in the README document.
9731 </para>
9732 </section>
9733 </section>
9734</chapter>
9735
9736<!--
9737vim: expandtab tw=80 ts=4
9738-->