summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml7613
1 files changed, 7613 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..27e1b52fc7
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,7613 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='extendpoky'>
6
7<title>Common Tasks</title>
8 <para>
9 This chapter describes fundamental procedures such as creating layers,
10 adding new software packages, extending or customizing images,
11 porting work to new hardware (adding a new machine), and so forth.
12 You will find that the procedures documented here occur often in the
13 development cycle using the Yocto Project.
14 </para>
15
16 <section id="understanding-and-creating-layers">
17 <title>Understanding and Creating Layers</title>
18
19 <para>
20 The OpenEmbedded build system supports organizing
21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from
23 each other.
24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular your Metadata, the easier
27 it is to cope with future changes.
28 </para>
29
30 <para>
31 To illustrate how layers are used to keep things modular, consider
32 machine customizations.
33 These types of customizations typically reside in a special layer,
34 rather than a general layer, called a Board Support Package (BSP)
35 Layer.
36 Furthermore, the machine customizations should be isolated from
37 recipes and Metadata that support a new GUI environment,
38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
44 with those machine-specific changes.
45 You can accomplish this through a recipe that is a BitBake append
46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
48 </para>
49
50 <para>
51 </para>
52
53 <section id='yocto-project-layers'>
54 <title>Layers</title>
55
56 <para>
57 The <link linkend='source-directory'>Source Directory</link>
58 contains both general layers and BSP
59 layers right out of the box.
60 You can easily identify layers that ship with a
61 Yocto Project release in the Source Directory by their
62 folder names.
63 Folders that represent layers typically have names that begin with
64 the string <filename>meta-</filename>.
65 <note>
66 It is not a requirement that a layer name begin with the
67 prefix <filename>meta-</filename>, but it is a commonly
68 accepted standard in the Yocto Project community.
69 </note>
70 For example, when you set up the Source Directory structure,
71 you will see several layers:
72 <filename>meta</filename>,
73 <filename>meta-skeleton</filename>,
74 <filename>meta-yocto</filename>, and
75 <filename>meta-yocto-bsp</filename>.
76 Each of these folders represents a distinct layer.
77 </para>
78
79 <para>
80 As another example, if you set up a local copy of the
81 <filename>meta-intel</filename> Git repository
82 and then explore the folder of that general layer,
83 you will discover many Intel-specific BSP layers inside.
84 For more information on BSP layers, see the
85 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
86 section in the Yocto Project Board Support Package (BSP)
87 Developer's Guide.
88 </para>
89 </section>
90
91 <section id='creating-your-own-layer'>
92 <title>Creating Your Own Layer</title>
93
94 <para>
95 It is very easy to create your own layers to use with the
96 OpenEmbedded build system.
97 The Yocto Project ships with scripts that speed up creating
98 general layers and BSP layers.
99 This section describes the steps you perform by hand to create
100 a layer so that you can better understand them.
101 For information about the layer-creation scripts, see the
102 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
103 section in the Yocto Project Board Support Package (BSP)
104 Developer's Guide and the
105 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
106 section further down in this manual.
107 </para>
108
109 <para>
110 Follow these general steps to create your layer:
111 <orderedlist>
112 <listitem><para><emphasis>Check Existing Layers:</emphasis>
113 Before creating a new layer, you should be sure someone
114 has not already created a layer containing the Metadata
115 you need.
116 You can see the
117 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
118 for a list of layers from the OpenEmbedded community
119 that can be used in the Yocto Project.
120 </para></listitem>
121 <listitem><para><emphasis>Create a Directory:</emphasis>
122 Create the directory for your layer.
123 While not strictly required, prepend the name of the
124 folder with the string <filename>meta-</filename>.
125 For example:
126 <literallayout class='monospaced'>
127 meta-mylayer
128 meta-GUI_xyz
129 meta-mymachine
130 </literallayout>
131 </para></listitem>
132 <listitem><para><emphasis>Create a Layer Configuration
133 File:</emphasis>
134 Inside your new layer folder, you need to create a
135 <filename>conf/layer.conf</filename> file.
136 It is easiest to take an existing layer configuration
137 file and copy that to your layer's
138 <filename>conf</filename> directory and then modify the
139 file as needed.</para>
140 <para>The
141 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
142 demonstrates the required syntax:
143 <literallayout class='monospaced'>
144 # We have a conf and classes directory, add to BBPATH
145 BBPATH .= ":${LAYERDIR}"
146
147 # We have recipes-* directories, add to BBFILES
148 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
149 ${LAYERDIR}/recipes-*/*/*.bbappend"
150
151 BBFILE_COLLECTIONS += "yoctobsp"
152 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
153 BBFILE_PRIORITY_yoctobsp = "5"
154 LAYERVERSION_yoctobsp = "2"
155 </literallayout></para>
156 <para>Here is an explanation of the example:
157 <itemizedlist>
158 <listitem><para>The configuration and
159 classes directory is appended to
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
161 <note>
162 All non-distro layers, which include all BSP
163 layers, are expected to append the layer
164 directory to the
165 <filename>BBPATH</filename>.
166 On the other hand, distro layers, such as
167 <filename>meta-yocto</filename>, can choose
168 to enforce their own precedence over
169 <filename>BBPATH</filename>.
170 For an example of that syntax, see the
171 <filename>layer.conf</filename> file for
172 the <filename>meta-yocto</filename> layer.
173 </note></para></listitem>
174 <listitem><para>The recipes for the layers are
175 appended to
176 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
177 </para></listitem>
178 <listitem><para>The
179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
180 variable is then appended with the layer name.
181 </para></listitem>
182 <listitem><para>The
183 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
184 variable is set to a regular expression and is
185 used to match files from
186 <filename>BBFILES</filename> into a particular
187 layer.
188 In this case,
189 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
190 is used to make <filename>BBFILE_PATTERN</filename> match within the
191 layer's path.</para></listitem>
192 <listitem><para>The
193 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
194 variable then assigns a priority to the layer.
195 Applying priorities is useful in situations
196 where the same package might appear in multiple
197 layers and allows you to choose the layer
198 that takes precedence.</para></listitem>
199 <listitem><para>The
200 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
201 variable optionally specifies the version of a
202 layer as a single number.</para></listitem>
203 </itemizedlist></para>
204 <para>Note the use of the
205 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
206 variable, which expands to the directory of the current
207 layer.</para>
208 <para>Through the use of the <filename>BBPATH</filename>
209 variable, BitBake locates class files
210 (<filename>.bbclass</filename>),
211 configuration files, and files that are included
212 with <filename>include</filename> and
213 <filename>require</filename> statements.
214 For these cases, BitBake uses the first file that
215 matches the name found in <filename>BBPATH</filename>.
216 This is similar to the way the <filename>PATH</filename>
217 variable is used for binaries.
218 It is recommended, therefore, that you use unique
219 class and configuration
220 filenames in your custom layer.</para></listitem>
221 <listitem><para><emphasis>Add Content:</emphasis> Depending
222 on the type of layer, add the content.
223 If the layer adds support for a machine, add the machine
224 configuration in a <filename>conf/machine/</filename>
225 file within the layer.
226 If the layer adds distro policy, add the distro
227 configuration in a <filename>conf/distro/</filename>
228 file within the layer.
229 If the layer introduces new recipes, put the recipes
230 you need in <filename>recipes-*</filename>
231 subdirectories within the layer.
232 <note>In order to be compliant with the Yocto Project,
233 a layer must contain a
234 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
235 </note></para></listitem>
236 </orderedlist>
237 </para>
238 </section>
239
240 <section id='best-practices-to-follow-when-creating-layers'>
241 <title>Best Practices to Follow When Creating Layers</title>
242
243 <para>
244 To create layers that are easier to maintain and that will
245 not impact builds for other machines, you should consider the
246 information in the following sections.
247 </para>
248
249 <section id='avoid-overlaying-entire-recipes'>
250 <title>Avoid "Overlaying" Entire Recipes</title>
251
252 <para>
253 Avoid "overlaying" entire recipes from other layers in your
254 configuration.
255 In other words, do not copy an entire recipe into your
256 layer and then modify it.
257 Rather, use an append file (<filename>.bbappend</filename>)
258 to override
259 only those parts of the original recipe you need to modify.
260 </para>
261 </section>
262
263 <section id='avoid-duplicating-include-files'>
264 <title>Avoid Duplicating Include Files</title>
265
266 <para>
267 Avoid duplicating include files.
268 Use append files (<filename>.bbappend</filename>)
269 for each recipe
270 that uses an include file.
271 Or, if you are introducing a new recipe that requires
272 the included file, use the path relative to the original
273 layer directory to refer to the file.
274 For example, use
275 <filename>require recipes-core/somepackage/somefile.inc</filename>
276 instead of <filename>require somefile.inc</filename>.
277 If you're finding you have to overlay the include file,
278 it could indicate a deficiency in the include file in
279 the layer to which it originally belongs.
280 If this is the case, you need to address that deficiency
281 instead of overlaying the include file.
282 </para>
283
284 <para>
285 For example, consider how support plug-ins for the Qt 4
286 database are configured.
287 The Source Directory does not have MySQL or PostgreSQL.
288 However, OpenEmbedded's layer <filename>meta-oe</filename>
289 does.
290 Consequently, <filename>meta-oe</filename> uses
291 append files to modify the
292 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
293 enable the appropriate plug-ins.
294 This variable was added to the <filename>qt4.inc</filename>
295 include file in the Source Directory specifically to allow
296 the <filename>meta-oe</filename> layer to be able to control
297 which plug-ins are built.
298 </para>
299 </section>
300
301 <section id='structure-your-layers'>
302 <title>Structure Your Layers</title>
303
304 <para>
305 Proper use of overrides within append files and placement
306 of machine-specific files within your layer can ensure that
307 a build is not using the wrong Metadata and negatively
308 impacting a build for a different machine.
309 Following are some examples:
310 <itemizedlist>
311 <listitem><para><emphasis>Modifying Variables to Support
312 a Different Machine:</emphasis>
313 Suppose you have a layer named
314 <filename>meta-one</filename> that adds support
315 for building machine "one".
316 To do so, you use an append file named
317 <filename>base-files.bbappend</filename> and
318 create a dependency on "foo" by altering the
319 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
320 variable:
321 <literallayout class='monospaced'>
322 DEPENDS = "foo"
323 </literallayout>
324 The dependency is created during any build that
325 includes the layer
326 <filename>meta-one</filename>.
327 However, you might not want this dependency
328 for all machines.
329 For example, suppose you are building for
330 machine "two" but your
331 <filename>bblayers.conf</filename> file has the
332 <filename>meta-one</filename> layer included.
333 During the build, the
334 <filename>base-files</filename> for machine
335 "two" will also have the dependency on
336 <filename>foo</filename>.</para>
337 <para>To make sure your changes apply only when
338 building machine "one", use a machine override
339 with the <filename>DEPENDS</filename> statement:
340 <literallayout class='monospaced'>
341 DEPENDS_one = "foo"
342 </literallayout>
343 You should follow the same strategy when using
344 <filename>_append</filename> and
345 <filename>_prepend</filename> operations:
346 <literallayout class='monospaced'>
347 DEPENDS_append_one = " foo"
348 DEPENDS_prepend_one = "foo "
349 </literallayout>
350 <note>
351 Avoiding "+=" and "=+" and using
352 machine-specific
353 <filename>_append</filename>
354 and <filename>_prepend</filename> operations
355 is recommended as well.
356 </note></para></listitem>
357 <listitem><para><emphasis>Place Machine-Specific Files
358 in Machine-Specific Locations:</emphasis>
359 When you have a base recipe, such as
360 <filename>base-files.bb</filename>, that
361 contains a
362 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
363 statement to a file, you can use an append file
364 to cause the build to use your own version of
365 the file.
366 For example, an append file in your layer at
367 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
368 could extend
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
370 using
371 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
372 as follows:
373 <literallayout class='monospaced'>
374 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
375 </literallayout>
376 The build for machine "one" will pick up your
377 machine-specific file as long as you have the
378 file in
379 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
380 However, if you are building for a different
381 machine and the
382 <filename>bblayers.conf</filename> file includes
383 the <filename>meta-one</filename> layer and
384 the location of your machine-specific file is
385 the first location where that file is found
386 according to <filename>FILESPATH</filename>,
387 builds for all machines will also use that
388 machine-specific file.</para>
389 <para>You can make sure that a machine-specific
390 file is used for a particular machine by putting
391 the file in a subdirectory specific to the
392 machine.
393 For example, rather than placing the file in
394 <filename>meta-one/recipes-core/base-files/base-files/</filename>
395 as shown above, put it in
396 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
397 Not only does this make sure the file is used
398 only when building for machine "one", but the
399 build process locates the file more quickly.</para>
400 <para>In summary, you need to place all files
401 referenced from <filename>SRC_URI</filename>
402 in a machine-specific subdirectory within the
403 layer in order to restrict those files to
404 machine-specific builds.</para></listitem>
405 </itemizedlist>
406 </para>
407 </section>
408
409 <section id='other-recommendations'>
410 <title>Other Recommendations</title>
411
412 <para>
413 We also recommend the following:
414 <itemizedlist>
415 <listitem><para>Store custom layers in a Git repository
416 that uses the
417 <filename>meta-&lt;layer_name&gt;</filename> format.
418 </para></listitem>
419 <listitem><para>Clone the repository alongside other
420 <filename>meta</filename> directories in the
421 <link linkend='source-directory'>Source Directory</link>.
422 </para></listitem>
423 </itemizedlist>
424 Following these recommendations keeps your Source Directory and
425 its configuration entirely inside the Yocto Project's core
426 base.
427 </para>
428 </section>
429 </section>
430
431 <section id='enabling-your-layer'>
432 <title>Enabling Your Layer</title>
433
434 <para>
435 Before the OpenEmbedded build system can use your new layer,
436 you need to enable it.
437 To enable your layer, simply add your layer's path to the
438 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
439 variable in your <filename>conf/bblayers.conf</filename> file,
440 which is found in the
441 <link linkend='build-directory'>Build Directory</link>.
442 The following example shows how to enable a layer named
443 <filename>meta-mylayer</filename>:
444 <literallayout class='monospaced'>
445 LCONF_VERSION = "6"
446
447 BBPATH = "${TOPDIR}"
448 BBFILES ?= ""
449
450 BBLAYERS ?= " \
451 $HOME/poky/meta \
452 $HOME/poky/meta-yocto \
453 $HOME/poky/meta-yocto-bsp \
454 $HOME/poky/meta-mylayer \
455 "
456
457 BBLAYERS_NON_REMOVABLE ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 "
461 </literallayout>
462 </para>
463
464 <para>
465 BitBake parses each <filename>conf/layer.conf</filename> file
466 as specified in the <filename>BBLAYERS</filename> variable
467 within the <filename>conf/bblayers.conf</filename> file.
468 During the processing of each
469 <filename>conf/layer.conf</filename> file, BitBake adds the
470 recipes, classes and configurations contained within the
471 particular layer to the source directory.
472 </para>
473 </section>
474
475 <section id='using-bbappend-files'>
476 <title>Using .bbappend Files</title>
477
478 <para>
479 Recipes used to append Metadata to other recipes are called
480 BitBake append files.
481 BitBake append files use the <filename>.bbappend</filename> file
482 type suffix, while the corresponding recipes to which Metadata
483 is being appended use the <filename>.bb</filename> file type
484 suffix.
485 </para>
486
487 <para>
488 A <filename>.bbappend</filename> file allows your layer to make
489 additions or changes to the content of another layer's recipe
490 without having to copy the other recipe into your layer.
491 Your <filename>.bbappend</filename> file resides in your layer,
492 while the main <filename>.bb</filename> recipe file to
493 which you are appending Metadata resides in a different layer.
494 </para>
495
496 <para>
497 Append files must have the same root names as their corresponding
498 recipes.
499 For example, the append file
500 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
501 <filename>someapp_&DISTRO;.bb</filename>.
502 This means the original recipe and append file names are version
503 number-specific.
504 If the corresponding recipe is renamed to update to a newer
505 version, the corresponding <filename>.bbappend</filename> file must
506 be renamed (and possibly updated) as well.
507 During the build process, BitBake displays an error on starting
508 if it detects a <filename>.bbappend</filename> file that does
509 not have a corresponding recipe with a matching name.
510 See the
511 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
512 variable for information on how to handle this error.
513 </para>
514
515 <para>
516 Being able to append information to an existing recipe not only
517 avoids duplication, but also automatically applies recipe
518 changes in a different layer to your layer.
519 If you were copying recipes, you would have to manually merge
520 changes as they occur.
521 </para>
522
523 <para>
524 As an example, consider the main formfactor recipe and a
525 corresponding formfactor append file both from the
526 <link linkend='source-directory'>Source Directory</link>.
527 Here is the main formfactor recipe, which is named
528 <filename>formfactor_0.0.bb</filename> and located in the
529 "meta" layer at
530 <filename>meta/recipes-bsp/formfactor</filename>:
531 <literallayout class='monospaced'>
532 SUMMARY = "Device formfactor information"
533 SECTION = "base"
534 LICENSE = "MIT"
535 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
536 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
537 PR = "r44"
538
539 SRC_URI = "file://config file://machconfig"
540 S = "${WORKDIR}"
541
542 PACKAGE_ARCH = "${MACHINE_ARCH}"
543 INHIBIT_DEFAULT_DEPS = "1"
544
545 do_install() {
546 # Only install file if it has a contents
547 install -d ${D}${sysconfdir}/formfactor/
548 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
549 if [ -s "${S}/machconfig" ]; then
550 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
551 fi
552 }
553 </literallayout>
554 In the main recipe, note the
555 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
556 variable, which tells the OpenEmbedded build system where to
557 find files during the build.
558 </para>
559
560 <para>
561 Following is the append file, which is named
562 <filename>formfactor_0.0.bbappend</filename> and is from the
563 Crown Bay BSP Layer named
564 <filename>meta-intel/meta-crownbay</filename>.
565 The file is in <filename>recipes-bsp/formfactor</filename>:
566 <literallayout class='monospaced'>
567 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
568 </literallayout>
569 </para>
570
571 <para>
572 By default, the build system uses the
573 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
574 variable to locate files.
575 This append file extends the locations by setting the
576 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
577 variable.
578 Setting this variable in the <filename>.bbappend</filename>
579 file is the most reliable and recommended method for adding
580 directories to the search path used by the build system
581 to find files.
582 </para>
583
584 <para>
585 The statement in this example extends the directories to include
586 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
587 which resolves to a directory named
588 <filename>formfactor</filename> in the same directory
589 in which the append file resides (i.e.
590 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
591 This implies that you must have the supporting directory
592 structure set up that will contain any files or patches you
593 will be including from the layer.
594 </para>
595
596 <para>
597 Using the immediate expansion assignment operator
598 <filename>:=</filename> is important because of the reference to
599 <filename>THISDIR</filename>.
600 The trailing colon character is important as it ensures that
601 items in the list remain colon-separated.
602 <note>
603 <para>
604 BitBake automatically defines the
605 <filename>THISDIR</filename> variable.
606 You should never set this variable yourself.
607 Using "_prepend" ensures your path will
608 be searched prior to other paths in the final list.
609 </para>
610
611 <para>
612 Also, not all append files add extra files.
613 Many append files simply exist to add build options
614 (e.g. <filename>systemd</filename>).
615 For these cases, it is not necessary to use the
616 "_prepend" part of the statement.
617 </para>
618 </note>
619 </para>
620 </section>
621
622 <section id='prioritizing-your-layer'>
623 <title>Prioritizing Your Layer</title>
624
625 <para>
626 Each layer is assigned a priority value.
627 Priority values control which layer takes precedence if there
628 are recipe files with the same name in multiple layers.
629 For these cases, the recipe file from the layer with a higher
630 priority number takes precedence.
631 Priority values also affect the order in which multiple
632 <filename>.bbappend</filename> files for the same recipe are
633 applied.
634 You can either specify the priority manually, or allow the
635 build system to calculate it based on the layer's dependencies.
636 </para>
637
638 <para>
639 To specify the layer's priority manually, use the
640 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
641 variable.
642 For example:
643 <literallayout class='monospaced'>
644 BBFILE_PRIORITY_mylayer = "1"
645 </literallayout>
646 </para>
647
648 <note>
649 <para>It is possible for a recipe with a lower version number
650 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
651 in a layer that has a higher priority to take precedence.</para>
652 <para>Also, the layer priority does not currently affect the
653 precedence order of <filename>.conf</filename>
654 or <filename>.bbclass</filename> files.
655 Future versions of BitBake might address this.</para>
656 </note>
657 </section>
658
659 <section id='managing-layers'>
660 <title>Managing Layers</title>
661
662 <para>
663 You can use the BitBake layer management tool to provide a view
664 into the structure of recipes across a multi-layer project.
665 Being able to generate output that reports on configured layers
666 with their paths and priorities and on
667 <filename>.bbappend</filename> files and their applicable
668 recipes can help to reveal potential problems.
669 </para>
670
671 <para>
672 Use the following form when running the layer management tool.
673 <literallayout class='monospaced'>
674 $ bitbake-layers &lt;command&gt; [arguments]
675 </literallayout>
676 The following list describes the available commands:
677 <itemizedlist>
678 <listitem><para><filename><emphasis>help:</emphasis></filename>
679 Displays general help or help on a specified command.
680 </para></listitem>
681 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
682 Shows the current configured layers.
683 </para></listitem>
684 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
685 Lists available recipes and the layers that provide them.
686 </para></listitem>
687 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
688 Lists overlayed recipes.
689 A recipe is overlayed when a recipe with the same name
690 exists in another layer that has a higher layer
691 priority.
692 </para></listitem>
693 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
694 Lists <filename>.bbappend</filename> files and the
695 recipe files to which they apply.
696 </para></listitem>
697 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
698 Lists dependency relationships between recipes that
699 cross layer boundaries.
700 </para></listitem>
701 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
702 Flattens the layer configuration into a separate output
703 directory.
704 Flattening your layer configuration builds a "flattened"
705 directory that contains the contents of all layers,
706 with any overlayed recipes removed and any
707 <filename>.bbappend</filename> files appended to the
708 corresponding recipes.
709 You might have to perform some manual cleanup of the
710 flattened layer as follows:
711 <itemizedlist>
712 <listitem><para>Non-recipe files (such as patches)
713 are overwritten.
714 The flatten command shows a warning for these
715 files.
716 </para></listitem>
717 <listitem><para>Anything beyond the normal layer
718 setup has been added to the
719 <filename>layer.conf</filename> file.
720 Only the lowest priority layer's
721 <filename>layer.conf</filename> is used.
722 </para></listitem>
723 <listitem><para>Overridden and appended items from
724 <filename>.bbappend</filename> files need to be
725 cleaned up.
726 The contents of each
727 <filename>.bbappend</filename> end up in the
728 flattened recipe.
729 However, if there are appended or changed
730 variable values, you need to tidy these up
731 yourself.
732 Consider the following example.
733 Here, the <filename>bitbake-layers</filename>
734 command adds the line
735 <filename>#### bbappended ...</filename> so that
736 you know where the following lines originate:
737 <literallayout class='monospaced'>
738 ...
739 DESCRIPTION = "A useful utility"
740 ...
741 EXTRA_OECONF = "--enable-something"
742 ...
743
744 #### bbappended from meta-anotherlayer ####
745
746 DESCRIPTION = "Customized utility"
747 EXTRA_OECONF += "--enable-somethingelse"
748 </literallayout>
749 Ideally, you would tidy up these utilities as
750 follows:
751 <literallayout class='monospaced'>
752 ...
753 DESCRIPTION = "Customized utility"
754 ...
755 EXTRA_OECONF = "--enable-something --enable-somethingelse"
756 ...
757 </literallayout></para></listitem>
758 </itemizedlist></para></listitem>
759 </itemizedlist>
760 </para>
761 </section>
762
763 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
764 <title>Creating a General Layer Using the yocto-layer Script</title>
765
766 <para>
767 The <filename>yocto-layer</filename> script simplifies
768 creating a new general layer.
769 <note>
770 For information on BSP layers, see the
771 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
772 section in the Yocto Project Board Specific (BSP)
773 Developer's Guide.
774 </note>
775 The default mode of the script's operation is to prompt you for
776 information needed to generate the layer:
777 <itemizedlist>
778 <listitem><para>The layer priority
779 </para></listitem>
780 <listitem><para>Whether or not to create a sample recipe.
781 </para></listitem>
782 <listitem><para>Whether or not to create a sample
783 append file.
784 </para></listitem>
785 </itemizedlist>
786 </para>
787
788 <para>
789 Use the <filename>yocto-layer create</filename> sub-command
790 to create a new general layer.
791 In its simplest form, you can create a layer as follows:
792 <literallayout class='monospaced'>
793 $ yocto-layer create mylayer
794 </literallayout>
795 The previous example creates a layer named
796 <filename>meta-mylayer</filename> in the current directory.
797 </para>
798
799 <para>
800 As the <filename>yocto-layer create</filename> command runs,
801 default values for the prompts appear in brackets.
802 Pressing enter without supplying anything for the prompts
803 or pressing enter and providing an invalid response causes the
804 script to accept the default value.
805 Once the script completes, the new layer
806 is created in the current working directory.
807 The script names the layer by prepending
808 <filename>meta-</filename> to the name you provide.
809 </para>
810
811 <para>
812 Minimally, the script creates the following within the layer:
813 <itemizedlist>
814 <listitem><para><emphasis>The <filename>conf</filename>
815 directory:</emphasis>
816 This directory contains the layer's configuration file.
817 The root name for the file is the same as the root name
818 your provided for the layer (e.g.
819 <filename>&lt;layer&gt;.conf</filename>).
820 </para></listitem>
821 <listitem><para><emphasis>The
822 <filename>COPYING.MIT</filename> file:</emphasis>
823 The copyright and use notice for the software.
824 </para></listitem>
825 <listitem><para><emphasis>The <filename>README</filename>
826 file:</emphasis>
827 A file describing the contents of your new layer.
828 </para></listitem>
829 </itemizedlist>
830 </para>
831
832 <para>
833 If you choose to generate a sample recipe file, the script
834 prompts you for the name for the recipe and then creates it
835 in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
836 The script creates a <filename>.bb</filename> file and a
837 directory, which contains a sample
838 <filename>helloworld.c</filename> source file, along with
839 a sample patch file.
840 If you do not provide a recipe name, the script uses
841 "example".
842 </para>
843
844 <para>
845 If you choose to generate a sample append file, the script
846 prompts you for the name for the file and then creates it
847 in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
848 The script creates a <filename>.bbappend</filename> file and a
849 directory, which contains a sample patch file.
850 If you do not provide a recipe name, the script uses
851 "example".
852 The script also prompts you for the version of the append file.
853 The version should match the recipe to which the append file
854 is associated.
855 </para>
856
857 <para>
858 The easiest way to see how the <filename>yocto-layer</filename>
859 script works is to experiment with the script.
860 You can also read the usage information by entering the
861 following:
862 <literallayout class='monospaced'>
863 $ yocto-layer help
864 </literallayout>
865 </para>
866
867 <para>
868 Once you create your general layer, you must add it to your
869 <filename>bblayers.conf</filename> file.
870 Here is an example where a layer named
871 <filename>meta-mylayer</filename> is added:
872 <literallayout class='monospaced'>
873 BBLAYERS = ?" \
874 /usr/local/src/yocto/meta \
875 /usr/local/src/yocto/meta-yocto \
876 /usr/local/src/yocto/meta-yocto-bsp \
877 /usr/local/src/yocto/meta-mylayer \
878 "
879
880 BBLAYERS_NON_REMOVABLE ?= " \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 "
884 </literallayout>
885 Adding the layer to this file enables the build system to
886 locate the layer during the build.
887 </para>
888 </section>
889 </section>
890
891 <section id='usingpoky-extend-customimage'>
892 <title>Customizing Images</title>
893
894 <para>
895 You can customize images to satisfy particular requirements.
896 This section describes several methods and provides guidelines for each.
897 </para>
898
899 <section id='usingpoky-extend-customimage-localconf'>
900 <title>Customizing Images Using <filename>local.conf</filename></title>
901
902 <para>
903 Probably the easiest way to customize an image is to add a
904 package by way of the <filename>local.conf</filename>
905 configuration file.
906 Because it is limited to local use, this method generally only
907 allows you to add packages and is not as flexible as creating
908 your own customized image.
909 When you add packages using local variables this way, you need
910 to realize that these variable changes are in effect for every
911 build and consequently affect all images, which might not
912 be what you require.
913 </para>
914
915 <para>
916 To add a package to your image using the local configuration
917 file, use the
918 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
919 variable with the <filename>_append</filename> operator:
920 <literallayout class='monospaced'>
921 IMAGE_INSTALL_append = " strace"
922 </literallayout>
923 Use of the syntax is important - specifically, the space between
924 the quote and the package name, which is
925 <filename>strace</filename> in this example.
926 This space is required since the <filename>_append</filename>
927 operator does not add the space.
928 </para>
929
930 <para>
931 Furthermore, you must use <filename>_append</filename> instead
932 of the <filename>+=</filename> operator if you want to avoid
933 ordering issues.
934 The reason for this is because doing so unconditionally appends
935 to the variable and avoids ordering problems due to the
936 variable being set in image recipes and
937 <filename>.bbclass</filename> files with operators like
938 <filename>?=</filename>.
939 Using <filename>_append</filename> ensures the operation takes
940 affect.
941 </para>
942
943 <para>
944 As shown in its simplest use,
945 <filename>IMAGE_INSTALL_append</filename> affects all images.
946 It is possible to extend the syntax so that the variable
947 applies to a specific image only.
948 Here is an example:
949 <literallayout class='monospaced'>
950 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
951 </literallayout>
952 This example adds <filename>strace</filename> to the
953 <filename>core-image-minimal</filename> image only.
954 </para>
955
956 <para>
957 You can add packages using a similar approach through the
958 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
959 variable.
960 If you use this variable, only
961 <filename>core-image-*</filename> images are affected.
962 </para>
963 </section>
964
965 <section id='usingpoky-extend-customimage-imagefeatures'>
966 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
967 <filename>EXTRA_IMAGE_FEATURES</filename></title>
968
969 <para>
970 Another method for customizing your image is to enable or
971 disable high-level image features by using the
972 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
973 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
974 variables.
975 Although the functions for both variables are nearly equivalent,
976 best practices dictate using <filename>IMAGE_FEATURES</filename>
977 from within a recipe and using
978 <filename>EXTRA_IMAGE_FEATURES</filename> from within
979 your <filename>local.conf</filename> file, which is found in the
980 <link linkend='build-directory'>Build Directory</link>.
981 </para>
982
983 <para>
984 To understand how these features work, the best reference is
985 <filename>meta/classes/core-image.bbclass</filename>.
986 In summary, the file looks at the contents of the
987 <filename>IMAGE_FEATURES</filename> variable and then maps
988 those contents into a set of package groups.
989 Based on this information, the build system automatically
990 adds the appropriate packages to the
991 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
992 variable.
993 Effectively, you are enabling extra features by extending the
994 class or creating a custom class for use with specialized image
995 <filename>.bb</filename> files.
996 </para>
997
998 <para>
999 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1000 from within your local configuration file.
1001 Using a separate area from which to enable features with
1002 this variable helps you avoid overwriting the features in the
1003 image recipe that are enabled with
1004 <filename>IMAGE_FEATURES</filename>.
1005 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1006 to <filename>IMAGE_FEATURES</filename> within
1007 <filename>meta/conf/bitbake.conf</filename>.
1008 </para>
1009
1010 <para>
1011 To illustrate how you can use these variables to modify your
1012 image, consider an example that selects the SSH server.
1013 The Yocto Project ships with two SSH servers you can use
1014 with your images: Dropbear and OpenSSH.
1015 Dropbear is a minimal SSH server appropriate for
1016 resource-constrained environments, while OpenSSH is a
1017 well-known standard SSH server implementation.
1018 By default, the <filename>core-image-sato</filename> image
1019 is configured to use Dropbear.
1020 The <filename>core-image-full-cmdline</filename> and
1021 <filename>core-image-lsb</filename> images both
1022 include OpenSSH.
1023 The <filename>core-image-minimal</filename> image does not
1024 contain an SSH server.
1025 </para>
1026
1027 <para>
1028 You can customize your image and change these defaults.
1029 Edit the <filename>IMAGE_FEATURES</filename> variable
1030 in your recipe or use the
1031 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1032 <filename>local.conf</filename> file so that it configures the
1033 image you are working with to include
1034 <filename>ssh-server-dropbear</filename> or
1035 <filename>ssh-server-openssh</filename>.
1036 </para>
1037
1038 <note>
1039 See the
1040 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1041 section in the Yocto Project Reference Manual for a complete
1042 list of image features that ship with the Yocto Project.
1043 </note>
1044 </section>
1045
1046 <section id='usingpoky-extend-customimage-custombb'>
1047 <title>Customizing Images Using Custom .bb Files</title>
1048
1049 <para>
1050 You can also customize an image by creating a custom recipe
1051 that defines additional software as part of the image.
1052 The following example shows the form for the two lines you need:
1053 <literallayout class='monospaced'>
1054 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1055
1056 inherit core-image
1057 </literallayout>
1058 </para>
1059
1060 <para>
1061 Defining the software using a custom recipe gives you total
1062 control over the contents of the image.
1063 It is important to use the correct names of packages in the
1064 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1065 variable.
1066 You must use the OpenEmbedded notation and not the Debian notation for the names
1067 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
1068 </para>
1069
1070 <para>
1071 The other method for creating a custom image is to base it on an existing image.
1072 For example, if you want to create an image based on <filename>core-image-sato</filename>
1073 but add the additional package <filename>strace</filename> to the image,
1074 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1075 new <filename>.bb</filename> and add the following line to the end of the copy:
1076 <literallayout class='monospaced'>
1077 IMAGE_INSTALL += "strace"
1078 </literallayout>
1079 </para>
1080 </section>
1081
1082 <section id='usingpoky-extend-customimage-customtasks'>
1083 <title>Customizing Images Using Custom Package Groups</title>
1084
1085 <para>
1086 For complex custom images, the best approach for customizing
1087 an image is to create a custom package group recipe that is
1088 used to build the image or images.
1089 A good example of a package group recipe is
1090 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1091 The
1092 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1093 variable lists the package group packages you wish to produce.
1094 <filename>inherit packagegroup</filename> sets appropriate
1095 default values and automatically adds <filename>-dev</filename>,
1096 <filename>-dbg</filename>, and <filename>-ptest</filename>
1097 complementary packages for every package specified in
1098 <filename>PACKAGES</filename>.
1099 Note that the inherit line should be towards
1100 the top of the recipe, certainly before you set
1101 <filename>PACKAGES</filename>.
1102 For each package you specify in <filename>PACKAGES</filename>,
1103 you can use
1104 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1105 and
1106 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1107 entries to provide a list of packages the parent task package
1108 should contain.
1109 Following is an example:
1110 <literallayout class='monospaced'>
1111 DESCRIPTION = "My Custom Package Groups"
1112
1113 inherit packagegroup
1114
1115 PACKAGES = "\
1116 packagegroup-custom-apps \
1117 packagegroup-custom-tools \
1118 "
1119
1120 RDEPENDS_packagegroup-custom-apps = "\
1121 dropbear \
1122 portmap \
1123 psplash"
1124
1125 RDEPENDS_packagegroup-custom-tools = "\
1126 oprofile \
1127 oprofileui-server \
1128 lttng-control \
1129 lttng-viewer"
1130
1131 RRECOMMENDS_packagegroup-custom-tools = "\
1132 kernel-module-oprofile"
1133 </literallayout>
1134 </para>
1135
1136 <para>
1137 In the previous example, two package group packages are created with their dependencies and their
1138 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1139 <filename>packagegroup-custom-tools</filename>.
1140 To build an image using these package group packages, you need to add
1141 <filename>packagegroup-custom-apps</filename> and/or
1142 <filename>packagegroup-custom-tools</filename> to
1143 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1144 For other forms of image dependencies see the other areas of this section.
1145 </para>
1146 </section>
1147 </section>
1148
1149 <section id='new-recipe-writing-a-new-recipe'>
1150 <title>Writing a New Recipe</title>
1151
1152 <para>
1153 Recipes (<filename>.bb</filename> files) are fundamental components
1154 in the Yocto Project environment.
1155 Each software component built by the OpenEmbedded build system
1156 requires a recipe to define the component.
1157 This section describes how to create, write, and test a new
1158 recipe.
1159 <note>
1160 For information on variables that are useful for recipes and
1161 for information about recipe naming issues, see the
1162 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1163 section of the Yocto Project Reference Manual.
1164 </note>
1165 </para>
1166
1167 <section id='new-recipe-overview'>
1168 <title>Overview</title>
1169
1170 <para>
1171 The following figure shows the basic process for creating a
1172 new recipe.
1173 The remainder of the section provides details for the steps.
1174 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1175 </para>
1176 </section>
1177
1178 <section id='new-recipe-locate-a-base-recipe'>
1179 <title>Locate a Base Recipe</title>
1180
1181 <para>
1182 Before writing a recipe from scratch, it is often useful to
1183 discover whether someone else has already written one that
1184 meets (or comes close to meeting) your needs.
1185 The Yocto Project and OpenEmbedded communities maintain many
1186 recipes that might be candidates for what you are doing.
1187 You can find a good central index of these recipes in the
1188 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1189 </para>
1190
1191 <para>
1192 Working from an existing recipe or a skeleton recipe is the
1193 best way to get started.
1194 Here are some points on both methods:
1195 <itemizedlist>
1196 <listitem><para><emphasis>Locate and modify a recipe that
1197 is close to what you want to do:</emphasis>
1198 This method works when you are familiar with the
1199 current recipe space.
1200 The method does not work so well for those new to
1201 the Yocto Project or writing recipes.</para>
1202 <para>Some risks associated with this method are
1203 using a recipe that has areas totally unrelated to
1204 what you are trying to accomplish with your recipe,
1205 not recognizing areas of the recipe that you might
1206 have to add from scratch, and so forth.
1207 All these risks stem from unfamiliarity with the
1208 existing recipe space.</para></listitem>
1209 <listitem><para><emphasis>Use and modify the following
1210 skeleton recipe:</emphasis>
1211 <literallayout class='monospaced'>
1212 SUMMARY = ""
1213 HOMEPAGE = ""
1214 LICENSE = ""
1215
1216 LIC_FILES_CHKSUM = ""
1217
1218 SRC_URI = ""
1219 SRC_URI[md5sum] = ""
1220 SRC_URI[sha256sum] = ""
1221
1222 S = "${WORKDIR}/${PN}-${PV}"
1223
1224 inherit &lt;stuff&gt;
1225 </literallayout>
1226 Modifying this recipe is the recommended method for
1227 creating a new recipe.
1228 The recipe provides the fundamental areas that you need
1229 to include, exclude, or alter to fit your needs.
1230 </para></listitem>
1231 </itemizedlist>
1232 </para>
1233 </section>
1234
1235 <section id='new-recipe-storing-and-naming-the-recipe'>
1236 <title>Storing and Naming the Recipe</title>
1237
1238 <para>
1239 Once you have your base recipe, you should put it in your
1240 own layer and name it appropriately.
1241 Locating it correctly ensures that the OpenEmbedded build
1242 system can find it when you use BitBake to process the
1243 recipe.
1244 </para>
1245
1246 <itemizedlist>
1247 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1248 The OpenEmbedded build system locates your recipe
1249 through the layer's <filename>conf/layer.conf</filename>
1250 file and the
1251 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1252 variable.
1253 This variable sets up a path from which the build system can
1254 locate recipes.
1255 Here is the typical use:
1256 <literallayout class='monospaced'>
1257 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1258 ${LAYERDIR}/recipes-*/*/*.bbappend"
1259 </literallayout>
1260 Consequently, you need to be sure you locate your new recipe
1261 inside your layer such that it can be found.</para>
1262 <para>You can find more information on how layers are
1263 structured in the
1264 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1265 section.</para></listitem>
1266 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1267 When you name your recipe, you need to follow this naming
1268 convention:
1269 <literallayout class='monospaced'>
1270 &lt;basename&gt;_&lt;version&gt;.bb
1271 </literallayout>
1272 Use lower-cased characters and do not include the reserved
1273 suffixes <filename>-native</filename>,
1274 <filename>-cross</filename>, <filename>-initial</filename>,
1275 or <filename>-dev</filename> casually (i.e. do not use them
1276 as part of your recipe name unless the string applies).
1277 Here are some examples:
1278 <literallayout class='monospaced'>
1279 cups_1.7.0.bb
1280 gawk_4.0.2.bb
1281 irssi_0.8.16-rc1.bb
1282 </literallayout></para></listitem>
1283 </itemizedlist>
1284 </section>
1285
1286 <section id='new-recipe-running-a-build-on-the-recipe'>
1287 <title>Running a Build on the Recipe</title>
1288
1289 <para>
1290 Creating a new recipe is usually an iterative process that
1291 requires using BitBake to process the recipe multiple times in
1292 order to progressively discover and add information to the
1293 recipe.
1294 </para>
1295
1296 <para>
1297 Assuming you have sourced a build environment setup script (i.e.
1298 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1299 or
1300 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1301 and you are in the
1302 <link linkend='build-directory'>Build Directory</link>,
1303 use BitBake to process your recipe.
1304 All you need to provide is the
1305 <filename>&lt;basename&gt;</filename> of the recipe as described
1306 in the previous section:
1307 <literallayout class='monospaced'>
1308 $ bitbake &lt;basename&gt;
1309 </literallayout>
1310
1311 </para>
1312
1313 <para>
1314 During the build, the OpenEmbedded build system creates a
1315 temporary work directory for the recipe
1316 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1317 where it keeps extracted source files, log files, intermediate
1318 compilation and packaging files, and so forth.
1319 </para>
1320
1321 <para>
1322 The temporary work directory is constructed as follows and
1323 depends on several factors:
1324 <literallayout class='monospaced'>
1325 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1326 </literallayout>
1327 As an example, assume a Source Directory top-level folder named
1328 <filename>poky</filename>, a default Build Directory at
1329 <filename>poky/build</filename>, and a
1330 <filename>qemux86-poky-linux</filename> machine target system.
1331 Furthermore, suppose your recipe is named
1332 <filename>foo_1.3.0-r0.bb</filename>.
1333 In this case, the work directory the build system uses to
1334 build the package would be as follows:
1335 <literallayout class='monospaced'>
1336 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1337 </literallayout>
1338 Inside this directory you can find sub-directories such as
1339 <filename>image</filename>, <filename>packages-split</filename>,
1340 and <filename>temp</filename>.
1341 After the build, you can examine these to determine how well
1342 the build went.
1343 <note>
1344 You can find log files for each task in the recipe's
1345 <filename>temp</filename> directory (e.g.
1346 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1347 Log files are named <filename>log.&lt;taskname&gt;</filename>
1348 (e.g. <filename>log.do_configure</filename>,
1349 <filename>log.do_fetch</filename>, and
1350 <filename>log.do_compile</filename>).
1351 </note>
1352 </para>
1353
1354 <para>
1355 You can find more information about the build process in the
1356 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1357 chapter of the Yocto Project Reference Manual.
1358 </para>
1359
1360 <para>
1361 You can also reference the following variables in the
1362 Yocto Project Reference Manual's glossary for more information:
1363 <itemizedlist>
1364 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1365 The top-level build output directory</listitem>
1366 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1367 The target system identifier</listitem>
1368 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1369 The recipe name</listitem>
1370 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1371 The epoch - (if
1372 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1373 is not specified, which is usually the case for most
1374 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1375 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1376 The recipe version</listitem>
1377 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1378 The recipe revision</listitem>
1379 </itemizedlist>
1380 </para>
1381 </section>
1382
1383 <section id='new-recipe-fetching-code'>
1384 <title>Fetching Code</title>
1385
1386 <para>
1387 The first thing your recipe must do is specify how to fetch
1388 the source files.
1389 Fetching is controlled mainly through the
1390 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1391 variable.
1392 Your recipe must have a <filename>SRC_URI</filename> variable
1393 that points to where the source is located.
1394 For a graphical representation of source locations, see the
1395 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1396 section in the Yocto Project Reference Manual.
1397 </para>
1398
1399 <para>
1400 The <filename>do_fetch</filename> task uses the prefix of
1401 each entry in the <filename>SRC_URI</filename> variable value
1402 to determine what fetcher to use to get your source files.
1403 It is the <filename>SRC_URI</filename> variable that triggers
1404 the fetcher.
1405 The <filename>do_patch</filename> task uses the variable after
1406 source is fetched to apply patches.
1407 The OpenEmbedded build system uses
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1409 for scanning directory locations for local files in
1410 <filename>SRC_URI</filename>.
1411 </para>
1412
1413 <para>
1414 The <filename>SRC_URI</filename> variable in your recipe must
1415 define each unique location for your source files.
1416 It is good practice to not hard-code pathnames in an URL used
1417 in <filename>SRC_URI</filename>.
1418 Rather than hard-code these paths, use
1419 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1420 which causes the fetch process to use the version specified in
1421 the recipe filename.
1422 Specifying the version in this manner means that upgrading the
1423 recipe to a future version is as simple as renaming the recipe
1424 to match the new version.
1425 </para>
1426
1427 <para>
1428 Here is a simple example from the
1429 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
1430 recipe where the source comes from a single tarball.
1431 Notice the use of the
1432 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1433 variable:
1434 <literallayout class='monospaced'>
1435 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1436 </literallayout>
1437 </para>
1438
1439 <para>
1440 Files mentioned in <filename>SRC_URI</filename> whose names end
1441 in a typical archive extension (e.g. <filename>.tar</filename>,
1442 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1443 <filename>.zip</filename>, and so forth), are automatically
1444 extracted during the <filename>do_unpack</filename> task.
1445 For another example that specifies these types of files, see
1446 the
1447 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1448 section.
1449 </para>
1450
1451 <para>
1452 Another way of specifying source is from an SCM.
1453 For Git repositories, you must specify
1454 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1455 and you should specify
1456 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1457 to include the revision with
1458 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1459 Here is an example from the recipe
1460 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1461 <literallayout class='monospaced'>
1462 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1463
1464 PR = "r6"
1465 PV = "1.0.5+git${SRCPV}"
1466
1467 SRC_URI = "git://git.kernel.dk/blktrace.git \
1468 file://ldflags.patch"
1469 </literallayout>
1470 </para>
1471
1472 <para>
1473 If your <filename>SRC_URI</filename> statement includes
1474 URLs pointing to individual files fetched from a remote server
1475 other than a version control system, BitBake attempts to
1476 verify the files against checksums defined in your recipe to
1477 ensure they have not been tampered with or otherwise modified
1478 since the recipe was written.
1479 Two checksums are used:
1480 <filename>SRC_URI[md5sum]</filename> and
1481 <filename>SRC_URI[sha256sum]</filename>.
1482 </para>
1483
1484 <para>
1485 If your <filename>SRC_URI</filename> variable points to
1486 more than a single URL (excluding SCM URLs), you need to
1487 provide the <filename>md5</filename> and
1488 <filename>sha256</filename> checksums for each URL.
1489 For these cases, you provide a name for each URL as part of
1490 the <filename>SRC_URI</filename> and then reference that name
1491 in the subsequent checksum statements.
1492 Here is an example:
1493 <literallayout class='monospaced'>
1494 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1495 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1496
1497 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1498 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1499
1500 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1501 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1502 </literallayout>
1503 </para>
1504
1505 <para>
1506 To find these checksums, you can comment the statements out
1507 and then attempt to build the software.
1508 The build will produce an error for each missing checksum
1509 and as part of the error message provide the correct checksum
1510 string.
1511 Once you have the correct checksums, simply copy them into your
1512 recipe for a subsequent build.
1513 </para>
1514
1515 <para>
1516 This final example is a bit more complicated and is from the
1517 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1518 recipe.
1519 The example's <filename>SRC_URI</filename> statement identifies
1520 multiple files as the source files for the recipe: a tarball, a
1521 patch file, a desktop file, and an icon.
1522 <literallayout class='monospaced'>
1523 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1524 file://xwc.patch \
1525 file://rxvt.desktop \
1526 file://rxvt.png"
1527 </literallayout>
1528 </para>
1529
1530 <para>
1531 When you specify local files using the
1532 <filename>file://</filename> URI protocol, the build system
1533 fetches files from the local machine.
1534 The path is relative to the
1535 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1536 variable and searches specific directories in a certain order:
1537 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1538 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1539 and <filename>files</filename>.
1540 The directories are assumed to be subdirectories of the
1541 directory in which the recipe or append file resides.
1542 For another example that specifies these types of files, see the
1543 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1544 section.
1545 </para>
1546
1547 <para>
1548 The previous example also specifies a patch file.
1549 Patch files are files whose names end in
1550 <filename>.patch</filename> or <filename>.diff</filename>.
1551 The build system automatically applies patches as described
1552 in the
1553 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1554 </para>
1555 </section>
1556
1557 <section id='new-recipe-unpacking-code'>
1558 <title>Unpacking Code</title>
1559
1560 <para>
1561 During the build, the <filename>do_unpack</filename> task
1562 unpacks the source with
1563 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1564 pointing to where it is unpacked.
1565 </para>
1566
1567 <para>
1568 If you are fetching your source files from an upstream source
1569 archived tarball and the tarball's internal structure matches
1570 the common convention of a top-level subdirectory named
1571 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1572 then you do not need to set <filename>S</filename>.
1573 However, if <filename>SRC_URI</filename> specifies to fetch
1574 source from an archive that does not use this convention,
1575 or from an SCM like Git or Subversion, your recipe needs to
1576 define <filename>S</filename>.
1577 </para>
1578
1579 <para>
1580 If processing your recipe using BitBake successfully unpacks
1581 the source files, you need to be sure that the directory
1582 pointed to by <filename>${S}</filename> matches the structure
1583 of the source.
1584 </para>
1585 </section>
1586
1587 <section id='new-recipe-patching-code'>
1588 <title>Patching Code</title>
1589
1590 <para>
1591 Sometimes it is necessary to patch code after it has been
1592 fetched.
1593 Any files mentioned in <filename>SRC_URI</filename> whose
1594 names end in <filename>.patch</filename> or
1595 <filename>.diff</filename> are treated as patches.
1596 The <filename>do_patch</filename> task automatically applies
1597 these patches.
1598 </para>
1599
1600 <para>
1601 The build system should be able to apply patches with the "-p1"
1602 option (i.e. one directory level in the path will be stripped
1603 off).
1604 If your patch needs to have more directory levels stripped off,
1605 specify the number of levels using the "striplevel" option in
1606 the <filename>SRC_URI</filename> entry for the patch.
1607 Alternatively, if your patch needs to be applied in a specific
1608 subdirectory that is not specified in the patch file, use the
1609 "patchdir" option in the entry.
1610 </para>
1611 </section>
1612
1613 <section id='new-recipe-licensing'>
1614 <title>Licensing</title>
1615
1616 <para>
1617 Your recipe needs to have both the
1618 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1619 and
1620 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1621 variables:
1622 <itemizedlist>
1623 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1624 This variable specifies the license for the software.
1625 If you do not know the license under which the software
1626 you are building is distributed, you should go to the
1627 source code and look for that information.
1628 Typical files containing this information include
1629 <filename>COPYING</filename>,
1630 <filename>LICENSE</filename>, and
1631 <filename>README</filename> files.
1632 You could also find the information near the top of
1633 a source file.
1634 For example, given a piece of software licensed under
1635 the GNU General Public License version 2, you would
1636 set <filename>LICENSE</filename> as follows:
1637 <literallayout class='monospaced'>
1638 LICENSE = "GPLv2"
1639 </literallayout></para>
1640 <para>The licenses you specify within
1641 <filename>LICENSE</filename> can have any name as long
1642 as you do not use spaces, since spaces are used as
1643 separators between license names.
1644 For standard licenses, use the names of the files in
1645 <filename>meta/files/common-licenses/</filename>
1646 or the <filename>SPDXLICENSEMAP</filename> flag names
1647 defined in <filename>meta/conf/licenses.conf</filename>.
1648 </para></listitem>
1649 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1650 The OpenEmbedded build system uses this variable to
1651 make sure the license text has not changed.
1652 If it has, the build produces an error and it affords
1653 you the chance to figure it out and correct the problem.
1654 </para>
1655 <para>You need to specify all applicable licensing
1656 files for the software.
1657 At the end of the configuration step, the build process
1658 will compare the checksums of the files to be sure
1659 the text has not changed.
1660 Any differences result in an error with the message
1661 containing the current checksum.
1662 For more explanation and examples of how to set the
1663 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1664 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1665 section in the Yocto Project Reference Manual.</para>
1666 <para>To determine the correct checksum string, you
1667 can list the appropriate files in the
1668 <filename>LIC_FILES_CHKSUM</filename> variable with
1669 incorrect md5 strings, attempt to build the software,
1670 and then note the resulting error messages that will
1671 report the correct md5 strings.
1672 Here is an example that assumes the software has a
1673 <filename>COPYING</filename> file:
1674 <literallayout class='monospaced'>
1675 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
1676 </literallayout>
1677 When you try to build the software, the build system
1678 will produce an error and give you the correct string
1679 that you can substitute into the recipe file for a
1680 subsequent build.
1681 </para></listitem>
1682 </itemizedlist>
1683 </para>
1684
1685<!--
1686
1687 <para>
1688 For trying this out I created a new recipe named
1689 <filename>htop_1.0.2.bb</filename> and put it in
1690 <filename>poky/meta/recipes-extended/htop</filename>.
1691 There are two license type statements in my very simple
1692 recipe:
1693 <literallayout class='monospaced'>
1694 LICENSE = ""
1695
1696 LIC_FILES_CHKSUM = ""
1697
1698 SRC_URI[md5sum] = ""
1699 SRC_URI[sha256sum] = ""
1700 </literallayout>
1701 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
1702 Next, you delete or comment out the two <filename>SRC_URI</filename>
1703 lines at the end and then attempt to build the software with
1704 <filename>bitbake htop</filename>.
1705 Doing so causes BitBake to report some errors and and give
1706 you the actual strings you need for the last two
1707 <filename>SRC_URI</filename> lines.
1708 Prior to this, you have to dig around in the home page of the
1709 source for <filename>htop</filename> and determine that the
1710 software is released under GPLv2.
1711 You can provide that in the <filename>LICENSE</filename>
1712 statement.
1713 Now you edit your recipe to have those two strings for
1714 the <filename>SRC_URI</filename> statements:
1715 <literallayout class='monospaced'>
1716 LICENSE = "GPLv2"
1717
1718 LIC_FILES_CHKSUM = ""
1719
1720 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
1721 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
1722 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
1723 </literallayout>
1724 At this point, you can build the software again using the
1725 <filename>bitbake htop</filename> command.
1726 There is just a set of errors now associated with the
1727 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
1728 </para>
1729-->
1730
1731 </section>
1732
1733 <section id='new-recipe-configuring-the-recipe'>
1734 <title>Configuring the Recipe</title>
1735
1736 <para>
1737 Most software provides some means of setting build-time
1738 configuration options before compilation.
1739 Typically, setting these options is accomplished by running a
1740 configure script with some options, or by modifying a build
1741 configuration file.
1742 </para>
1743
1744 <para>
1745 A major part of build-time configuration is about checking for
1746 build-time dependencies and possibly enabling optional
1747 functionality as a result.
1748 You need to specify any build-time dependencies for the
1749 software you are building in your recipe's
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1751 value, in terms of other recipes that satisfy those
1752 dependencies.
1753 You can often find build-time or runtime
1754 dependencies described in the software's documentation.
1755 </para>
1756
1757 <para>
1758 The following list provides configuration items of note based
1759 on how your software is built:
1760 <itemizedlist>
1761 <listitem><para><emphasis>Autotools:</emphasis>
1762 If your source files have a
1763 <filename>configure.ac</filename> file, then your
1764 software is built using Autotools.
1765 If this is the case, you just need to worry about
1766 tweaking the configuration.</para>
1767 <para>When using Autotools, your recipe needs to inherit
1768 the
1769 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1770 class and your recipe does not have to contain a
1771 <filename>do_configure</filename> task.
1772 However, you might still want to make some adjustments.
1773 For example, you can set
1774 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1775 to pass any needed configure options that are specific
1776 to the recipe.</para></listitem>
1777 <listitem><para><emphasis>CMake:</emphasis>
1778 If your source files have a
1779 <filename>CMakeLists.txt</filename> file, then your
1780 software is built using CMake.
1781 If this is the case, you just need to worry about
1782 tweaking the configuration.</para>
1783 <para>When you use CMake, your recipe needs to inherit
1784 the
1785 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
1786 class and your recipe does not have to contain a
1787 <filename>do_configure</filename> task.
1788 You can make some adjustments by setting
1789 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1790 to pass any needed configure options that are specific
1791 to the recipe.</para></listitem>
1792 <listitem><para><emphasis>Other:</emphasis>
1793 If your source files do not have a
1794 <filename>configure.ac</filename> or
1795 <filename>CMakeLists.txt</filename> file, then your
1796 software is built using some method other than Autotools
1797 or CMake.
1798 If this is the case, you normally need to provide a
1799 <filename>do_configure</filename> task in your recipe
1800 unless, of course, there is nothing to configure.
1801 </para>
1802 <para>Even if your software is not being built by
1803 Autotools or CMake, you still might not need to deal
1804 with any configuration issues.
1805 You need to determine if configuration is even a required step.
1806 You might need to modify a Makefile or some configuration file
1807 used for the build to specify necessary build options.
1808 Or, perhaps you might need to run a provided, custom
1809 configure script with the appropriate options.</para>
1810 <para>For the case involving a custom configure
1811 script, you would run
1812 <filename>./configure --help</filename> and look for
1813 the options you need to set.</para></listitem>
1814 </itemizedlist>
1815 </para>
1816
1817 <para>
1818 Once configuration succeeds, it is always good practice to
1819 look at the <filename>log.do_configure</filename> file to
1820 ensure that the appropriate options have been enabled and no
1821 additional build-time dependencies need to be added to
1822 <filename>DEPENDS</filename>.
1823 For example, if the configure script reports that it found
1824 something not mentioned in <filename>DEPENDS</filename>, or
1825 that it did not find something that it needed for some
1826 desired optional functionality, then you would need to add
1827 those to <filename>DEPENDS</filename>.
1828 Looking at the log might also reveal items being checked for
1829 and/or enabled that you do not want, or items not being found
1830 that are in <filename>DEPENDS</filename>, in which case
1831 you would need to look at passing extra options to the
1832 configure script as needed.
1833 For reference information on configure options specific to the
1834 software you are building, you can consult the output of the
1835 <filename>./configure --help</filename> command within
1836 <filename>${S}</filename> or consult the software's upstream
1837 documentation.
1838 </para>
1839 </section>
1840
1841 <section id='new-recipe-compilation'>
1842 <title>Compilation</title>
1843
1844 <para>
1845 During a build, the <filename>do_compile</filename> task
1846 happens after source is fetched, unpacked, and configured.
1847 If the recipe passes through <filename>do_compile</filename>
1848 successfully, nothing needs to be done.
1849 </para>
1850
1851 <para>
1852 However, if the compile step fails, you need to diagnose the
1853 failure.
1854 Here are some common issues that cause failures:
1855 <itemizedlist>
1856 <listitem><para><emphasis>Parallel build failures:</emphasis>
1857 These failures manifest themselves as intermittent
1858 errors, or errors reporting that a file or directory
1859 that should be created by some other part of the build
1860 process could not be found.
1861 This type of failure can occur even if, upon inspection,
1862 the file or directory does exist after the build has
1863 failed, because that part of the build process happened
1864 in the wrong order.</para>
1865 <para>To fix the problem, you need to either satisfy
1866 the missing dependency in the Makefile or whatever
1867 script produced the Makefile, or (as a workaround)
1868 set
1869 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
1870 to an empty string:
1871 <literallayout class='monospaced'>
1872 PARALLEL_MAKE = ""
1873 </literallayout></para></listitem>
1874 <listitem><para><emphasis>Improper host path usage:</emphasis>
1875 This failure applies to recipes building for the target
1876 or <filename>nativesdk</filename> only.
1877 The failure occurs when the compilation process uses
1878 improper headers, libraries, or other files from the
1879 host system when cross-compiling for the target.
1880 </para>
1881 <para>To fix the problem, examine the
1882 <filename>log.do_compile</filename> file to identify
1883 the host paths being used (e.g.
1884 <filename>/usr/include</filename>,
1885 <filename>/usr/lib</filename>, and so forth) and then
1886 either add configure options, apply a patch, or do both.
1887 </para></listitem>
1888 <listitem><para><emphasis>Failure to find required
1889 libraries/headers:</emphasis>
1890 If a build-time dependency is missing because it has
1891 not been declared in
1892 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
1893 or because the dependency exists but the path used by
1894 the build process to find the file is incorrect and the
1895 configure step did not detect it, the compilation
1896 process could fail.
1897 For either of these failures, the compilation process
1898 notes that files could not be found.
1899 In these cases, you need to go back and add additional
1900 options to the configure script as well as possibly
1901 add additional build-time dependencies to
1902 <filename>DEPENDS</filename>.
1903 Occasionally, it is necessary to apply a patch to the
1904 source to ensure the correct paths are used.
1905 </para></listitem>
1906 </itemizedlist>
1907 </para>
1908 </section>
1909
1910 <section id='new-recipe-installing'>
1911 <title>Installing</title>
1912
1913 <para>
1914 During <filename>do_install</filename>, the task copies the
1915 built files along with their hierarchy to locations that
1916 would mirror their locations on the target device.
1917 The installation process copies files from the
1918 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
1919 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
1920 and
1921 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1922 directories to the
1923 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1924 directory to create the structure as it should appear on the
1925 target system.
1926 </para>
1927
1928 <para>
1929 How your software is built affects what you must do to be
1930 sure your software is installed correctly.
1931 The following list describes what you must do for installation
1932 depending on the type of build system used by the software
1933 being built:
1934 <itemizedlist>
1935 <listitem><para><emphasis>Autotools and CMake:</emphasis>
1936 If the software your recipe is building uses Autotools
1937 or CMake, the OpenEmbedded build
1938 system understands how to install the software.
1939 Consequently, you do not have to have a
1940 <filename>do_install</filename> task as part of your
1941 recipe.
1942 You just need to make sure the install portion of the
1943 build completes with no issues.
1944 However, if you wish to install additional files not
1945 already being installed by
1946 <filename>make install</filename>, you should do this
1947 using a <filename>do_install_append</filename> function
1948 using the install command as described in
1949 <emphasis>Manual</emphasis> later in this list.
1950 </para></listitem>
1951 <listitem><para><emphasis>Other (using
1952 <filename>make install</filename>):</emphasis>
1953 You need to define a
1954 <filename>do_install</filename> function in your
1955 recipe.
1956 The function should call
1957 <filename>oe_runmake install</filename> and will likely
1958 need to pass in the destination directory as well.
1959 How you pass that path is dependent on how the
1960 <filename>Makefile</filename> being run is written
1961 (e.g. <filename>DESTDIR=${D}</filename>,
1962 <filename>PREFIX=${D}</filename>,
1963 <filename>INSTALLROOT=${D}</filename>, and so forth).
1964 </para>
1965 <para>For an example recipe using
1966 <filename>make install</filename>, see the
1967 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
1968 section.</para></listitem>
1969 <listitem><para><emphasis>Manual:</emphasis>
1970 You need to define a
1971 <filename>do_install</filename> function in your
1972 recipe.
1973 The function must first use
1974 <filename>install -d</filename> to create the
1975 directories.
1976 Once the directories exist, your function can use
1977 <filename>install</filename> to manually install the
1978 built software into the directories.</para>
1979 <para>You can find more information on
1980 <filename>install</filename> at
1981 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
1982 </para></listitem>
1983 </itemizedlist>
1984 </para>
1985
1986 <para>
1987 For the scenarios that do not use Autotools or
1988 CMake, you need to track the installation
1989 and diagnose and fix any issues until everything installs
1990 correctly.
1991 You need to look in the default location of
1992 <filename>${D}</filename>, which is
1993 <filename>${WORKDIR}/image</filename>, to be sure your
1994 files have been installed correctly.
1995 </para>
1996
1997 <note>
1998 During the installation process, you might need to modify
1999 some of the installed files to suit the target layout.
2000 For example, you might need to replace hard-coded paths in an
2001 initscript with values of variables provided by the build
2002 system, such as replacing <filename>/usr/bin/</filename> with
2003 <filename>${bindir}</filename>.
2004 If you do perform such modifications during
2005 <filename>do_install</filename>, be sure to modify the
2006 destination file after copying rather than before copying.
2007 Modifying after copying ensures that the build system can
2008 re-execute <filename>do_install</filename> if needed.
2009 </note>
2010
2011 <note>
2012 <filename>oe_runmake install</filename>, which can be run
2013 directly or can be run indirectly by the
2014 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2015 and
2016 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2017 classes, runs <filename>make install</filename> in parallel.
2018 Sometimes, a Makefile can have missing dependencies between
2019 targets that can result in race conditions.
2020 If you experience intermittent failures during
2021 <filename>do_install</filename>, you might be able to work
2022 around them by disabling parallel Makefile installs
2023 by adding the following to the recipe:
2024 <literallayout class='monospaced'>
2025 PARALLEL_MAKEINST = ""
2026 </literallayout>
2027 See
2028 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2029 for additional information.
2030 </note>
2031 </section>
2032
2033 <section id='new-recipe-enabling-system-services'>
2034 <title>Enabling System Services</title>
2035
2036 <para>
2037 If you want to install a service, which is a process that
2038 usually starts on boot and runs in the background, then
2039 you must include some additional definitions in your recipe.
2040 </para>
2041
2042 <para>
2043 If you are adding services and the service initialization
2044 script or the service file itself is not installed, you must
2045 provide for that installation in your recipe using a
2046 <filename>do_install_append</filename> function.
2047 If your recipe already has a <filename>do_install</filename>
2048 function, update the function near its end rather than
2049 adding an additional <filename>do_install_append</filename>
2050 function.
2051 </para>
2052
2053 <para>
2054 When you create the installation for your services, you need
2055 to accomplish what is normally done by
2056 <filename>make install</filename>.
2057 In other words, make sure your installation arranges the output
2058 similar to how it is arranged on the target system.
2059 </para>
2060
2061 <para>
2062 The OpenEmbedded build system provides support for starting
2063 services two different ways:
2064 <itemizedlist>
2065 <listitem><para><emphasis>SysVinit:</emphasis>
2066 SysVinit is a system and service manager that
2067 manages the init system used to control the very basic
2068 functions of your system.
2069 The init program is the first program
2070 started by the Linux kernel when the system boots.
2071 Init then controls the startup, running and shutdown
2072 of all other programs.</para>
2073 <para>To enable a service using SysVinit, your recipe
2074 needs to inherit the
2075 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2076 class.
2077 The class helps facilitate safely installing the
2078 package on the target.</para>
2079 <para>You will need to set the
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2081 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2082 and
2083 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2084 variables within your recipe.</para></listitem>
2085 <listitem><para><emphasis>systemd:</emphasis>
2086 System Management Daemon (systemd) was designed to
2087 replace SysVinit and to provide
2088 enhanced management of services.
2089 For more information on systemd, see the systemd
2090 homepage at
2091 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2092 </para>
2093 <para>To enable a service using systemd, your recipe
2094 needs to inherit the
2095 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2096 class.
2097 See the <filename>systemd.class</filename> file
2098 located in your
2099 <link linkend='source-directory'>Source Directory</link>.
2100 section for more information.
2101 </para></listitem>
2102 </itemizedlist>
2103 </para>
2104 </section>
2105
2106 <section id='new-recipe-packaging'>
2107 <title>Packaging</title>
2108
2109 <para>
2110 The <filename>do_package</filename> task splits the files
2111 produced by the recipe into logical components.
2112 Even software that produces a single binary might still have
2113 debug symbols, documentation, and other logical components
2114 that should be split out.
2115 The <filename>do_package</filename> task ensures that files
2116 are split up and packaged correctly.
2117 </para>
2118
2119 <para>
2120 After you build your software, you need to be sure your packages
2121 are correct.
2122 Examine the
2123 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2124 directory and make sure files are where you expect them to be.
2125 </para>
2126
2127 <para>
2128 If you discover problems, you can set
2129 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2130 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2131 <filename>do_install(_append)</filename>, and so forth as
2132 needed.
2133 </para>
2134
2135 <para>
2136 See the
2137 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2138 section for an example that shows how you might split
2139 your software into more than one package.
2140 </para>
2141
2142 <para>
2143 For an example showing how to install a post-installation
2144 script, see the
2145 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2146 section.
2147 </para>
2148 </section>
2149
2150 <section id='properly-versioning-pre-release-recipes'>
2151 <title>Properly Versioning Pre-Release Recipes</title>
2152
2153 <para>
2154 Sometimes the name of a recipe can lead to versioning
2155 problems when the recipe is upgraded to a final release.
2156 For example, consider the
2157 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2158 the list of example recipes in the
2159 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2160 section.
2161 This recipe is at a release candidate stage (i.e.
2162 "rc1").
2163 When the recipe is released, the recipe filename becomes
2164 <filename>irssi_0.8.16.bb</filename>.
2165 The version change from <filename>0.8.16-rc1</filename>
2166 to <filename>0.8.16</filename> is seen as a decrease by the
2167 build system and package managers, so the resulting packages
2168 will not correctly trigger an upgrade.
2169 </para>
2170
2171 <para>
2172 In order to ensure the versions compare properly, the
2173 recommended convention is to set
2174 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2175 within the recipe to
2176 "&lt;previous version&gt;+&lt;current version&gt;".
2177 You can use an additional variable so that you can use the
2178 current version elsewhere.
2179 Here is an example:
2180 <literallayout class='monospaced'>
2181 REALPV = "0.8.16-rc1"
2182 PV = "0.8.15+${REALPV}"
2183 </literallayout>
2184 </para>
2185 </section>
2186
2187 <section id='new-recipe-post-installation-scripts'>
2188 <title>Post-Installation Scripts</title>
2189
2190 <para>
2191 Post-installation scripts run immediately after installing
2192 a package on the target, or during image creation when a
2193 package is included in an image.
2194 To add a post-installation script to a package, add a
2195 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2196 the recipe file (<filename>.bb</filename>) and use
2197 <filename>PACKAGENAME</filename> as the name of the package
2198 you want to attach to the <filename>postinst</filename>
2199 script.
2200 To apply the post-installation script to the main package
2201 for the recipe, which is usually what is required, specify
2202 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2203 in place of <filename>PACKAGENAME</filename>.
2204 </para>
2205
2206 <para>
2207 A post-installation function has the following structure:
2208 <literallayout class='monospaced'>
2209 pkg_postinst_PACKAGENAME () {
2210 #!/bin/sh -e
2211 # Commands to carry out
2212 }
2213 </literallayout>
2214 </para>
2215
2216 <para>
2217 The script defined in the post-installation function is
2218 called when the root filesystem is created.
2219 If the script succeeds, the package is marked as installed.
2220 If the script fails, the package is marked as unpacked and
2221 the script is executed when the image boots again.
2222 </para>
2223
2224 <para>
2225 Sometimes it is necessary for the execution of a
2226 post-installation script to be delayed until the first boot.
2227 For example, the script might need to be executed on the
2228 device itself.
2229 To delay script execution until boot time, use the following
2230 structure in the post-installation script:
2231 <literallayout class='monospaced'>
2232 pkg_postinst_PACKAGENAME () {
2233 #!/bin/sh -e
2234 if [ x"$D" = "x" ]; then
2235 # Actions to carry out on the device go here
2236 else
2237 exit 1
2238 fi
2239 }
2240 </literallayout>
2241 </para>
2242
2243 <para>
2244 The previous example delays execution until the image boots
2245 again because the
2246 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2247 variable points to the directory containing the image when
2248 the root filesystem is created at build time but is unset
2249 when executed on the first boot.
2250 </para>
2251
2252 <note>
2253 Equivalent support for pre-install, pre-uninstall, and
2254 post-uninstall scripts exist by way of
2255 <filename>pkg_preinst</filename>,
2256 <filename>pkg_prerm</filename>, and
2257 <filename>pkg_postrm</filename>, respectively.
2258 These scrips work in exactly the same way as does
2259 <filename>pkg_postinst</filename> with the exception that they
2260 run at different times.
2261 Also, because of when they run, they are not applicable to
2262 being run at image creation time like
2263 <filename>pkg_postinst</filename>.
2264 </note>
2265 </section>
2266
2267 <section id='new-recipe-testing'>
2268 <title>Testing</title>
2269
2270 <para>
2271 The final step for completing your recipe is to be sure that
2272 the software you built runs correctly.
2273 To accomplish runtime testing, add the build's output
2274 packages to your image and test them on the target.
2275 </para>
2276
2277 <para>
2278 For information on how to customize your image by adding
2279 specific packages, see the
2280 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2281 section.
2282 </para>
2283 </section>
2284
2285 <section id='new-recipe-testing-examples'>
2286 <title>Examples</title>
2287
2288 <para>
2289 To help summarize how to write a recipe, this section provides
2290 some examples given various scenarios:
2291 <itemizedlist>
2292 <listitem><para>Recipes that use local files</para></listitem>
2293 <listitem><para>Using an Autotooled package</para></listitem>
2294 <listitem><para>Using a Makefile-based package</para></listitem>
2295 <listitem><para>Splitting an application into multiple packages</para></listitem>
2296 </itemizedlist>
2297 </para>
2298
2299 <section id='new-recipe-single-c-file-package-hello-world'>
2300 <title>Single .c File Package (Hello World!)</title>
2301
2302 <para>
2303 Building an application from a single file that is stored
2304 locally (e.g. under <filename>files/</filename>) requires
2305 a recipe that has the file listed in the
2306 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2307 variable.
2308 Additionally, you need to manually write the
2309 <filename>do_compile</filename> and
2310 <filename>do_install</filename> tasks.
2311 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2312 variable defines the directory containing the source code,
2313 which is set to
2314 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2315 in this case - the directory BitBake uses for the build.
2316 <literallayout class='monospaced'>
2317 SUMMARY = "Simple helloworld application"
2318 SECTION = "examples"
2319 LICENSE = "MIT"
2320 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2321
2322 SRC_URI = "file://helloworld.c"
2323
2324 S = "${WORKDIR}"
2325
2326 do_compile() {
2327 ${CC} helloworld.c -o helloworld
2328 }
2329
2330 do_install() {
2331 install -d ${D}${bindir}
2332 install -m 0755 helloworld ${D}${bindir}
2333 }
2334 </literallayout>
2335 </para>
2336
2337 <para>
2338 By default, the <filename>helloworld</filename>,
2339 <filename>helloworld-dbg</filename>, and
2340 <filename>helloworld-dev</filename> packages are built.
2341 For information on how to customize the packaging process,
2342 see the
2343 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2344 section.
2345 </para>
2346 </section>
2347
2348 <section id='new-recipe-autotooled-package'>
2349 <title>Autotooled Package</title>
2350 <para>
2351 Applications that use Autotools such as <filename>autoconf</filename> and
2352 <filename>automake</filename> require a recipe that has a source archive listed in
2353 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2354 also inherit the
2355 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2356 class, which contains the definitions of all the steps
2357 needed to build an Autotool-based application.
2358 The result of the build is automatically packaged.
2359 And, if the application uses NLS for localization, packages with local information are
2360 generated (one package per language).
2361 Following is one example: (<filename>hello_2.3.bb</filename>)
2362 <literallayout class='monospaced'>
2363 SUMMARY = "GNU Helloworld application"
2364 SECTION = "examples"
2365 LICENSE = "GPLv2+"
2366 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2367
2368 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2369
2370 inherit autotools gettext
2371 </literallayout>
2372 </para>
2373
2374 <para>
2375 The variable
2376 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2377 is used to track source license changes as described in the
2378 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2379 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2380 </para>
2381 </section>
2382
2383 <section id='new-recipe-makefile-based-package'>
2384 <title>Makefile-Based Package</title>
2385
2386 <para>
2387 Applications that use GNU <filename>make</filename> also require a recipe that has
2388 the source archive listed in
2389 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2390 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2391 starts the <filename>make</filename> command to compile the application.
2392 If you need additional <filename>make</filename> options, you should store them in the
2393 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2394 variable.
2395 BitBake passes these options into the <filename>make</filename> GNU invocation.
2396 Note that a <filename>do_install</filename> task is still required.
2397 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2398 </para>
2399
2400 <para>
2401 Some applications might require extra parameters to be passed to the compiler.
2402 For example, the application might need an additional header path.
2403 You can accomplish this by adding to the
2404 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2405 The following example shows this:
2406 <literallayout class='monospaced'>
2407 CFLAGS_prepend = "-I ${S}/include "
2408 </literallayout>
2409 </para>
2410
2411 <para>
2412 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2413 <literallayout class='monospaced'>
2414 SUMMARY = "Tools for managing memory technology devices."
2415 SECTION = "base"
2416 DEPENDS = "zlib lzo e2fsprogs util-linux"
2417 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2418 LICENSE = "GPLv2+"
2419 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2420 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2421
2422 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2423 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2424
2425 S = "${WORKDIR}/git/"
2426
2427 PR = "r1"
2428
2429 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2430 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2431
2432 do_install () {
2433 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2434 INCLUDEDIR=${includedir}
2435 install -d ${D}${includedir}/mtd/
2436 for f in ${S}/include/mtd/*.h; do
2437 install -m 0644 $f ${D}${includedir}/mtd/
2438 done
2439 }
2440
2441 PARALLEL_MAKE = ""
2442
2443 BBCLASSEXTEND = "native"
2444 </literallayout>
2445 </para>
2446 </section>
2447
2448 <section id='splitting-an-application-into-multiple-packages'>
2449 <title>Splitting an Application into Multiple Packages</title>
2450
2451 <para>
2452 You can use the variables
2453 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2454 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2455 to split an application into multiple packages.
2456 </para>
2457
2458 <para>
2459 Following is an example that uses the <filename>libxpm</filename> recipe.
2460 By default, this recipe generates a single package that contains the library along
2461 with a few binaries.
2462 You can modify the recipe to split the binaries into separate packages:
2463 <literallayout class='monospaced'>
2464 require xorg-lib-common.inc
2465
2466 SUMMARY = "X11 Pixmap library"
2467 LICENSE = "X-BSD"
2468 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2469 DEPENDS += "libxext libsm libxt"
2470 PR = "r3"
2471 PE = "1"
2472
2473 XORG_PN = "libXpm"
2474
2475 PACKAGES =+ "sxpm cxpm"
2476 FILES_cxpm = "${bindir}/cxpm"
2477 FILES_sxpm = "${bindir}/sxpm"
2478 </literallayout>
2479 </para>
2480
2481 <para>
2482 In the previous example, we want to ship the <filename>sxpm</filename>
2483 and <filename>cxpm</filename> binaries in separate packages.
2484 Since <filename>bindir</filename> would be packaged into the main
2485 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2486 package by default, we prepend the <filename>PACKAGES</filename>
2487 variable so additional package names are added to the start of list.
2488 This results in the extra <filename>FILES_*</filename>
2489 variables then containing information that define which files and
2490 directories go into which packages.
2491 Files included by earlier packages are skipped by latter packages.
2492 Thus, the main <filename>PN</filename> package
2493 does not include the above listed files.
2494 </para>
2495 </section>
2496 </section>
2497 </section>
2498
2499 <section id="platdev-newmachine">
2500 <title>Adding a New Machine</title>
2501
2502 <para>
2503 Adding a new machine to the Yocto Project is a straight forward
2504 process.
2505 This section describes how to add machines that are similar
2506 to those that the Yocto Project already supports.
2507 <note>
2508 Although well within the capabilities of the Yocto Project,
2509 adding a totally new architecture might require
2510 changes to <filename>gcc/eglibc</filename> and to the site
2511 information, which is beyond the scope of this manual.
2512 </note>
2513 </para>
2514
2515 <para>
2516 For a complete example that shows how to add a new machine,
2517 see the
2518 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
2519 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
2520 </para>
2521
2522 <section id="platdev-newmachine-conffile">
2523 <title>Adding the Machine Configuration File</title>
2524
2525 <para>
2526 To add a new machine, you need to add a new machine
2527 configuration file to the layer's
2528 <filename>conf/machine</filename> directory.
2529 This configuration file provides details about the device
2530 you are adding.
2531 </para>
2532
2533 <para>
2534 The OpenEmbedded build system uses the root name of the
2535 machine configuration file to reference the new machine.
2536 For example, given a machine configuration file named
2537 <filename>crownbay.conf</filename>, the build system
2538 recognizes the machine as "crownbay".
2539 </para>
2540
2541 <para>
2542 The most important variables you must set in your machine
2543 configuration file are as follows:
2544 <itemizedlist>
2545 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
2546 (e.g. "arm")</para></listitem>
2547 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
2548 (see below)</para></listitem>
2549 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
2550 (e.g. "apm screen wifi")</para></listitem>
2551 </itemizedlist>
2552 </para>
2553
2554 <para>
2555 You might also need these variables:
2556 <itemizedlist>
2557 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
2558 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
2559 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
2560 (e.g. "zImage")</para></listitem>
2561 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
2562 (e.g. "tar.gz jffs2")</para></listitem>
2563 </itemizedlist>
2564 </para>
2565
2566 <para>
2567 You can find full details on these variables in the reference
2568 section.
2569 You can leverage existing machine <filename>.conf</filename>
2570 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
2571 </para>
2572 </section>
2573
2574 <section id="platdev-newmachine-kernel">
2575 <title>Adding a Kernel for the Machine</title>
2576
2577 <para>
2578 The OpenEmbedded build system needs to be able to build a kernel
2579 for the machine.
2580 You need to either create a new kernel recipe for this machine,
2581 or extend an existing kernel recipe.
2582 You can find several kernel recipe examples in the
2583 Source Directory at
2584 <filename>meta/recipes-kernel/linux</filename>
2585 that you can use as references.
2586 </para>
2587
2588 <para>
2589 If you are creating a new kernel recipe, normal recipe-writing
2590 rules apply for setting up a
2591 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2592 Thus, you need to specify any necessary patches and set
2593 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2594 to point at the source code.
2595 You need to create a <filename>do_configure</filename> task that
2596 configures the unpacked kernel with a
2597 <filename>defconfig</filename> file.
2598 You can do this by using a <filename>make defconfig</filename>
2599 command or, more commonly, by copying in a suitable
2600 <filename>defconfig</filename> file and then running
2601 <filename>make oldconfig</filename>.
2602 By making use of <filename>inherit kernel</filename> and
2603 potentially some of the <filename>linux-*.inc</filename> files,
2604 most other functionality is centralized and the defaults of the
2605 class normally work well.
2606 </para>
2607
2608 <para>
2609 If you are extending an existing kernel recipe, it is usually
2610 a matter of adding a suitable <filename>defconfig</filename>
2611 file.
2612 The file needs to be added into a location similar to
2613 <filename>defconfig</filename> files used for other machines
2614 in a given kernel recipe.
2615 A possible way to do this is by listing the file in the
2616 <filename>SRC_URI</filename> and adding the machine to the
2617 expression in
2618 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
2619 <literallayout class='monospaced'>
2620 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2621 </literallayout>
2622 </para>
2623 </section>
2624
2625 <section id="platdev-newmachine-formfactor">
2626 <title>Adding a Formfactor Configuration File</title>
2627
2628 <para>
2629 A formfactor configuration file provides information about the
2630 target hardware for which the image is being built and information that
2631 the build system cannot obtain from other sources such as the kernel.
2632 Some examples of information contained in a formfactor configuration file include
2633 framebuffer orientation, whether or not the system has a keyboard,
2634 the positioning of the keyboard in relation to the screen, and
2635 the screen resolution.
2636 </para>
2637
2638 <para>
2639 The build system uses reasonable defaults in most cases.
2640 However, if customization is
2641 necessary, you need to create a <filename>machconfig</filename> file
2642 in the <filename>meta/recipes-bsp/formfactor/files</filename>
2643 directory.
2644 This directory contains directories for specific machines such as
2645 <filename>qemuarm</filename> and <filename>qemux86</filename>.
2646 For information about the settings available and the defaults, see the
2647 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
2648 same area.
2649 </para>
2650
2651 <para>
2652 Following is an example for "qemuarm" machine:
2653 <literallayout class='monospaced'>
2654 HAVE_TOUCHSCREEN=1
2655 HAVE_KEYBOARD=1
2656
2657 DISPLAY_CAN_ROTATE=0
2658 DISPLAY_ORIENTATION=0
2659 #DISPLAY_WIDTH_PIXELS=640
2660 #DISPLAY_HEIGHT_PIXELS=480
2661 #DISPLAY_BPP=16
2662 DISPLAY_DPI=150
2663 DISPLAY_SUBPIXEL_ORDER=vrgb
2664 </literallayout>
2665 </para>
2666 </section>
2667 </section>
2668
2669 <section id="platdev-working-with-libraries">
2670 <title>Working With Libraries</title>
2671
2672 <para>
2673 Libraries are an integral part of your system.
2674 This section describes some common practices you might find
2675 helpful when working with libraries to build your system:
2676 <itemizedlist>
2677 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
2678 </para></listitem>
2679 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
2680 </para></listitem>
2681 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
2682 </para></listitem>
2683 </itemizedlist>
2684 </para>
2685
2686 <section id='including-static-library-files'>
2687 <title>Including Static Library Files</title>
2688
2689 <para>
2690 If you are building a library and the library offers static linking, you can control
2691 which static library files (<filename>*.a</filename> files) get included in the
2692 built library.
2693 </para>
2694
2695 <para>
2696 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
2697 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
2698 variables in the
2699 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
2700 by the <filename>do_install</filename> task are packaged.
2701 By default, the <filename>PACKAGES</filename> variable contains
2702 <filename>${PN}-staticdev</filename>, which includes all static library files.
2703 <note>
2704 Some previously released versions of the Yocto Project
2705 defined the static library files through
2706 <filename>${PN}-dev</filename>.
2707 </note>
2708 Following, is part of the BitBake configuration file.
2709 You can see where the static library files are defined:
2710 <literallayout class='monospaced'>
2711 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
2712 PACKAGES_DYNAMIC = "${PN}-locale-*"
2713 FILES = ""
2714
2715 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
2716 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
2717 ${base_bindir}/* ${base_sbindir}/* \
2718 ${base_libdir}/*${SOLIBS} \
2719 ${datadir}/${BPN} ${libdir}/${BPN}/* \
2720 ${datadir}/pixmaps ${datadir}/applications \
2721 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
2722 ${libdir}/bonobo/servers"
2723
2724 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
2725 ${datadir}/gnome/help"
2726 SECTION_${PN}-doc = "doc"
2727
2728 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
2729 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
2730 ${datadir}/aclocal ${base_libdir}/*.o"
2731 SECTION_${PN}-dev = "devel"
2732 ALLOW_EMPTY_${PN}-dev = "1"
2733 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
2734
2735 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
2736 SECTION_${PN}-staticdev = "devel"
2737 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
2738 </literallayout>
2739 </para>
2740 </section>
2741
2742 <section id="combining-multiple-versions-library-files-into-one-image">
2743 <title>Combining Multiple Versions of Library Files into One Image</title>
2744
2745 <para>
2746 The build system offers the ability to build libraries with different
2747 target optimizations or architecture formats and combine these together
2748 into one system image.
2749 You can link different binaries in the image
2750 against the different libraries as needed for specific use cases.
2751 This feature is called "Multilib."
2752 </para>
2753
2754 <para>
2755 An example would be where you have most of a system compiled in 32-bit
2756 mode using 32-bit libraries, but you have something large, like a database
2757 engine, that needs to be a 64-bit application and uses 64-bit libraries.
2758 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
2759 </para>
2760
2761 <para>
2762 While the Multilib feature is most commonly used for 32 and 64-bit differences,
2763 the approach the build system uses facilitates different target optimizations.
2764 You could compile some binaries to use one set of libraries and other binaries
2765 to use other different sets of libraries.
2766 The libraries could differ in architecture, compiler options, or other
2767 optimizations.
2768 </para>
2769
2770 <para>
2771 This section overviews the Multilib process only.
2772 For more details on how to implement Multilib, see the
2773 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
2774 page.
2775 </para>
2776
2777 <para>
2778 Aside from this wiki page, several examples exist in the
2779 <filename>meta-skeleton</filename> layer found in the
2780 <link linkend='source-directory'>Source Directory</link>:
2781 <itemizedlist>
2782 <listitem><para><filename>conf/multilib-example.conf</filename>
2783 configuration file</para></listitem>
2784 <listitem><para><filename>conf/multilib-example2.conf</filename>
2785 configuration file</para></listitem>
2786 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
2787 recipe</para></listitem>
2788 </itemizedlist>
2789 </para>
2790
2791 <section id='preparing-to-use-multilib'>
2792 <title>Preparing to Use Multilib</title>
2793
2794 <para>
2795 User-specific requirements drive the Multilib feature.
2796 Consequently, there is no one "out-of-the-box" configuration that likely
2797 exists to meet your needs.
2798 </para>
2799
2800 <para>
2801 In order to enable Multilib, you first need to ensure your recipe is
2802 extended to support multiple libraries.
2803 Many standard recipes are already extended and support multiple libraries.
2804 You can check in the <filename>meta/conf/multilib.conf</filename>
2805 configuration file in the
2806 <link linkend='source-directory'>Source Directory</link> to see how this is
2807 done using the
2808 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
2809 variable.
2810 Eventually, all recipes will be covered and this list will
2811 not be needed.
2812 </para>
2813
2814 <para>
2815 For the most part, the Multilib class extension works automatically to
2816 extend the package name from <filename>${PN}</filename> to
2817 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
2818 is the particular multilib (e.g. "lib32-" or "lib64-").
2819 Standard variables such as
2820 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2821 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
2822 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
2823 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
2824 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2825 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
2826 If you are extending any manual code in the recipe, you can use the
2827 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
2828 correctly.
2829 This automatic extension code resides in <filename>multilib.bbclass</filename>.
2830 </para>
2831 </section>
2832
2833 <section id='using-multilib'>
2834 <title>Using Multilib</title>
2835
2836 <para>
2837 After you have set up the recipes, you need to define the actual
2838 combination of multiple libraries you want to build.
2839 You accomplish this through your <filename>local.conf</filename>
2840 configuration file in the
2841 <link linkend='build-directory'>Build Directory</link>.
2842 An example configuration would be as follows:
2843 <literallayout class='monospaced'>
2844 MACHINE = "qemux86-64"
2845 require conf/multilib.conf
2846 MULTILIBS = "multilib:lib32"
2847 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
2848 IMAGE_INSTALL = "lib32-connman"
2849 </literallayout>
2850 This example enables an
2851 additional library named <filename>lib32</filename> alongside the
2852 normal target packages.
2853 When combining these "lib32" alternatives, the example uses "x86" for tuning.
2854 For information on this particular tuning, see
2855 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
2856 </para>
2857
2858 <para>
2859 The example then includes <filename>lib32-connman</filename>
2860 in all the images, which illustrates one method of including a
2861 multiple library dependency.
2862 You can use a normal image build to include this dependency,
2863 for example:
2864 <literallayout class='monospaced'>
2865 $ bitbake core-image-sato
2866 </literallayout>
2867 You can also build Multilib packages specifically with a command like this:
2868 <literallayout class='monospaced'>
2869 $ bitbake lib32-connman
2870 </literallayout>
2871 </para>
2872 </section>
2873
2874 <section id='additional-implementation-details'>
2875 <title>Additional Implementation Details</title>
2876
2877 <para>
2878 Different packaging systems have different levels of native Multilib
2879 support.
2880 For the RPM Package Management System, the following implementation details
2881 exist:
2882 <itemizedlist>
2883 <listitem><para>A unique architecture is defined for the Multilib packages,
2884 along with creating a unique deploy folder under
2885 <filename>tmp/deploy/rpm</filename> in the
2886 <link linkend='build-directory'>Build Directory</link>.
2887 For example, consider <filename>lib32</filename> in a
2888 <filename>qemux86-64</filename> image.
2889 The possible architectures in the system are "all", "qemux86_64",
2890 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
2891 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
2892 <filename>${PN}</filename> during RPM packaging.
2893 The naming for a normal RPM package and a Multilib RPM package in a
2894 <filename>qemux86-64</filename> system resolves to something similar to
2895 <filename>bash-4.1-r2.x86_64.rpm</filename> and
2896 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
2897 </para></listitem>
2898 <listitem><para>When installing a Multilib image, the RPM backend first
2899 installs the base image and then installs the Multilib libraries.
2900 </para></listitem>
2901 <listitem><para>The build system relies on RPM to resolve the identical files in the
2902 two (or more) Multilib packages.</para></listitem>
2903 </itemizedlist>
2904 </para>
2905
2906 <para>
2907 For the IPK Package Management System, the following implementation details exist:
2908 <itemizedlist>
2909 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
2910 <filename>${PN}</filename> during IPK packaging.
2911 The naming for a normal RPM package and a Multilib IPK package in a
2912 <filename>qemux86-64</filename> system resolves to something like
2913 <filename>bash_4.1-r2.x86_64.ipk</filename> and
2914 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
2915 </para></listitem>
2916 <listitem><para>The IPK deploy folder is not modified with
2917 <filename>${MLPREFIX}</filename> because packages with and without
2918 the Multilib feature can exist in the same folder due to the
2919 <filename>${PN}</filename> differences.</para></listitem>
2920 <listitem><para>IPK defines a sanity check for Multilib installation
2921 using certain rules for file comparison, overridden, etc.
2922 </para></listitem>
2923 </itemizedlist>
2924 </para>
2925 </section>
2926 </section>
2927
2928 <section id='installing-multiple-versions-of-the-same-library'>
2929 <title>Installing Multiple Versions of the Same Library</title>
2930
2931 <para>
2932 Situations can exist where you need to install and use
2933 multiple versions of the same library on the same system
2934 at the same time.
2935 These situations almost always exist when a library API
2936 changes and you have multiple pieces of software that
2937 depend on the separate versions of the library.
2938 To accommodate these situations, you can install multiple
2939 versions of the same library in parallel on the same system.
2940 </para>
2941
2942 <para>
2943 The process is straight forward as long as the libraries use
2944 proper versioning.
2945 With properly versioned libraries, all you need to do to
2946 individually specify the libraries is create separate,
2947 appropriately named recipes where the
2948 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
2949 name includes a portion that differentiates each library version
2950 (e.g.the major part of the version number).
2951 Thus, instead of having a single recipe that loads one version
2952 of a library (e.g. <filename>clutter</filename>), you provide
2953 multiple recipes that result in different versions
2954 of the libraries you want.
2955 As an example, the following two recipes would allow the
2956 two separate versions of the <filename>clutter</filename>
2957 library to co-exist on the same system:
2958 <literallayout class='monospaced'>
2959 clutter-1.6_1.6.20.bb
2960 clutter-1.8_1.8.4.bb
2961 </literallayout>
2962 Additionally, if you have other recipes that depend on a given
2963 library, you need to use the
2964 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2965 variable to create the dependency.
2966 Continuing with the same example, if you want to have a recipe
2967 depend on the 1.8 version of the <filename>clutter</filename>
2968 library, use the following in your recipe:
2969 <literallayout class='monospaced'>
2970 DEPENDS = "clutter-1.8"
2971 </literallayout>
2972 </para>
2973 </section>
2974 </section>
2975
2976 <section id='configuring-the-kernel'>
2977 <title>Configuring the Kernel</title>
2978
2979 <para>
2980 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
2981 file has all the right information in it for the image you are building.
2982 You can use the <filename>menuconfig</filename> tool and configuration fragments to
2983 make sure your <filename>.config</filename> file is just how you need it.
2984 This section describes how to use <filename>menuconfig</filename>, create and use
2985 configuration fragments, and how to interactively tweak your <filename>.config</filename>
2986 file to create the leanest kernel configuration file possible.
2987 </para>
2988
2989 <para>
2990 For more information on kernel configuration, see the
2991 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
2992 section in the Yocto Project Linux Kernel Development Manual.
2993 </para>
2994
2995 <section id='using-menuconfig'>
2996 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
2997
2998 <para>
2999 The easiest way to define kernel configurations is to set them through the
3000 <filename>menuconfig</filename> tool.
3001 This tool provides an interactive method with which
3002 to set kernel configurations.
3003 For general information on <filename>menuconfig</filename>, see
3004 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
3005 </para>
3006
3007 <para>
3008 To use the <filename>menuconfig</filename> tool in the Yocto Project development
3009 environment, you must launch it using BitBake.
3010 Thus, the environment must be set up using the
3011 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3012 or
3013 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
3014 script found in the
3015 <link linkend='build-directory'>Build Directory</link>.
3016 The following commands run <filename>menuconfig</filename> assuming the
3017 <link linkend='source-directory'>Source Directory</link>
3018 top-level folder is <filename>~/poky</filename>:
3019 <literallayout class='monospaced'>
3020 $ cd poky
3021 $ source oe-init-build-env
3022 $ bitbake linux-yocto -c menuconfig
3023 </literallayout>
3024 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
3025 interactively examine and configure all the kernel configuration parameters.
3026 After making your changes, simply exit the tool and save your changes to
3027 create an updated version of the <filename>.config</filename> configuration file.
3028 </para>
3029
3030 <para>
3031 Consider an example that configures the <filename>linux-yocto-3.14</filename>
3032 kernel.
3033 The OpenEmbedded build system recognizes this kernel as
3034 <filename>linux-yocto</filename>.
3035 Thus, the following commands from the shell in which you previously sourced the
3036 environment initialization script cleans the shared state cache and the
3037 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
3038 directory and then runs <filename>menuconfig</filename>:
3039 <literallayout class='monospaced'>
3040 $ bitbake linux-yocto -c menuconfig
3041 </literallayout>
3042 </para>
3043
3044 <para>
3045 Once <filename>menuconfig</filename> launches, use the interface
3046 to navigate through the selections to find the configuration settings in
3047 which you are interested.
3048 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
3049 You can find it at <filename>Processor Type and Features</filename> under
3050 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
3051 After highlighting the selection, use the arrow keys to select or deselect
3052 the setting.
3053 When you are finished with all your selections, exit out and save them.
3054 </para>
3055
3056 <para>
3057 Saving the selections updates the <filename>.config</filename> configuration file.
3058 This is the file that the OpenEmbedded build system uses to configure the
3059 kernel during the build.
3060 You can find and examine this file in the Build Directory in
3061 <filename>tmp/work/</filename>.
3062 The actual <filename>.config</filename> is located in the area where the
3063 specific kernel is built.
3064 For example, if you were building a Linux Yocto kernel based on the
3065 Linux 3.14 kernel and you were building a QEMU image targeted for
3066 <filename>x86</filename> architecture, the
3067 <filename>.config</filename> file would be located here:
3068 <literallayout class='monospaced'>
3069 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
3070 ...656ed30-r1/linux-qemux86-standard-build
3071 </literallayout>
3072 <note>
3073 The previous example directory is artificially split and many of the characters
3074 in the actual filename are omitted in order to make it more readable.
3075 Also, depending on the kernel you are using, the exact pathname
3076 for <filename>linux-yocto-3.14...</filename> might differ.
3077 </note>
3078 </para>
3079
3080 <para>
3081 Within the <filename>.config</filename> file, you can see the kernel settings.
3082 For example, the following entry shows that symmetric multi-processor support
3083 is not set:
3084 <literallayout class='monospaced'>
3085 # CONFIG_SMP is not set
3086 </literallayout>
3087 </para>
3088
3089 <para>
3090 A good method to isolate changed configurations is to use a combination of the
3091 <filename>menuconfig</filename> tool and simple shell commands.
3092 Before changing configurations with <filename>menuconfig</filename>, copy the
3093 existing <filename>.config</filename> and rename it to something else,
3094 use <filename>menuconfig</filename> to make
3095 as many changes as you want and save them, then compare the renamed configuration
3096 file against the newly created file.
3097 You can use the resulting differences as your base to create configuration fragments
3098 to permanently save in your kernel layer.
3099 <note>
3100 Be sure to make a copy of the <filename>.config</filename> and don't just
3101 rename it.
3102 The build system needs an existing <filename>.config</filename>
3103 from which to work.
3104 </note>
3105 </para>
3106 </section>
3107
3108 <section id='creating-config-fragments'>
3109 <title>Creating Configuration Fragments</title>
3110
3111 <para>
3112 Configuration fragments are simply kernel options that appear in a file
3113 placed where the OpenEmbedded build system can find and apply them.
3114 Syntactically, the configuration statement is identical to what would appear
3115 in the <filename>.config</filename> file, which is in the
3116 <link linkend='build-directory'>Build Directory</link> in
3117 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
3118 </para>
3119
3120 <para>
3121 It is simple to create a configuration fragment.
3122 For example, issuing the following from the shell creates a configuration fragment
3123 file named <filename>my_smp.cfg</filename> that enables multi-processor support
3124 within the kernel:
3125 <literallayout class='monospaced'>
3126 $ echo "CONFIG_SMP=y" >> my_smp.cfg
3127 </literallayout>
3128 <note>
3129 All configuration files must use the <filename>.cfg</filename> extension in order
3130 for the OpenEmbedded build system to recognize them as a configuration fragment.
3131 </note>
3132 </para>
3133
3134 <para>
3135 Where do you put your configuration files?
3136 You can place these configuration files in the same area pointed to by
3137 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3138 The OpenEmbedded build system will pick up the configuration and add it to the
3139 kernel's configuration.
3140 For example, suppose you had a set of configuration options in a file called
3141 <filename>myconfig.cfg</filename>.
3142 If you put that file inside a directory named <filename>linux-yocto</filename>
3143 that resides in the same directory as the kernel's append file and then add
3144 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
3145 those configuration options will be picked up and applied when the kernel is built.
3146 <literallayout class='monospaced'>
3147 SRC_URI += "file://myconfig.cfg"
3148 </literallayout>
3149 </para>
3150
3151 <para>
3152 As mentioned earlier, you can group related configurations into multiple files and
3153 name them all in the <filename>SRC_URI</filename> statement as well.
3154 For example, you could group separate configurations specifically for Ethernet and graphics
3155 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
3156 following in your append file:
3157 <literallayout class='monospaced'>
3158 SRC_URI += "file://myconfig.cfg \
3159 file://eth.cfg \
3160 file://gfx.cfg"
3161 </literallayout>
3162 </para>
3163 </section>
3164
3165 <section id='fine-tuning-the-kernel-configuration-file'>
3166 <title>Fine-Tuning the Kernel Configuration File</title>
3167
3168 <para>
3169 You can make sure the <filename>.config</filename> file is as lean or efficient as
3170 possible by reading the output of the kernel configuration fragment audit,
3171 noting any issues, making changes to correct the issues, and then repeating.
3172 </para>
3173
3174 <para>
3175 As part of the kernel build process, the
3176 <filename>kernel_configcheck</filename> task runs.
3177 This task validates the kernel configuration by checking the final
3178 <filename>.config</filename> file against the input files.
3179 During the check, the task produces warning messages for the following
3180 issues:
3181 <itemizedlist>
3182 <listitem><para>Requested options that did not make the final
3183 <filename>.config</filename> file.</para></listitem>
3184 <listitem><para>Configuration items that appear twice in the same
3185 configuration fragment.</para></listitem>
3186 <listitem><para>Configuration items tagged as "required" that were overridden.
3187 </para></listitem>
3188 <listitem><para>A board overrides a non-board specific option.</para></listitem>
3189 <listitem><para>Listed options not valid for the kernel being processed.
3190 In other words, the option does not appear anywhere.</para></listitem>
3191 </itemizedlist>
3192 <note>
3193 The <filename>kernel_configcheck</filename> task can also optionally report
3194 if an option is overridden during processing.
3195 </note>
3196 </para>
3197
3198 <para>
3199 For each output warning, a message points to the file
3200 that contains a list of the options and a pointer to the config
3201 fragment that defines them.
3202 Collectively, the files are the key to streamlining the configuration.
3203 </para>
3204
3205 <para>
3206 To streamline the configuration, do the following:
3207 <orderedlist>
3208 <listitem><para>Start with a full configuration that you know
3209 works - it builds and boots successfully.
3210 This configuration file will be your baseline.</para></listitem>
3211 <listitem><para>Separately run the <filename>configme</filename> and
3212 <filename>kernel_configcheck</filename> tasks.</para></listitem>
3213 <listitem><para>Take the resulting list of files from the
3214 <filename>kernel_configcheck</filename> task warnings and do the following:
3215 <itemizedlist>
3216 <listitem><para>Drop values that are redefined in the fragment but do not
3217 change the final <filename>.config</filename> file.</para></listitem>
3218 <listitem><para>Analyze and potentially drop values from the
3219 <filename>.config</filename> file that override required
3220 configurations.</para></listitem>
3221 <listitem><para>Analyze and potentially remove non-board specific options.
3222 </para></listitem>
3223 <listitem><para>Remove repeated and invalid options.</para></listitem>
3224 </itemizedlist></para></listitem>
3225 <listitem><para>After you have worked through the output of the kernel configuration
3226 audit, you can re-run the <filename>configme</filename>
3227 and <filename>kernel_configcheck</filename> tasks to see the results of your
3228 changes.
3229 If you have more issues, you can deal with them as described in the
3230 previous step.</para></listitem>
3231 </orderedlist>
3232 </para>
3233
3234 <para>
3235 Iteratively working through steps two through four eventually yields
3236 a minimal, streamlined configuration file.
3237 Once you have the best <filename>.config</filename>, you can build the Linux
3238 Yocto kernel.
3239 </para>
3240 </section>
3241 </section>
3242
3243 <section id="patching-the-kernel">
3244 <title>Patching the Kernel</title>
3245
3246 <para>
3247 Patching the kernel involves changing or adding configurations to an existing kernel,
3248 changing or adding recipes to the kernel that are needed to support specific hardware features,
3249 or even altering the source code itself.
3250 <note>
3251 You can use the <filename>yocto-kernel</filename> script
3252 found in the <link linkend='source-directory'>Source Directory</link>
3253 under <filename>scripts</filename> to manage kernel patches and configuration.
3254 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
3255 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
3256 more information.</note>
3257 </para>
3258
3259 <para>
3260 This example creates a simple patch by adding some QEMU emulator console
3261 output at boot time through <filename>printk</filename> statements in the kernel's
3262 <filename>calibrate.c</filename> source code file.
3263 Applying the patch and booting the modified image causes the added
3264 messages to appear on the emulator's console.
3265 </para>
3266
3267 <para>
3268 The example assumes a clean build exists for the <filename>qemux86</filename>
3269 machine in a
3270 <link linkend='source-directory'>Source Directory</link>
3271 named <filename>poky</filename>.
3272 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
3273 <filename>build</filename> and is located in <filename>poky</filename> and
3274 the kernel is based on the Linux 3.4 kernel.
3275 For general information on how to configure the most efficient build, see the
3276 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
3277 in the Yocto Project Quick Start.
3278 </para>
3279
3280 <para>
3281 Also, for more information on patching the kernel, see the
3282 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
3283 section in the Yocto Project Linux Kernel Development Manual.
3284 </para>
3285
3286 <section id='create-a-layer-for-your-changes'>
3287 <title>Create a Layer for your Changes</title>
3288
3289 <para>
3290 The first step is to create a layer so you can isolate your
3291 changes.
3292 Rather than use the <filename>yocto-layer</filename> script
3293 to create the layer, this example steps through the process
3294 by hand.
3295 If you want information on the script that creates a general
3296 layer, see the
3297 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3298 section.
3299 </para>
3300
3301 <para>
3302 These two commands create a directory you can use for your
3303 layer:
3304 <literallayout class='monospaced'>
3305 $ cd ~/poky
3306 $ mkdir meta-mylayer
3307 </literallayout>
3308 Creating a directory that follows the Yocto Project layer naming
3309 conventions sets up the layer for your changes.
3310 The layer is where you place your configuration files, append
3311 files, and patch files.
3312 To learn more about creating a layer and filling it with the
3313 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
3314 and Creating Layers</link>" section.
3315 </para>
3316 </section>
3317
3318 <section id='finding-the-kernel-source-code'>
3319 <title>Finding the Kernel Source Code</title>
3320
3321 <para>
3322 Each time you build a kernel image, the kernel source code is fetched
3323 and unpacked into the following directory:
3324 <literallayout class='monospaced'>
3325 ${S}/linux
3326 </literallayout>
3327 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
3328 section and the
3329 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
3330 for more information about where source is kept during a build.
3331 </para>
3332
3333 <para>
3334 For this example, we are going to patch the
3335 <filename>init/calibrate.c</filename> file
3336 by adding some simple console <filename>printk</filename> statements that we can
3337 see when we boot the image using QEMU.
3338 </para>
3339 </section>
3340
3341 <section id='creating-the-patch'>
3342 <title>Creating the Patch</title>
3343
3344 <para>
3345 Two methods exist by which you can create the patch:
3346 <link linkend='using-a-git-workflow'>Git workflow</link> and
3347 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
3348 For kernel patches, the Git workflow is more appropriate.
3349 This section assumes the Git workflow and shows the steps specific to
3350 this example.
3351 <orderedlist>
3352 <listitem><para><emphasis>Change the working directory</emphasis>:
3353 Change to where the kernel source code is before making
3354 your edits to the <filename>calibrate.c</filename> file:
3355 <literallayout class='monospaced'>
3356 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
3357 </literallayout>
3358 Because you are working in an established Git repository,
3359 you must be in this directory in order to commit your changes
3360 and create the patch file.
3361 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
3362 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
3363 represent the version and revision for the
3364 <filename>linux-yocto</filename> recipe.
3365 The <filename>PV</filename> variable includes the Git meta and machine
3366 hashes, which make the directory name longer than you might
3367 expect.
3368 </note></para></listitem>
3369 <listitem><para><emphasis>Edit the source file</emphasis>:
3370 Edit the <filename>init/calibrate.c</filename> file to have the
3371 following changes:
3372 <literallayout class='monospaced'>
3373 void calibrate_delay(void)
3374 {
3375 unsigned long lpj;
3376 static bool printed;
3377 int this_cpu = smp_processor_id();
3378
3379 printk("*************************************\n");
3380 printk("* *\n");
3381 printk("* HELLO YOCTO KERNEL *\n");
3382 printk("* *\n");
3383 printk("*************************************\n");
3384
3385 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
3386 .
3387 .
3388 .
3389 </literallayout></para></listitem>
3390 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
3391 These Git commands display the modified file, stage it, and then
3392 commit the file:
3393 <literallayout class='monospaced'>
3394 $ git status
3395 $ git add init/calibrate.c
3396 $ git commit -m "calibrate: Add printk example"
3397 </literallayout></para></listitem>
3398 <listitem><para><emphasis>Generate the patch file</emphasis>:
3399 This Git command creates the a patch file named
3400 <filename>0001-calibrate-Add-printk-example.patch</filename>
3401 in the current directory.
3402 <literallayout class='monospaced'>
3403 $ git format-patch -1
3404 </literallayout>
3405 </para></listitem>
3406 </orderedlist>
3407 </para>
3408 </section>
3409
3410 <section id='set-up-your-layer-for-the-build'>
3411 <title>Set Up Your Layer for the Build</title>
3412
3413 <para>These steps get your layer set up for the build:
3414 <orderedlist>
3415 <listitem><para><emphasis>Create additional structure</emphasis>:
3416 Create the additional layer structure:
3417 <literallayout class='monospaced'>
3418 $ cd ~/poky/meta-mylayer
3419 $ mkdir conf
3420 $ mkdir recipes-kernel
3421 $ mkdir recipes-kernel/linux
3422 $ mkdir recipes-kernel/linux/linux-yocto
3423 </literallayout>
3424 The <filename>conf</filename> directory holds your configuration files, while the
3425 <filename>recipes-kernel</filename> directory holds your append file and
3426 your patch file.</para></listitem>
3427 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
3428 Move to the <filename>meta-mylayer/conf</filename> directory and create
3429 the <filename>layer.conf</filename> file as follows:
3430 <literallayout class='monospaced'>
3431 # We have a conf and classes directory, add to BBPATH
3432 BBPATH .= ":${LAYERDIR}"
3433
3434 # We have recipes-* directories, add to BBFILES
3435 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
3436 ${LAYERDIR}/recipes-*/*/*.bbappend"
3437
3438 BBFILE_COLLECTIONS += "mylayer"
3439 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
3440 BBFILE_PRIORITY_mylayer = "5"
3441 </literallayout>
3442 Notice <filename>mylayer</filename> as part of the last three
3443 statements.</para></listitem>
3444 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
3445 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
3446 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
3447 <literallayout class='monospaced'>
3448 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3449
3450 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
3451 </literallayout>
3452 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
3453 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
3454 statements enable the OpenEmbedded build system to find the patch file.
3455 For more information on using append files, see the
3456 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3457 section.
3458 </para></listitem>
3459 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
3460 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
3461 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
3462 directory.</para></listitem>
3463 </orderedlist>
3464 </para>
3465 </section>
3466
3467 <section id='set-up-for-the-build'>
3468 <title>Set Up for the Build</title>
3469
3470 <para>
3471 Do the following to make sure the build parameters are set up for the example.
3472 Once you set up these build parameters, they do not have to change unless you
3473 change the target architecture of the machine you are building:
3474 <itemizedlist>
3475 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
3476 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3477 definition within the <filename>local.conf</filename> file in the
3478 <link linkend='build-directory'>Build Directory</link>
3479 specifies the target architecture used when building the Linux kernel.
3480 By default, <filename>MACHINE</filename> is set to
3481 <filename>qemux86</filename>, which specifies a 32-bit
3482 <trademark class='registered'>Intel</trademark> Architecture
3483 target machine suitable for the QEMU emulator.</para></listitem>
3484 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
3485 layer:</emphasis> The
3486 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
3487 variable in the
3488 <filename>bblayers.conf</filename> file found in the
3489 <filename>poky/build/conf</filename> directory needs to have the path to your local
3490 <filename>meta-mylayer</filename> layer.
3491 By default, the <filename>BBLAYERS</filename> variable contains paths to
3492 <filename>meta</filename>, <filename>meta-yocto</filename>, and
3493 <filename>meta-yocto-bsp</filename> in the
3494 <filename>poky</filename> Git repository.
3495 Add the path to your <filename>meta-mylayer</filename> location:
3496 <literallayout class='monospaced'>
3497 BBLAYERS ?= " \
3498 $HOME/poky/meta \
3499 $HOME/poky/meta-yocto \
3500 $HOME/poky/meta-yocto-bsp \
3501 $HOME/poky/meta-mylayer \
3502 "
3503
3504 BBLAYERS_NON_REMOVABLE ?= " \
3505 $HOME/poky/meta \
3506 $HOME/poky/meta-yocto \
3507 "
3508 </literallayout></para></listitem>
3509 </itemizedlist>
3510 </para>
3511 </section>
3512
3513 <section id='build-the-modified-qemu-kernel-image'>
3514 <title>Build the Modified QEMU Kernel Image</title>
3515
3516 <para>
3517 The following steps build your modified kernel image:
3518 <orderedlist>
3519 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
3520 Your environment should be set up since you previously sourced
3521 the
3522 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3523 script.
3524 If it is not, source the script again from <filename>poky</filename>.
3525 <literallayout class='monospaced'>
3526 $ cd ~/poky
3527 $ source &OE_INIT_FILE;
3528 </literallayout>
3529 </para></listitem>
3530 <listitem><para><emphasis>Clean up</emphasis>:
3531 Be sure to clean the shared state out by running the
3532 <filename>cleansstate</filename> BitBake task as follows from your Build Directory:
3533 <literallayout class='monospaced'>
3534 $ bitbake -c cleansstate linux-yocto
3535 </literallayout></para>
3536 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
3537 directory inside the
3538 <link linkend='build-directory'>Build Directory</link>.
3539 Always use the various BitBake clean tasks to clear out previous
3540 build artifacts.
3541 </note></para></listitem>
3542 <listitem><para><emphasis>Build the image</emphasis>:
3543 Next, build the kernel image using this command:
3544 <literallayout class='monospaced'>
3545 $ bitbake -k linux-yocto
3546 </literallayout></para></listitem>
3547 </orderedlist>
3548 </para>
3549 </section>
3550
3551 <section id='boot-the-image-and-verify-your-changes'>
3552 <title>Boot the Image and Verify Your Changes</title>
3553
3554 <para>
3555 These steps boot the image and allow you to see the changes
3556 <orderedlist>
3557 <listitem><para><emphasis>Boot the image</emphasis>:
3558 Boot the modified image in the QEMU emulator
3559 using this command:
3560 <literallayout class='monospaced'>
3561 $ runqemu qemux86
3562 </literallayout></para></listitem>
3563 <listitem><para><emphasis>Verify the changes</emphasis>:
3564 Log into the machine using <filename>root</filename> with no password and then
3565 use the following shell command to scroll through the console's boot output.
3566 <literallayout class='monospaced'>
3567 # dmesg | less
3568 </literallayout>
3569 You should see the results of your <filename>printk</filename> statements
3570 as part of the output.</para></listitem>
3571 </orderedlist>
3572 </para>
3573 </section>
3574 </section>
3575
3576 <section id='making-images-more-secure'>
3577 <title>Making Images More Secure</title>
3578
3579 <para>
3580 Security is of increasing concern for embedded devices.
3581 Consider the issues and problems discussed in just this
3582 sampling of work found across the Internet:
3583 <itemizedlist>
3584 <listitem><para><emphasis>
3585 "<ulink url='https://www.schneier.com/blog/archives/2014/01/security_risks_9.html'>Security Risks of Embedded Systems</ulink>"</emphasis>
3586 by Bruce Schneier
3587 </para></listitem>
3588 <listitem><para><emphasis>
3589 "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
3590 by Carna Botnet</para></listitem>
3591 <listitem><para><emphasis>
3592 "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
3593 by Jake Edge
3594 </para></listitem>
3595 <listitem><para><emphasis>
3596 "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security
3597Gateways via their Web Interfaces</ulink>"</emphasis>
3598 by Ben Williams
3599 </para></listitem>
3600 </itemizedlist>
3601 </para>
3602
3603 <para>
3604 When securing your image is of concern, there are steps, tools,
3605 and variables that you can consider to help you reach the
3606 security goals you need for your particular device.
3607 Not all situations are identical when it comes to making an
3608 image secure.
3609 Consequently, this section provides some guidance and suggestions
3610 for consideration when you want to make your image more secure.
3611 <note>
3612 Because the security requirements and risks are
3613 different for every type of device, this section cannot
3614 provide a complete reference on securing your custom OS.
3615 It is strongly recommended that you also consult other sources
3616 of information on embedded Linux system hardening and on
3617 security.
3618 </note>
3619 </para>
3620
3621 <section id='general-considerations'>
3622 <title>General Considerations</title>
3623
3624 <para>
3625 General considerations exist that help you create more
3626 secure images.
3627 You should consider the following suggestions to help
3628 make your device more secure:
3629 <itemizedlist>
3630 <listitem><para>
3631 Scan additional code you are adding to the system
3632 (e.g. application code) by using static analysis
3633 tools.
3634 Look for buffer overflows and other potential
3635 security problems.
3636 </para></listitem>
3637 <listitem><para>
3638 Pay particular attention to to the security for
3639 any web-based administration interface.
3640 </para>
3641 <para>Web interfaces typically need to perform
3642 administrative functions and tend to need to run with
3643 elevated privileges.
3644 Thus, the consequences resulting from the interface's
3645 security becoming compromised can be serious.
3646 Look for common web vulnerabilities such as
3647 cross-site-scripting (XSS), unvalidated inputs,
3648 and so forth.</para>
3649 <para>As with system passwords, the default credentials
3650 for accessing a web-based interface should not be the
3651 same across all devices.
3652 This is particularly true if the interface is enabled
3653 by default as it can be assumed that many end-users
3654 will not change the credentials.
3655 </para></listitem>
3656 <listitem><para>
3657 Ensure you can update the software on the device to
3658 mitigate vulnerabilities discovered in the future.
3659 This consideration especially applies when your
3660 device is network-enabled.
3661 </para></listitem>
3662 <listitem><para>
3663 Ensure you remove or disable debugging functionality
3664 before producing the final image.
3665 For information on how to do this, see the
3666 "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>"
3667 section.
3668 </para></listitem>
3669 <listitem><para>
3670 Ensure you have no network services listening that
3671 are not needed.
3672 </para></listitem>
3673 <listitem><para>
3674 Remove any software from the image that is not needed.
3675 </para></listitem>
3676 <listitem><para>
3677 Enable hardware support for secure boot functionality
3678 when your device supports this functionality.
3679 </para></listitem>
3680 </itemizedlist>
3681 </para>
3682 </section>
3683
3684 <section id='security-flags'>
3685 <title>Security Flags</title>
3686
3687 <para>
3688 The Yocto Project has security flags that you can enable that
3689 help make your build output more secure.
3690 The security flags are in the
3691 <filename>meta/conf/distro/include/security_flags.inc</filename>
3692 file in your
3693 <link linkend='source-directory'>Source Directory</link>
3694 (e.g. <filename>poky</filename>).
3695 <note>
3696 Depending on the recipe, certain security flags are enabled
3697 and disabled by default.
3698 </note>
3699 </para>
3700
3701 <para>
3702<!--
3703 The GCC/LD flags in <filename>security_flags.inc</filename>
3704 enable more secure code generation.
3705 By including the <filename>security_flags.inc</filename>
3706 file, you enable flags to the compiler and linker that cause
3707 them to generate more secure code.
3708 <note>
3709 The GCC/LD flags are enabled by default in the
3710 <filename>poky-lsb</filename> distribution.
3711 </note>
3712-->
3713 Use the following line in your
3714 <filename>local.conf</filename> file or in your custom
3715 distribution configuration file to enable the security
3716 compiler and linker flags to your build:
3717 <literallayout class='monospaced'>
3718 require conf/distro/include/security_flags.inc
3719 </literallayout>
3720 </para>
3721 </section>
3722
3723 <section id='considerations-specific-to-the-openembedded-build-system'>
3724 <title>Considerations Specific to the OpenEmbedded Build System</title>
3725
3726 <para>
3727 You can take some steps that are specific to the
3728 OpenEmbedded build system to make your images more secure:
3729 <itemizedlist>
3730 <listitem><para>
3731 Ensure "debug-tweaks" is not listed with
3732 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>.
3733 The default is to enable "debug-tweaks" by adding it
3734 to
3735 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
3736 in <filename>local.conf</filename>.
3737 However, you should comment out the variable or be
3738 sure that it does not have "debug-tweaks" before
3739 producing your final image.
3740 Among other things, leaving this in place sets the
3741 root password as blank, which makes logging in for
3742 debugging or inspection easy during
3743 development but also means anyone can easily log in
3744 during production.
3745 </para></listitem>
3746 <listitem><para>
3747 It is possible to set a root password for the image
3748 and also to set passwords for any extra users you might
3749 add (e.g. administrative or service type users).
3750 When you set up passwords for multiple images or
3751 users, you should not duplicate passwords.
3752 </para>
3753 <para>
3754 To set up passwords, use the
3755 <filename>extrausers</filename> class, which is the
3756 preferred method.
3757 For an example on how to set up both root and user
3758 passwords, see the
3759 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>"
3760 section.
3761 <note>
3762 When adding extra user accounts or setting a
3763 root password, be cautious about setting the
3764 same password on every device.
3765 If you do this, and the password you have set
3766 is exposed, then every device is now potentially
3767 compromised.
3768 If you need this access but want to ensure
3769 security, consider setting a different,
3770 random password for each device.
3771 Typically, you do this as a separate step after
3772 you deploy the image onto the device.
3773 </note>
3774 </para></listitem>
3775 <listitem><para>
3776 Consider enabling a Mandatory Access Control (MAC)
3777 framework (such as SMACK or SELinux) and tuning it
3778 appropriately for your device's usage.
3779 You can find more information in the
3780 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/'><filename>meta-selinux</filename></ulink>
3781 layer.
3782 </para></listitem>
3783 </itemizedlist>
3784 </para>
3785
3786 <para>
3787 </para>
3788 </section>
3789
3790 <section id='tools-for-hardening-your-image'>
3791 <title>Tools for Hardening Your Image</title>
3792
3793 <para>
3794 The Yocto Project provides tools for making your image
3795 more secure.
3796 You can find these tools in the
3797 <filename>meta-security</filename> layer of the
3798 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
3799 </para>
3800 </section>
3801 </section>
3802
3803 <section id='creating-your-own-distribution'>
3804 <title>Creating Your Own Distribution</title>
3805
3806 <para>
3807 When you build an image using the Yocto Project and
3808 do not alter any distribution
3809 <link linkend='metadata'>Metadata</link>, you are creating a
3810 Poky distribution.
3811 If you wish to gain more control over package alternative
3812 selections, compile-time options, and other low-level
3813 configurations, you can create your own distribution.
3814 </para>
3815
3816 <para>
3817 To create your own distribution, the basic steps consist of
3818 creating your own distribution layer, creating your own
3819 distribution configuration file, and then adding any needed
3820 code and Metadata to the layer.
3821 The following steps provide some more detail:
3822 <itemizedlist>
3823 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
3824 Create your distribution layer so that you can keep your
3825 Metadata and code for the distribution separate.
3826 It is strongly recommended that you create and use your own
3827 layer for configuration and code.
3828 Using your own layer as compared to just placing
3829 configurations in a <filename>local.conf</filename>
3830 configuration file makes it easier to reproduce the same
3831 build configuration when using multiple build machines.
3832 See the
3833 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3834 section for information on how to quickly set up a layer.
3835 </para></listitem>
3836 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
3837 The distribution configuration file needs to be created in
3838 the <filename>conf/distro</filename> directory of your
3839 layer.
3840 You need to name it using your distribution name
3841 (e.g. <filename>mydistro.conf</filename>).
3842 <note>
3843 The
3844 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3845 variable in your
3846 <filename>local.conf</filename> file determines the
3847 name of your distribution.
3848 </note></para>
3849 <para>You can split out parts of your configuration file
3850 into include files and then "require" them from within
3851 your distribution configuration file.
3852 Be sure to place the include files in the
3853 <filename>conf/distro/include</filename> directory of
3854 your layer.
3855 A common example usage of include files would be to
3856 separate out the selection of desired version and revisions
3857 for individual recipes.
3858</para>
3859 <para>Your configuration file needs to set the following
3860 required variables:
3861 <literallayout class='monospaced'>
3862 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
3863 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
3864 </literallayout>
3865 These following variables are optional and you typically
3866 set them from the distribution configuration file:
3867 <literallayout class='monospaced'>
3868 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3869 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
3870 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
3871 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
3872 </literallayout>
3873 <tip>
3874 If you want to base your distribution configuration file
3875 on the very basic configuration from OE-Core, you
3876 can use
3877 <filename>conf/distro/defaultsetup.conf</filename> as
3878 a reference and just include variables that differ
3879 as compared to <filename>defaultsetup.conf</filename>.
3880 Alternatively, you can create a distribution
3881 configuration file from scratch using the
3882 <filename>defaultsetup.conf</filename> file
3883 or configuration files from other distributions
3884 such as Poky or Angstrom as references.
3885 </tip></para></listitem>
3886 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
3887 Be sure to define any other variables for which you want to
3888 create a default or enforce as part of the distribution
3889 configuration.
3890 You can include nearly any variable from the
3891 <filename>local.conf</filename> file.
3892 The variables you use are not limited to the list in the
3893 previous bulleted item.</para></listitem>
3894 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
3895 In your <filename>local.conf</filename> file in the
3896 <link linkend='build-directory'>Build Directory</link>,
3897 set your
3898 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3899 variable to point to your distribution's configuration file.
3900 For example, if your distribution's configuration file is
3901 named <filename>mydistro.conf</filename>, then you point
3902 to it as follows:
3903 <literallayout class='monospaced'>
3904 DISTRO = "mydistro"
3905 </literallayout></para></listitem>
3906 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
3907 Use your layer to hold other information needed for the
3908 distribution:
3909 <itemizedlist>
3910 <listitem><para>Add recipes for installing
3911 distro-specific configuration files that are not
3912 already installed by another recipe.
3913 If you have distro-specific configuration files
3914 that are included by an existing recipe, you should
3915 add an append file (<filename>.bbappend</filename>)
3916 for those.
3917 For general information and recommendations
3918 on how to add recipes to your layer, see the
3919 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
3920 and
3921 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
3922 sections.</para></listitem>
3923 <listitem><para>Add any image recipes that are specific
3924 to your distribution.</para></listitem>
3925 <listitem><para>Add a <filename>psplash</filename>
3926 append file for a branded splash screen.
3927 For information on append files, see the
3928 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3929 section.</para></listitem>
3930 <listitem><para>Add any other append files to make
3931 custom changes that are specific to individual
3932 recipes.</para></listitem>
3933 </itemizedlist></para></listitem>
3934 </itemizedlist>
3935 </para>
3936 </section>
3937
3938 <section id='building-a-tiny-system'>
3939 <title>Building a Tiny System</title>
3940
3941 <para>
3942 Very small distributions have some significant advantages such
3943 as requiring less on-die or in-package memory (cheaper), better
3944 performance through efficient cache usage, lower power requirements
3945 due to less memory, faster boot times, and reduced development
3946 overhead.
3947 Some real-world examples where a very small distribution gives
3948 you distinct advantages are digital cameras, medical devices,
3949 and small headless systems.
3950 </para>
3951
3952 <para>
3953 This section presents information that shows you how you can
3954 trim your distribution to even smaller sizes than the
3955 <filename>poky-tiny</filename> distribution, which is around
3956 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
3957 </para>
3958
3959 <section id='tiny-system-overview'>
3960 <title>Overview</title>
3961
3962 <para>
3963 The following list presents the overall steps you need to
3964 consider and perform to create distributions with smaller
3965 root filesystems, achieve faster boot times, maintain your critical
3966 functionality, and avoid initial RAM disks:
3967 <itemizedlist>
3968 <listitem><para>
3969 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
3970 </para></listitem>
3971 <listitem><para>
3972 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
3973 </para></listitem>
3974 <listitem><para>
3975 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
3976 </para></listitem>
3977 <listitem><para>
3978 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
3979 </para></listitem>
3980 <listitem><para>
3981 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
3982 </para></listitem>
3983 <listitem><para>
3984 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
3985 </para></listitem>
3986 <listitem><para>
3987 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
3988 </para></listitem>
3989 </itemizedlist>
3990 </para>
3991 </section>
3992
3993 <section id='goals-and-guiding-principles'>
3994 <title>Goals and Guiding Principles</title>
3995
3996 <para>
3997 Before you can reach your destination, you need to know
3998 where you are going.
3999 Here is an example list that you can use as a guide when
4000 creating very small distributions:
4001 <itemizedlist>
4002 <listitem><para>Determine how much space you need
4003 (e.g. a kernel that is 1 Mbyte or less and
4004 a root filesystem that is 3 Mbytes or less).
4005 </para></listitem>
4006 <listitem><para>Find the areas that are currently
4007 taking 90% of the space and concentrate on reducing
4008 those areas.
4009 </para></listitem>
4010 <listitem><para>Do not create any difficult "hacks"
4011 to achieve your goals.</para></listitem>
4012 <listitem><para>Leverage the device-specific
4013 options.</para></listitem>
4014 <listitem><para>Work in a separate layer so that you
4015 keep changes isolated.
4016 For information on how to create layers, see
4017 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
4018 </para></listitem>
4019 </itemizedlist>
4020 </para>
4021 </section>
4022
4023 <section id='understand-what-gives-your-image-size'>
4024 <title>Understand What Contributes to Your Image Size</title>
4025
4026 <para>
4027 It is easiest to have something to start with when creating
4028 your own distribution.
4029 You can use the Yocto Project out-of-the-box to create the
4030 <filename>poky-tiny</filename> distribution.
4031 Ultimately, you will want to make changes in your own
4032 distribution that are likely modeled after
4033 <filename>poky-tiny</filename>.
4034 <note>
4035 To use <filename>poky-tiny</filename> in your build,
4036 set the
4037 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
4038 variable in your
4039 <filename>local.conf</filename> file to "poky-tiny"
4040 as described in the
4041 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
4042 section.
4043 </note>
4044 </para>
4045
4046 <para>
4047 Understanding some memory concepts will help you reduce the
4048 system size.
4049 Memory consists of static, dynamic, and temporary memory.
4050 Static memory is the TEXT (code), DATA (initialized data
4051 in the code), and BSS (uninitialized data) sections.
4052 Dynamic memory represents memory that is allocated at runtime:
4053 stacks, hash tables, and so forth.
4054 Temporary memory is recovered after the boot process.
4055 This memory consists of memory used for decompressing
4056 the kernel and for the <filename>__init__</filename>
4057 functions.
4058 </para>
4059
4060 <para>
4061 To help you see where you currently are with kernel and root
4062 filesystem sizes, you can use two tools found in the
4063 <link linkend='source-directory'>Source Directory</link> in
4064 the <filename>scripts/tiny/</filename> directory:
4065 <itemizedlist>
4066 <listitem><para><filename>ksize.py</filename>: Reports
4067 component sizes for the kernel build objects.
4068 </para></listitem>
4069 <listitem><para><filename>dirsize.py</filename>: Reports
4070 component sizes for the root filesystem.</para></listitem>
4071 </itemizedlist>
4072 This next tool and command help you organize configuration
4073 fragments and view file dependencies in a human-readable form:
4074 <itemizedlist>
4075 <listitem><para><filename>merge_config.sh</filename>:
4076 Helps you manage configuration files and fragments
4077 within the kernel.
4078 With this tool, you can merge individual configuration
4079 fragments together.
4080 The tool allows you to make overrides and warns you
4081 of any missing configuration options.
4082 The tool is ideal for allowing you to iterate on
4083 configurations, create minimal configurations, and
4084 create configuration files for different machines
4085 without having to duplicate your process.</para>
4086 <para>The <filename>merge_config.sh</filename> script is
4087 part of the Linux Yocto kernel Git repositories
4088 (i.e. <filename>linux-yocto-3.14</filename>,
4089 <filename>linux-yocto-3.10</filename>,
4090 <filename>linux-yocto-3.8</filename>, and so forth)
4091 in the
4092 <filename>scripts/kconfig</filename> directory.</para>
4093 <para>For more information on configuration fragments,
4094 see the
4095 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
4096 section of the Yocto Project Linux Kernel Development
4097 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
4098 section, which is in this manual.</para></listitem>
4099 <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
4100 Using the BitBake command with these options brings up
4101 a Dependency Explorer from which you can view file
4102 dependencies.
4103 Understanding these dependencies allows you to make
4104 informed decisions when cutting out various pieces of the
4105 kernel and root filesystem.</para></listitem>
4106 </itemizedlist>
4107 </para>
4108 </section>
4109
4110 <section id='trim-the-root-filesystem'>
4111 <title>Trim the Root Filesystem</title>
4112
4113 <para>
4114 The root filesystem is made up of packages for booting,
4115 libraries, and applications.
4116 To change things, you can configure how the packaging happens,
4117 which changes the way you build them.
4118 You can also tweak the filesystem itself or select a different
4119 filesystem.
4120 </para>
4121
4122 <para>
4123 First, find out what is hogging your root filesystem by running the
4124 <filename>dirsize.py</filename> script from your root directory:
4125 <literallayout class='monospaced'>
4126 $ cd &lt;root-directory-of-image&gt;
4127 $ dirsize.py 100000 > dirsize-100k.log
4128 $ cat dirsize-100k.log
4129 </literallayout>
4130 You can apply a filter to the script to ignore files under
4131 a certain size.
4132 The previous example filters out any files below 100 Kbytes.
4133 The sizes reported by the tool are uncompressed, and thus
4134 will be smaller by a relatively constant factor in a
4135 compressed root filesystem.
4136 When you examine your log file, you can focus on areas of the
4137 root filesystem that take up large amounts of memory.
4138 </para>
4139
4140 <para>
4141 You need to be sure that what you eliminate does not cripple
4142 the functionality you need.
4143 One way to see how packages relate to each other is by using
4144 the Dependency Explorer UI with the BitBake command:
4145 <literallayout class='monospaced'>
4146 $ cd &lt;image-directory&gt;
4147 $ bitbake -u depexp -g &lt;image&gt;
4148 </literallayout>
4149 Use the interface to select potential packages you wish to
4150 eliminate and see their dependency relationships.
4151 </para>
4152
4153 <para>
4154 When deciding how to reduce the size, get rid of packages that
4155 result in minimal impact on the feature set.
4156 For example, you might not need a VGA display.
4157 Or, you might be able to get by with <filename>devtmpfs</filename>
4158 and <filename>mdev</filename> instead of
4159 <filename>udev</filename>.
4160 </para>
4161
4162 <para>
4163 Use your <filename>local.conf</filename> file to make changes.
4164 For example, to eliminate <filename>udev</filename> and
4165 <filename>glib</filename>, set the following in the
4166 local configuration file:
4167 <literallayout class='monospaced'>
4168 VIRTUAL-RUNTIME_dev_manager = ""
4169 </literallayout>
4170 </para>
4171
4172 <para>
4173 Finally, you should consider exactly the type of root
4174 filesystem you need to meet your needs while also reducing
4175 its size.
4176 For example, consider <filename>cramfs</filename>,
4177 <filename>squashfs</filename>, <filename>ubifs</filename>,
4178 <filename>ext2</filename>, or an <filename>initramfs</filename>
4179 using <filename>initramfs</filename>.
4180 Be aware that <filename>ext3</filename> requires a 1 Mbyte
4181 journal.
4182 If you are okay with running read-only, you do not need this
4183 journal.
4184 </para>
4185
4186 <note>
4187 After each round of elimination, you need to rebuild your
4188 system and then use the tools to see the effects of your
4189 reductions.
4190 </note>
4191
4192
4193 </section>
4194
4195 <section id='trim-the-kernel'>
4196 <title>Trim the Kernel</title>
4197
4198 <para>
4199 The kernel is built by including policies for hardware-independent
4200 aspects.
4201 What subsystems do you enable?
4202 For what architecture are you building?
4203 Which drivers do you build by default?
4204 <note>You can modify the kernel source if you want to help
4205 with boot time.
4206 </note>
4207 </para>
4208
4209 <para>
4210 Run the <filename>ksize.py</filename> script from the top-level
4211 Linux build directory to get an idea of what is making up
4212 the kernel:
4213 <literallayout class='monospaced'>
4214 $ cd &lt;top-level-linux-build-directory&gt;
4215 $ ksize.py > ksize.log
4216 $ cat ksize.log
4217 </literallayout>
4218 When you examine the log, you will see how much space is
4219 taken up with the built-in <filename>.o</filename> files for
4220 drivers, networking, core kernel files, filesystem, sound,
4221 and so forth.
4222 The sizes reported by the tool are uncompressed, and thus
4223 will be smaller by a relatively constant factor in a compressed
4224 kernel image.
4225 Look to reduce the areas that are large and taking up around
4226 the "90% rule."
4227 </para>
4228
4229 <para>
4230 To examine, or drill down, into any particular area, use the
4231 <filename>-d</filename> option with the script:
4232 <literallayout class='monospaced'>
4233 $ ksize.py -d > ksize.log
4234 </literallayout>
4235 Using this option breaks out the individual file information
4236 for each area of the kernel (e.g. drivers, networking, and
4237 so forth).
4238 </para>
4239
4240 <para>
4241 Use your log file to see what you can eliminate from the kernel
4242 based on features you can let go.
4243 For example, if you are not going to need sound, you do not
4244 need any drivers that support sound.
4245 </para>
4246
4247 <para>
4248 After figuring out what to eliminate, you need to reconfigure
4249 the kernel to reflect those changes during the next build.
4250 You could run <filename>menuconfig</filename> and make all your
4251 changes at once.
4252 However, that makes it difficult to see the effects of your
4253 individual eliminations and also makes it difficult to replicate
4254 the changes for perhaps another target device.
4255 A better method is to start with no configurations using
4256 <filename>allnoconfig</filename>, create configuration
4257 fragments for individual changes, and then manage the
4258 fragments into a single configuration file using
4259 <filename>merge_config.sh</filename>.
4260 The tool makes it easy for you to iterate using the
4261 configuration change and build cycle.
4262 </para>
4263
4264 <para>
4265 Each time you make configuration changes, you need to rebuild
4266 the kernel and check to see what impact your changes had on
4267 the overall size.
4268 </para>
4269 </section>
4270
4271 <section id='remove-package-management-requirements'>
4272 <title>Remove Package Management Requirements</title>
4273
4274 <para>
4275 Packaging requirements add size to the image.
4276 One way to reduce the size of the image is to remove all the
4277 packaging requirements from the image.
4278 This reduction includes both removing the package manager
4279 and its unique dependencies as well as removing the package
4280 management data itself.
4281 </para>
4282
4283 <para>
4284 To eliminate all the packaging requirements for an image,
4285 be sure that "package-management" is not part of your
4286 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4287 statement for the image.
4288 When you remove this feature, you are removing the package
4289 manager as well as its dependencies from the root filesystem.
4290 </para>
4291 </section>
4292
4293 <section id='look-for-other-ways-to-minimize-size'>
4294 <title>Look for Other Ways to Minimize Size</title>
4295
4296 <para>
4297 Depending on your particular circumstances, other areas that you
4298 can trim likely exist.
4299 The key to finding these areas is through tools and methods
4300 described here combined with experimentation and iteration.
4301 Here are a couple of areas to experiment with:
4302 <itemizedlist>
4303 <listitem><para><filename>eglibc</filename>:
4304 In general, follow this process:
4305 <orderedlist>
4306 <listitem><para>Remove <filename>eglibc</filename>
4307 features from
4308 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4309 that you think you do not need.</para></listitem>
4310 <listitem><para>Build your distribution.
4311 </para></listitem>
4312 <listitem><para>If the build fails due to missing
4313 symbols in a package, determine if you can
4314 reconfigure the package to not need those
4315 features.
4316 For example, change the configuration to not
4317 support wide character support as is done for
4318 <filename>ncurses</filename>.
4319 Or, if support for those characters is needed,
4320 determine what <filename>eglibc</filename>
4321 features provide the support and restore the
4322 configuration.
4323 </para></listitem>
4324 <listitem><para>Rebuild and repeat the process.
4325 </para></listitem>
4326 </orderedlist></para></listitem>
4327 <listitem><para><filename>busybox</filename>:
4328 For BusyBox, use a process similar as described for
4329 <filename>eglibc</filename>.
4330 A difference is you will need to boot the resulting
4331 system to see if you are able to do everything you
4332 expect from the running system.
4333 You need to be sure to integrate configuration fragments
4334 into Busybox because BusyBox handles its own core
4335 features and then allows you to add configuration
4336 fragments on top.
4337 </para></listitem>
4338 </itemizedlist>
4339 </para>
4340 </section>
4341
4342 <section id='iterate-on-the-process'>
4343 <title>Iterate on the Process</title>
4344
4345 <para>
4346 If you have not reached your goals on system size, you need
4347 to iterate on the process.
4348 The process is the same.
4349 Use the tools and see just what is taking up 90% of the root
4350 filesystem and the kernel.
4351 Decide what you can eliminate without limiting your device
4352 beyond what you need.
4353 </para>
4354
4355 <para>
4356 Depending on your system, a good place to look might be
4357 Busybox, which provides a stripped down
4358 version of Unix tools in a single, executable file.
4359 You might be able to drop virtual terminal services or perhaps
4360 ipv6.
4361 </para>
4362 </section>
4363 </section>
4364
4365 <section id='working-with-packages'>
4366 <title>Working with Packages</title>
4367
4368 <para>
4369 This section describes a few tasks that involve packages:
4370 <itemizedlist>
4371 <listitem><para>
4372 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
4373 </para></listitem>
4374 <listitem><para>
4375 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
4376 </para></listitem>
4377 <listitem><para>
4378 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
4379 </para></listitem>
4380 <listitem><para>
4381 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
4382 </para></listitem>
4383 <listitem><para>
4384 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
4385 </para></listitem>
4386 <listitem><para>
4387 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
4388 </para></listitem>
4389 </itemizedlist>
4390 </para>
4391
4392 <section id='excluding-packages-from-an-image'>
4393 <title>Excluding Packages from an Image</title>
4394
4395 <para>
4396 You might find it necessary to prevent specific packages
4397 from being installed into an image.
4398 If so, you can use several variables to direct the build
4399 system to essentially ignore installing recommended packages
4400 or to not install a package at all.
4401 </para>
4402
4403 <para>
4404 The following list introduces variables you can use to
4405 prevent packages from being installed into your image.
4406 Each of these variables only works with IPK and RPM
4407 package types.
4408 Support for Debian packages does not exist.
4409 Also, you can use these variables from your
4410 <filename>local.conf</filename> file or attach them to a
4411 specific image recipe by using a recipe name override.
4412 For more detail on the variables, see the descriptions in the
4413 Yocto Project Reference Manual's glossary chapter.
4414 <itemizedlist>
4415 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
4416 Use this variable to specify "recommended-only"
4417 packages that you do not want installed.
4418 </para></listitem>
4419 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
4420 Use this variable to prevent all "recommended-only"
4421 packages from being installed.
4422 </para></listitem>
4423 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
4424 Use this variable to prevent specific packages from
4425 being installed regardless of whether they are
4426 "recommended-only" or not.
4427 You need to realize that the build process could
4428 fail with an error when you
4429 prevent the installation of a package whose presence
4430 is required by an installed package.
4431 </para></listitem>
4432 </itemizedlist>
4433 </para>
4434 </section>
4435
4436 <section id='incrementing-a-package-revision-number'>
4437 <title>Incrementing a Package Revision Number</title>
4438
4439 <para>
4440 If a committed change results in changing the package output,
4441 then the value of the
4442 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4443 variable needs to be increased (or "bumped").
4444 Increasing <filename>PR</filename> occurs one of two ways:
4445 <itemizedlist>
4446 <listitem><para>Automatically using a Package Revision
4447 Service (PR Service).</para></listitem>
4448 <listitem><para>Manually incrementing the
4449 <filename>PR</filename> variable.</para></listitem>
4450 </itemizedlist>
4451 </para>
4452
4453 <para>
4454 Given that one of the challenges any build system and its
4455 users face is how to maintain a package feed that is compatible
4456 with existing package manager applications such as
4457 RPM, APT, and OPKG, using an automated system is much
4458 preferred over a manual system.
4459 In either system, the main requirement is that version
4460 numbering increases in a linear fashion and that a number of
4461 version components exist that support that linear progression.
4462 </para>
4463
4464 <para>
4465 The following two sections provide information on the PR Service
4466 and on manual <filename>PR</filename> bumping.
4467 </para>
4468
4469 <section id='working-with-a-pr-service'>
4470 <title>Working With a PR Service</title>
4471
4472 <para>
4473 As mentioned, attempting to maintain revision numbers in the
4474 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4475 is error prone, inaccurate, and causes problems for people
4476 submitting recipes.
4477 Conversely, the PR Service automatically generates
4478 increasing numbers, particularly the revision field,
4479 which removes the human element.
4480 <note>
4481 For additional information on using a PR Service, you
4482 can see the
4483 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
4484 wiki page.
4485 </note>
4486 </para>
4487
4488 <para>
4489 The Yocto Project uses variables in order of
4490 decreasing priority to facilitate revision numbering (i.e.
4491 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
4492 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
4493 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4494 for epoch, version, and revision, respectively).
4495 The values are highly dependent on the policies and
4496 procedures of a given distribution and package feed.
4497 </para>
4498
4499 <para>
4500 Because the OpenEmbedded build system uses
4501 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
4502 which are unique to a given build, the build system
4503 knows when to rebuild packages.
4504 All the inputs into a given task are represented by a
4505 signature, which can trigger a rebuild when different.
4506 Thus, the build system itself does not rely on the
4507 <filename>PR</filename> numbers to trigger a rebuild.
4508 The signatures, however, can be used to generate
4509 <filename>PR</filename> values.
4510 </para>
4511
4512 <para>
4513 The PR Service works with both
4514 <filename>OEBasic</filename> and
4515 <filename>OEBasicHash</filename> generators.
4516 The value of <filename>PR</filename> bumps when the
4517 checksum changes and the different generator mechanisms
4518 change signatures under different circumstances.
4519 </para>
4520
4521 <para>
4522 As implemented, the build system includes values from
4523 the PR Service into the <filename>PR</filename> field as
4524 an addition using the form "<filename>.x</filename>" so
4525 <filename>r0</filename> becomes <filename>r0.1</filename>,
4526 <filename>r0.2</filename> and so forth.
4527 This scheme allows existing <filename>PR</filename> values
4528 to be used for whatever reasons, which include manual
4529 <filename>PR</filename> bumps, should it be necessary.
4530 </para>
4531
4532 <para>
4533 By default, the PR Service is not enabled or running.
4534 Thus, the packages generated are just "self consistent".
4535 The build system adds and removes packages and
4536 there are no guarantees about upgrade paths but images
4537 will be consistent and correct with the latest changes.
4538 </para>
4539
4540 <para>
4541 The simplest form for a PR Service is for it to exist
4542 for a single host development system that builds the
4543 package feed (building system).
4544 For this scenario, you can enable a local PR Service by
4545 setting
4546 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
4547 in your <filename>local.conf</filename> file in the
4548 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4549 <literallayout class='monospaced'>
4550 PRSERV_HOST = "localhost:0"
4551 </literallayout>
4552 Once the service is started, packages will automatically
4553 get increasing <filename>PR</filename> values and
4554 BitBake will take care of starting and stopping the server.
4555 </para>
4556
4557 <para>
4558 If you have a more complex setup where multiple host
4559 development systems work against a common, shared package
4560 feed, you have a single PR Service running and it is
4561 connected to each building system.
4562 For this scenario, you need to start the PR Service using
4563 the <filename>bitbake-prserv</filename> command:
4564 <literallayout class='monospaced'>
4565 bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
4566 </literallayout>
4567 In addition to hand-starting the service, you need to
4568 update the <filename>local.conf</filename> file of each
4569 building system as described earlier so each system
4570 points to the server and port.
4571 </para>
4572
4573 <para>
4574 It is also recommended you use build history, which adds
4575 some sanity checks to package versions, in conjunction with
4576 the server that is running the PR Service.
4577 To enable build history, add the following to each building
4578 system's <filename>local.conf</filename> file:
4579 <literallayout class='monospaced'>
4580 # It is recommended to activate "buildhistory" for testing the PR service
4581 INHERIT += "buildhistory"
4582 BUILDHISTORY_COMMIT = "1"
4583 </literallayout>
4584 For information on build history, see the
4585 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
4586 section in the Yocto Project Reference Manual.
4587 </para>
4588
4589 <note>
4590 <para>The OpenEmbedded build system does not maintain
4591 <filename>PR</filename> information as part of the
4592 shared state (sstate) packages.
4593 If you maintain an sstate feed, its expected that either
4594 all your building systems that contribute to the sstate
4595 feed use a shared PR Service, or you do not run a PR
4596 Service on any of your building systems.
4597 Having some systems use a PR Service while others do
4598 not leads to obvious problems.</para>
4599 <para>For more information on shared state, see the
4600 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
4601 section in the Yocto Project Reference Manual.</para>
4602 </note>
4603 </section>
4604
4605 <section id='manually-bumping-pr'>
4606 <title>Manually Bumping PR</title>
4607
4608 <para>
4609 The alternative to setting up a PR Service is to manually
4610 bump the
4611 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4612 variable.
4613 </para>
4614
4615 <para>
4616 If a committed change results in changing the package output,
4617 then the value of the PR variable needs to be increased
4618 (or "bumped") as part of that commit.
4619 For new recipes you should add the <filename>PR</filename>
4620 variable and set its initial value equal to "r0", which is the default.
4621 Even though the default value is "r0", the practice of adding it to a new recipe makes
4622 it harder to forget to bump the variable when you make changes
4623 to the recipe in future.
4624 </para>
4625
4626 <para>
4627 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
4628 you can also use the
4629 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
4630 variable to ensure that
4631 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
4632 <filename>.inc</filename> file itself is changed.
4633 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
4634 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
4635 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
4636 If the <filename>.inc</filename> file is changed then its
4637 <filename>INC_PR</filename> should be incremented.
4638 </para>
4639
4640 <para>
4641 When upgrading the version of a package, assuming the
4642 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
4643 changes, the <filename>PR</filename> variable should be
4644 reset to "r0" (or "$(INC_PR).0" if you are using
4645 <filename>INC_PR</filename>).
4646 </para>
4647
4648 <para>
4649 Usually, version increases occur only to packages.
4650 However, if for some reason <filename>PV</filename> changes but does not
4651 increase, you can increase the
4652 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
4653 variable (Package Epoch).
4654 The <filename>PE</filename> variable defaults to "0".
4655 </para>
4656
4657 <para>
4658 Version numbering strives to follow the
4659 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
4660 Debian Version Field Policy Guidelines</ulink>.
4661 These guidelines define how versions are compared and what "increasing" a version means.
4662 </para>
4663 </section>
4664 </section>
4665
4666 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
4667 <title>Handling a Package Name Alias</title>
4668 <para>
4669 Sometimes a package name you are using might exist under an alias or as a similarly named
4670 package in a different distribution.
4671 The OpenEmbedded build system implements a <filename>distro_check</filename>
4672 task that automatically connects to major distributions
4673 and checks for these situations.
4674 If the package exists under a different name in a different distribution, you get a
4675 <filename>distro_check</filename> mismatch.
4676 You can resolve this problem by defining a per-distro recipe name alias using the
4677 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
4678 variable.
4679 </para>
4680
4681 <para>
4682 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
4683 variable:
4684 <literallayout class='monospaced'>
4685 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
4686 distro2=package_name_alias2 \
4687 distro3=package_name_alias3 \
4688 ..."
4689 </literallayout>
4690 </para>
4691
4692 <para>
4693 If you have more than one distribution alias, separate them with a space.
4694 Note that the build system currently automatically checks the
4695 Fedora, OpenSUSE, Debian, Ubuntu,
4696 and Mandriva distributions for source package recipes without having to specify them
4697 using the <filename>DISTRO_PN_ALIAS</filename> variable.
4698 For example, the following command generates a report that lists the Linux distributions
4699 that include the sources for each of the recipes.
4700 <literallayout class='monospaced'>
4701 $ bitbake world -f -c distro_check
4702 </literallayout>
4703 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
4704 file found in the
4705 <link linkend='source-directory'>Source Directory</link>.
4706 </para>
4707 </section>
4708
4709 <section id='handling-optional-module-packaging'>
4710 <title>Handling Optional Module Packaging</title>
4711
4712 <para>
4713 Many pieces of software split functionality into optional
4714 modules (or plug-ins) and the plug-ins that are built
4715 might depend on configuration options.
4716 To avoid having to duplicate the logic that determines what
4717 modules are available in your recipe or to avoid having
4718 to package each module by hand, the OpenEmbedded build system
4719 provides functionality to handle module packaging dynamically.
4720 </para>
4721
4722 <para>
4723 To handle optional module packaging, you need to do two things:
4724 <itemizedlist>
4725 <listitem><para>Ensure the module packaging is actually
4726 done.</para></listitem>
4727 <listitem><para>Ensure that any dependencies on optional
4728 modules from other recipes are satisfied by your recipe.
4729 </para></listitem>
4730 </itemizedlist>
4731 </para>
4732
4733 <section id='making-sure-the-packaging-is-done'>
4734 <title>Making Sure the Packaging is Done</title>
4735
4736 <para>
4737 To ensure the module packaging actually gets done, you use
4738 the <filename>do_split_packages</filename> function within
4739 the <filename>populate_packages</filename> Python function
4740 in your recipe.
4741 The <filename>do_split_packages</filename> function
4742 searches for a pattern of files or directories under a
4743 specified path and creates a package for each one it finds
4744 by appending to the
4745 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
4746 variable and setting the appropriate values for
4747 <filename>FILES_packagename</filename>,
4748 <filename>RDEPENDS_packagename</filename>,
4749 <filename>DESCRIPTION_packagename</filename>, and so forth.
4750 Here is an example from the <filename>lighttpd</filename>
4751 recipe:
4752 <literallayout class='monospaced'>
4753 python populate_packages_prepend () {
4754 lighttpd_libdir = d.expand('${libdir}')
4755 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
4756 'lighttpd-module-%s', 'Lighttpd module for %s',
4757 extra_depends='')
4758 }
4759 </literallayout>
4760 The previous example specifies a number of things in the
4761 call to <filename>do_split_packages</filename>.
4762 <itemizedlist>
4763 <listitem><para>A directory within the files installed
4764 by your recipe through <filename>do_install</filename>
4765 in which to search.</para></listitem>
4766 <listitem><para>A regular expression used to match module
4767 files in that directory.
4768 In the example, note the parentheses () that mark
4769 the part of the expression from which the module
4770 name should be derived.</para></listitem>
4771 <listitem><para>A pattern to use for the package names.
4772 </para></listitem>
4773 <listitem><para>A description for each package.
4774 </para></listitem>
4775 <listitem><para>An empty string for
4776 <filename>extra_depends</filename>, which disables
4777 the default dependency on the main
4778 <filename>lighttpd</filename> package.
4779 Thus, if a file in <filename>${libdir}</filename>
4780 called <filename>mod_alias.so</filename> is found,
4781 a package called <filename>lighttpd-module-alias</filename>
4782 is created for it and the
4783 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
4784 is set to "Lighttpd module for alias".</para></listitem>
4785 </itemizedlist>
4786 </para>
4787
4788 <para>
4789 Often, packaging modules is as simple as the previous
4790 example.
4791 However, more advanced options exist that you can use
4792 within <filename>do_split_packages</filename> to modify its
4793 behavior.
4794 And, if you need to, you can add more logic by specifying
4795 a hook function that is called for each package.
4796 It is also perfectly acceptable to call
4797 <filename>do_split_packages</filename> multiple times if
4798 you have more than one set of modules to package.
4799 </para>
4800
4801 <para>
4802 For more examples that show how to use
4803 <filename>do_split_packages</filename>, see the
4804 <filename>connman.inc</filename> file in the
4805 <filename>meta/recipes-connectivity/connman/</filename>
4806 directory of the <filename>poky</filename>
4807 <link linkend='yocto-project-repositories'>source repository</link>.
4808 You can also find examples in
4809 <filename>meta/classes/kernel.bbclass</filename>.
4810 </para>
4811
4812 <para>
4813 Following is a reference that shows
4814 <filename>do_split_packages</filename> mandatory and
4815 optional arguments:
4816 <literallayout class='monospaced'>
4817 Mandatory arguments
4818
4819 root
4820 The path in which to search
4821 file_regex
4822 Regular expression to match searched files.
4823 Use parentheses () to mark the part of this
4824 expression that should be used to derive the
4825 module name (to be substituted where %s is
4826 used in other function arguments as noted below)
4827 output_pattern
4828 Pattern to use for the package names. Must
4829 include %s.
4830 description
4831 Description to set for each package. Must
4832 include %s.
4833
4834 Optional arguments
4835
4836 postinst
4837 Postinstall script to use for all packages
4838 (as a string)
4839 recursive
4840 True to perform a recursive search - default
4841 False
4842 hook
4843 A hook function to be called for every match.
4844 The function will be called with the following
4845 arguments (in the order listed):
4846
4847 f
4848 Full path to the file/directory match
4849 pkg
4850 The package name
4851 file_regex
4852 As above
4853 output_pattern
4854 As above
4855 modulename
4856 The module name derived using file_regex
4857
4858 extra_depends
4859 Extra runtime dependencies (RDEPENDS) to be
4860 set for all packages. The default value of None
4861 causes a dependency on the main package
4862 (${PN}) - if you do not want this, pass empty
4863 string '' for this parameter.
4864 aux_files_pattern
4865 Extra item(s) to be added to FILES for each
4866 package. Can be a single string item or a list
4867 of strings for multiple items. Must include %s.
4868 postrm
4869 postrm script to use for all packages (as a
4870 string)
4871 allow_dirs
4872 True to allow directories to be matched -
4873 default False
4874 prepend
4875 If True, prepend created packages to PACKAGES
4876 instead of the default False which appends them
4877 match_path
4878 match file_regex on the whole relative path to
4879 the root rather than just the file name
4880 aux_files_pattern_verbatim
4881 Extra item(s) to be added to FILES for each
4882 package, using the actual derived module name
4883 rather than converting it to something legal
4884 for a package name. Can be a single string item
4885 or a list of strings for multiple items. Must
4886 include %s.
4887 allow_links
4888 True to allow symlinks to be matched - default
4889 False
4890 summary
4891 Summary to set for each package. Must include %s;
4892 defaults to description if not set.
4893 </literallayout>
4894 </para>
4895 </section>
4896
4897 <section id='satisfying-dependencies'>
4898 <title>Satisfying Dependencies</title>
4899
4900 <para>
4901 The second part for handling optional module packaging
4902 is to ensure that any dependencies on optional modules
4903 from other recipes are satisfied by your recipe.
4904 You can be sure these dependencies are satisfied by
4905 using the
4906 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
4907 Here is an example that continues with the
4908 <filename>lighttpd</filename> recipe shown earlier:
4909 <literallayout class='monospaced'>
4910 PACKAGES_DYNAMIC = "lighttpd-module-.*"
4911 </literallayout>
4912 The name specified in the regular expression can of
4913 course be anything.
4914 In this example, it is <filename>lighttpd-module-</filename>
4915 and is specified as the prefix to ensure that any
4916 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
4917 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
4918 on a package name starting with the prefix are satisfied
4919 during build time.
4920 If you are using <filename>do_split_packages</filename>
4921 as described in the previous section, the value you put in
4922 <filename>PACKAGES_DYNAMIC</filename> should correspond to
4923 the name pattern specified in the call to
4924 <filename>do_split_packages</filename>.
4925 </para>
4926 </section>
4927 </section>
4928
4929 <section id='using-runtime-package-management'>
4930 <title>Using Runtime Package Management</title>
4931
4932 <para>
4933 During a build, BitBake always transforms a recipe into one or
4934 more packages.
4935 For example, BitBake takes the <filename>bash</filename> recipe
4936 and currently produces the <filename>bash-dbg</filename>,
4937 <filename>bash-staticdev</filename>,
4938 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
4939 <filename>bash-locale</filename>, and
4940 <filename>bash</filename> packages.
4941 Not all generated packages are included in an image.
4942 </para>
4943
4944 <para>
4945 In several situations, you might need to update, add, remove,
4946 or query the packages on a target device at runtime
4947 (i.e. without having to generate a new image).
4948 Examples of such situations include:
4949 <itemizedlist>
4950 <listitem><para>
4951 You want to provide in-the-field updates to deployed
4952 devices (e.g. security updates).
4953 </para></listitem>
4954 <listitem><para>
4955 You want to have a fast turn-around development cycle
4956 for one or more applications that run on your device.
4957 </para></listitem>
4958 <listitem><para>
4959 You want to temporarily install the "debug" packages
4960 of various applications on your device so that
4961 debugging can be greatly improved by allowing
4962 access to symbols and source debugging.
4963 </para></listitem>
4964 <listitem><para>
4965 You want to deploy a more minimal package selection of
4966 your device but allow in-the-field updates to add a
4967 larger selection for customization.
4968 </para></listitem>
4969 </itemizedlist>
4970 </para>
4971
4972 <para>
4973 In all these situations, you have something similar to a more
4974 traditional Linux distribution in that in-field devices
4975 are able to receive pre-compiled packages from a server for
4976 installation or update.
4977 Being able to install these packages on a running,
4978 in-field device is what is termed "runtime package
4979 management".
4980 </para>
4981
4982 <para>
4983 In order to use runtime package management, you
4984 need a host/server machine that serves up the pre-compiled
4985 packages plus the required metadata.
4986 You also need package manipulation tools on the target.
4987 The build machine is a likely candidate to act as the server.
4988 However, that machine does not necessarily have to be the
4989 package server.
4990 The build machine could push its artifacts to another machine
4991 that acts as the server (e.g. Internet-facing).
4992 </para>
4993
4994 <para>
4995 A simple build that targets just one device produces
4996 more than one package database.
4997 In other words, the packages produced by a build are separated
4998 out into a couple of different package groupings based on
4999 criteria such as the target's CPU architecture, the target
5000 board, or the C library used on the target.
5001 For example, a build targeting the <filename>qemuarm</filename>
5002 device produces the following three package databases:
5003 <filename>all</filename>, <filename>armv5te</filename>, and
5004 <filename>qemuarm</filename>.
5005 If you wanted your <filename>qemuarm</filename> device to be
5006 aware of all the packages that were available to it,
5007 you would need to point it to each of these databases
5008 individually.
5009 In a similar way, a traditional Linux distribution usually is
5010 configured to be aware of a number of software repositories
5011 from which it retrieves packages.
5012 </para>
5013
5014 <para>
5015 Using runtime package management is completely optional and
5016 not required for a successful build or deployment in any
5017 way.
5018 But if you want to make use of runtime package management,
5019 you need to do a couple things above and beyond the basics.
5020 The remainder of this section describes what you need to do.
5021 </para>
5022
5023 <section id='runtime-package-management-build'>
5024 <title>Build Considerations</title>
5025
5026 <para>
5027 This section describes build considerations that you need
5028 to be aware of in order to provide support for runtime
5029 package management.
5030 </para>
5031
5032 <para>
5033 When BitBake generates packages it needs to know
5034 what format or formats to use.
5035 In your configuration, you use the
5036 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
5037 variable to specify the format.
5038 <note>
5039 You can choose to have more than one format but you must
5040 provide at least one.
5041 </note>
5042 </para>
5043
5044 <para>
5045 If you would like your image to start off with a basic
5046 package database of the packages in your current build
5047 as well as have the relevant tools available on the
5048 target for runtime package management, you can include
5049 "package-management" in the
5050 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5051 variable.
5052 Including "package-management" in this
5053 configuration variable ensures that when the image
5054 is assembled for your target, the image includes
5055 the currently-known package databases as well as
5056 the target-specific tools required for runtime
5057 package management to be performed on the target.
5058 However, this is not strictly necessary.
5059 You could start your image off without any databases
5060 but only include the required on-target package
5061 tool(s).
5062 As an example, you could include "opkg" in your
5063 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
5064 variable if you are using the IPK package format.
5065 You can then initialize your target's package database(s)
5066 later once your image is up and running.
5067 </para>
5068
5069 <para>
5070 Whenever you perform any sort of build step that can
5071 potentially generate a package or modify an existing
5072 package, it is always a good idea to re-generate the
5073 package index with:
5074 <literallayout class='monospaced'>
5075 $ bitbake package-index
5076 </literallayout>
5077 Realize that it is not sufficient to simply do the
5078 following:
5079 <literallayout class='monospaced'>
5080 $ bitbake &lt;some-package&gt; package-index
5081 </literallayout>
5082 This is because BitBake does not properly schedule the
5083 <filename>package-index</filename> target fully after any
5084 other target has completed.
5085 Thus, be sure to run the package update step separately.
5086 </para>
5087
5088 <para>
5089 As described below in the
5090 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
5091 section, if you are using IPK as your package format, you
5092 can make use of the
5093 <filename>distro-feed-configs</filename> recipe provided
5094 by <filename>meta-oe</filename> in order to configure your
5095 target to use your IPK databases.
5096 </para>
5097
5098 <para>
5099 When your build is complete, your packages reside in the
5100 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
5101 directory.
5102 For example, if <filename>${TMPDIR}</filename>
5103 is <filename>tmp</filename> and your selected package type
5104 is IPK, then your IPK packages are available in
5105 <filename>tmp/deploy/ipk</filename>.
5106 </para>
5107 </section>
5108
5109 <section id='runtime-package-management-server'>
5110 <title>Host or Server Machine Setup</title>
5111
5112 <para>
5113 Typically, packages are served from a server using
5114 HTTP.
5115 However, other protocols are possible.
5116 If you want to use HTTP, then setup and configure a
5117 web server, such as Apache 2 or lighttpd, on the machine
5118 serving the packages.
5119 </para>
5120
5121 <para>
5122 As previously mentioned, the build machine can act as the
5123 package server.
5124 In the following sections that describe server machine
5125 setups, the build machine is assumed to also be the server.
5126 </para>
5127
5128 <section id='package-server-apache'>
5129 <title>Serving Packages via Apache 2</title>
5130
5131 <para>
5132 This example assumes you are using the Apache 2
5133 server:
5134 <orderedlist>
5135 <listitem><para>
5136 Add the directory to your Apache
5137 configuration, which you can find at
5138 <filename>/etc/httpd/conf/httpd.conf</filename>.
5139 Use commands similar to these on the
5140 development system.
5141 These example commands assume a top-level
5142 <link linkend='source-directory'>Source Directory</link>
5143 named <filename>poky</filename> in your home
5144 directory.
5145 The example also assumes an RPM package type.
5146 If you are using a different package type, such
5147 as IPK, use "ipk" in the pathnames:
5148 <literallayout class='monospaced'>
5149 &lt;VirtualHost *:80&gt;
5150 ....
5151 Alias /rpm ~/poky/build/tmp/deploy/rpm
5152 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
5153 Options +Indexes
5154 &lt;/Directory&gt;
5155 &lt;/VirtualHost&gt;
5156 </literallayout></para></listitem>
5157 <listitem><para>
5158 Reload the Apache configuration as described
5159 in this step.
5160 For all commands, be sure you have root
5161 privileges.
5162 </para>
5163
5164 <para>
5165 If your development system is using Fedora or
5166 CentOS, use the following:
5167 <literallayout class='monospaced'>
5168 # service httpd reload
5169 </literallayout>
5170 For Ubuntu and Debian, use the following:
5171 <literallayout class='monospaced'>
5172 # /etc/init.d/apache2 reload
5173 </literallayout>
5174 For OpenSUSE, use the following:
5175 <literallayout class='monospaced'>
5176 # /etc/init.d/apache2 reload
5177 </literallayout></para></listitem>
5178 <listitem><para>
5179 If you are using Security-Enhanced Linux
5180 (SELinux), you need to label the files as
5181 being accessible through Apache.
5182 Use the following command from the development
5183 host.
5184 This example assumes RPM package types:
5185 <literallayout class='monospaced'>
5186 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
5187 </literallayout></para></listitem>
5188 </orderedlist>
5189 </para>
5190 </section>
5191
5192 <section id='package-server-lighttpd'>
5193 <title>Serving Packages via lighttpd</title>
5194
5195 <para>
5196 If you are using lighttpd, all you need
5197 to do is to provide a link from your
5198 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
5199 directory to lighttpd's document-root.
5200 You can determine the specifics of your lighttpd
5201 installation by looking through its configuration file,
5202 which is usually found at:
5203 <filename>/etc/lighttpd/lighttpd.conf</filename>.
5204 </para>
5205
5206 <para>
5207 For example, if you are using IPK, lighttpd's
5208 document-root is set to
5209 <filename>/var/www/lighttpd</filename>, and you had
5210 packages for a target named "BOARD",
5211 then you might create a link from your build location
5212 to lighttpd's document-root as follows:
5213 <literallayout class='monospaced'>
5214 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
5215 </literallayout>
5216 </para>
5217
5218 <para>
5219 At this point, you need to start the lighttpd server.
5220 The method used to start the server varies by
5221 distribution.
5222 However, one basic method that starts it by hand is:
5223 <literallayout class='monospaced'>
5224 # lighttpd -f /etc/lighttpd/lighttpd.conf
5225 </literallayout>
5226 </para>
5227 </section>
5228 </section>
5229
5230 <section id='runtime-package-management-target'>
5231 <title>Target Setup</title>
5232
5233 <para>
5234 Setting up the target differs depending on the
5235 package management system.
5236 This section provides information for RPM and IPK.
5237 </para>
5238
5239 <section id='runtime-package-management-target-rpm'>
5240 <title>Using RPM</title>
5241
5242 <para>
5243 The application for performing runtime package
5244 management of RPM packages on the target is called
5245 <filename>smart</filename>.
5246 </para>
5247
5248 <para>
5249 On the target machine, you need to inform
5250 <filename>smart</filename> of every package database
5251 you want to use.
5252 As an example, suppose your target device can use the
5253 following three package databases from a server named
5254 <filename>server.name</filename>:
5255 <filename>all</filename>, <filename>i586</filename>,
5256 and <filename>qemux86</filename>.
5257 Given this example, issue the following commands on the
5258 target:
5259 <literallayout class='monospaced'>
5260 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
5261 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
5262 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
5263 </literallayout>
5264 Also from the target machine, fetch the repository
5265 information using this command:
5266 <literallayout class='monospaced'>
5267 # smart update
5268 </literallayout>
5269 You can now use the <filename>smart query</filename>
5270 and <filename>smart install</filename> commands to
5271 find and install packages from the repositories.
5272 </para>
5273 </section>
5274
5275 <section id='runtime-package-management-target-ipk'>
5276 <title>Using IPK</title>
5277
5278 <para>
5279 The application for performing runtime package
5280 management of IPK packages on the target is called
5281 <filename>opkg</filename>.
5282 </para>
5283
5284 <para>
5285 In order to inform <filename>opkg</filename> of the
5286 package databases you want to use, simply create one
5287 or more <filename>*.conf</filename> files in the
5288 <filename>/etc/opkg</filename> directory on the target.
5289 The <filename>opkg</filename> application uses them
5290 to find its available package databases.
5291 As an example, suppose you configured your HTTP server
5292 on your machine named
5293 <filename>www.mysite.com</filename> to serve files
5294 from a <filename>BOARD-dir</filename> directory under
5295 its document-root.
5296 In this case, you might create a configuration
5297 file on the target called
5298 <filename>/etc/opkg/base-feeds.conf</filename> that
5299 contains:
5300 <literallayout class='monospaced'>
5301 src/gz all http://www.mysite.com/BOARD-dir/all
5302 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
5303 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
5304 </literallayout>
5305 </para>
5306
5307 <para>
5308 As a way of making it easier to generate and make
5309 these IPK configuration files available on your
5310 target, simply define
5311 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
5312 to point to your server and the location within the
5313 document-root which contains the databases.
5314 For example: if you are serving your packages over
5315 HTTP, your server's IP address is 192.168.7.1, and
5316 your databases are located in a directory called
5317 <filename>BOARD-dir</filename> underneath your HTTP
5318 server's document-root, you need to set
5319 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
5320 <filename>http://192.168.7.1/BOARD-dir</filename> and
5321 a set of configuration files will be generated for you
5322 in your target to work with this feed.
5323 </para>
5324
5325 <para>
5326 On the target machine, fetch (or refresh) the
5327 repository information using this command:
5328 <literallayout class='monospaced'>
5329 # opkg update
5330 </literallayout>
5331 You can now use the <filename>opkg list</filename> and
5332 <filename>opkg install</filename> commands to find and
5333 install packages from the repositories.
5334 </para>
5335 </section>
5336 </section>
5337 </section>
5338
5339 <section id='testing-packages-with-ptest'>
5340 <title>Testing Packages With ptest</title>
5341
5342 <para>
5343 A Package Test (ptest) runs tests against packages built
5344 by the OpenEmbedded build system on the target machine.
5345 A ptest contains at least two items: the actual test, and
5346 a shell script (<filename>run-ptest</filename>) that starts
5347 the test.
5348 The shell script that starts the test must not contain
5349 the actual test, the script only starts it.
5350 On the other hand, the test can be anything from a simple
5351 shell script that runs a binary and checks the output to
5352 an elaborate system of test binaries and data files.
5353 </para>
5354
5355 <para>
5356 The test generates output in the format used by
5357 Automake:
5358 <literallayout class='monospaced'>
5359 &lt;result&gt;: &lt;testname&gt;
5360 </literallayout>
5361 where the result can be <filename>PASS</filename>,
5362 <filename>FAIL</filename>, or <filename>SKIP</filename>,
5363 and the testname can be any identifying string.
5364 </para>
5365
5366 <note>
5367 A recipe is "ptest-enabled" if it inherits the
5368 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5369 class.
5370 </note>
5371
5372 <section id='adding-ptest-to-your-build'>
5373 <title>Adding ptest to Your Build</title>
5374
5375 <para>
5376 To add package testing to your build, add the
5377 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5378 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
5379 variables to your <filename>local.conf</filename> file,
5380 which is found in the
5381 <link linkend='build-directory'>Build Directory</link>:
5382 <literallayout class='monospaced'>
5383 DISTRO_FEATURES_append = " ptest"
5384 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
5385 </literallayout>
5386 Once your build is complete, the ptest files are installed
5387 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
5388 directory within the image, where
5389 <filename>&lt;package&gt;</filename> is the name of the
5390 package.
5391 </para>
5392 </section>
5393
5394 <section id='running-ptest'>
5395 <title>Running ptest</title>
5396
5397 <para>
5398 The <filename>ptest-runner</filename> package installs a
5399 shell script that loops through all installed ptest test
5400 suites and runs them in sequence.
5401 Consequently, you might want to add this package to
5402 your image.
5403 </para>
5404 </section>
5405
5406 <section id='getting-your-package-ready'>
5407 <title>Getting Your Package Ready</title>
5408
5409 <para>
5410 In order to enable a recipe to run installed ptests
5411 on target hardware,
5412 you need to prepare the recipes that build the packages
5413 you want to test.
5414 Here is what you have to do for each recipe:
5415 <itemizedlist>
5416 <listitem><para><emphasis>Be sure the recipe
5417 inherits the
5418 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5419 class:</emphasis>
5420 Include the following line in each recipe:
5421 <literallayout class='monospaced'>
5422 inherit ptest
5423 </literallayout>
5424 </para></listitem>
5425 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
5426 This script starts your test.
5427 Locate the script where you will refer to it
5428 using
5429 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
5430 Here is an example that starts a test for
5431 <filename>dbus</filename>:
5432 <literallayout class='monospaced'>
5433 #!/bin/sh
5434 cd test
5435 make -k runtest-TESTS
5436 </literallayout>
5437 </para></listitem>
5438 <listitem><para><emphasis>Ensure dependencies are
5439 met:</emphasis>
5440 If the test adds build or runtime dependencies
5441 that normally do not exist for the package
5442 (such as requiring "make" to run the test suite),
5443 use the
5444 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
5445 and
5446 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
5447 variables in your recipe in order for the package
5448 to meet the dependencies.
5449 Here is an example where the package has a runtime
5450 dependency on "make":
5451 <literallayout class='monospaced'>
5452 RDEPENDS_${PN}-ptest += "make"
5453 </literallayout>
5454 </para></listitem>
5455 <listitem><para><emphasis>Add a function to build the
5456 test suite:</emphasis>
5457 Not many packages support cross-compilation of
5458 their test suites.
5459 Consequently, you usually need to add a
5460 cross-compilation function to the package.
5461 </para>
5462 <para>Many packages based on Automake compile and
5463 run the test suite by using a single command
5464 such as <filename>make check</filename>.
5465 However, the native <filename>make check</filename>
5466 builds and runs on the same computer, while
5467 cross-compiling requires that the package is built
5468 on the host but executed on the target.
5469 The built version of Automake that ships with the
5470 Yocto Project includes a patch that separates
5471 building and execution.
5472 Consequently, packages that use the unaltered,
5473 patched version of <filename>make check</filename>
5474 automatically cross-compiles.</para>
5475 <para>However, you still must add a
5476 <filename>do_compile_ptest</filename> function to
5477 build the test suite.
5478 Add a function similar to the following to your
5479 recipe:
5480 <literallayout class='monospaced'>
5481 do_compile_ptest() {
5482 oe_runmake buildtest-TESTS
5483 }
5484 </literallayout>
5485 </para></listitem>
5486 <listitem><para><emphasis>Ensure special configurations
5487 are set:</emphasis>
5488 If the package requires special configurations
5489 prior to compiling the test code, you must
5490 insert a <filename>do_configure_ptest</filename>
5491 function into the recipe.
5492 </para></listitem>
5493 <listitem><para><emphasis>Install the test
5494 suite:</emphasis>
5495 The <filename>ptest</filename> class
5496 automatically copies the file
5497 <filename>run-ptest</filename> to the target and
5498 then runs make <filename>install-ptest</filename>
5499 to run the tests.
5500 If this is not enough, you need to create a
5501 <filename>do_install_ptest</filename> function and
5502 make sure it gets called after the
5503 "make install-ptest" completes.
5504 </para></listitem>
5505 </itemizedlist>
5506 </para>
5507 </section>
5508 </section>
5509 </section>
5510
5511 <section id="building-software-from-an-external-source">
5512 <title>Building Software from an External Source</title>
5513
5514 <para>
5515 By default, the OpenEmbedded build system uses the
5516 <link linkend='build-directory'>Build Directory</link> to
5517 build source code.
5518 The build process involves fetching the source files, unpacking
5519 them, and then patching them if necessary before the build takes
5520 place.
5521 </para>
5522
5523 <para>
5524 Situations exist where you might want to build software from source
5525 files that are external to and thus outside of the
5526 OpenEmbedded build system.
5527 For example, suppose you have a project that includes a new BSP with
5528 a heavily customized kernel.
5529 And, you want to minimize exposing the build system to the
5530 development team so that they can focus on their project and
5531 maintain everyone's workflow as much as possible.
5532 In this case, you want a kernel source directory on the development
5533 machine where the development occurs.
5534 You want the recipe's
5535 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
5536 variable to point to the external directory and use it as is, not
5537 copy it.
5538 </para>
5539
5540 <para>
5541 To build from software that comes from an external source, all you
5542 need to do is inherit the
5543 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
5544 class and then set the
5545 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
5546 variable to point to your external source code.
5547 Here are the statements to put in your
5548 <filename>local.conf</filename> file:
5549 <literallayout class='monospaced'>
5550 INHERIT += "externalsrc"
5551 EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
5552 </literallayout>
5553 </para>
5554
5555 <para>
5556 By default, <filename>externalsrc.bbclass</filename> builds
5557 the source code in a directory separate from the external source
5558 directory as specified by
5559 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
5560 If you need to have the source built in the same directory in
5561 which it resides, or some other nominated directory, you can set
5562 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
5563 to point to that directory:
5564 <literallayout class='monospaced'>
5565 EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
5566 </literallayout>
5567 </para>
5568 </section>
5569
5570 <section id="selecting-an-initialization-manager">
5571 <title>Selecting an Initialization Manager</title>
5572
5573 <para>
5574 By default, the Yocto Project uses SysVinit as the initialization
5575 manager.
5576 However, support also exists for systemd,
5577 which is a full replacement for init with
5578 parallel starting of services, reduced shell overhead and other
5579 features that are used by many distributions.
5580 </para>
5581
5582 <para>
5583 If you want to use SysVinit, you do
5584 not have to do anything.
5585 But, if you want to use systemd, you must
5586 take some steps as described in the following sections.
5587 </para>
5588
5589 <section id='using-systemd-exclusively'>
5590 <title>Using systemd Exclusively</title>
5591
5592 <para>
5593 Set the these variables in your distribution configuration
5594 file as follows:
5595 <literallayout class='monospaced'>
5596 DISTRO_FEATURES_append = " systemd"
5597 VIRTUAL-RUNTIME_init_manager = "systemd"
5598 </literallayout>
5599 You can also prevent the SysVinit
5600 distribution feature from
5601 being automatically enabled as follows:
5602 <literallayout class='monospaced'>
5603 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
5604 </literallayout>
5605 Doing so removes any redundant SysVinit scripts.
5606 </para>
5607
5608 <para>
5609 To remove initscripts from your image altogether,
5610 set this variable also:
5611 <literallayout class='monospaced'>
5612 VIRTUAL-RUNTIME_initscripts = ""
5613 </literallayout>
5614 </para>
5615
5616 <para>
5617 For information on the backfill variable, see
5618 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
5619 </para>
5620 </section>
5621
5622 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
5623 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
5624
5625 <para>
5626 Set the these variables in your distribution configuration
5627 file as follows:
5628 <literallayout class='monospaced'>
5629 DISTRO_FEATURES_append = " systemd"
5630 VIRTUAL-RUNTIME_init_manager = "systemd"
5631 </literallayout>
5632 Doing so causes your main image to use the
5633 <filename>packagegroup-core-boot.bb</filename> recipe and
5634 systemd.
5635 The rescue/minimal image cannot use this package group.
5636 However, it can install SysVinit
5637 and the appropriate packages will have support for both
5638 systemd and SysVinit.
5639 </para>
5640 </section>
5641 </section>
5642
5643 <section id="platdev-appdev-srcrev">
5644 <title>Using an External SCM</title>
5645
5646 <para>
5647 If you're working on a recipe that pulls from an external Source
5648 Code Manager (SCM), it is possible to have the OpenEmbedded build
5649 system notice new recipe changes added to the SCM and then build
5650 the resulting packages that depend on the new recipes by using
5651 the latest versions.
5652 This only works for SCMs from which it is possible to get a
5653 sensible revision number for changes.
5654 Currently, you can do this with Apache Subversion (SVN), Git, and
5655 Bazaar (BZR) repositories.
5656 </para>
5657
5658 <para>
5659 To enable this behavior, the
5660 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
5661 of the recipe needs to reference
5662 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
5663 Here is an example:
5664 <literallayout class='monospaced'>
5665 PV = "1.2.3+git${SRCPV}
5666 </literallayout>
5667 Then, you can add the following to your
5668 <filename>local.conf</filename>:
5669 <literallayout class='monospaced'>
5670 SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
5671 </literallayout>
5672 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
5673 is the name of the recipe for which you want to enable automatic source
5674 revision updating.
5675 </para>
5676
5677 <para>
5678 If you do not want to update your local configuration file, you can
5679 add the following directly to the recipe to finish enabling
5680 the feature:
5681 <literallayout class='monospaced'>
5682 SRCREV = "${AUTOREV}"
5683 </literallayout>
5684 </para>
5685
5686 <para>
5687 The Yocto Project provides a distribution named
5688 <filename>poky-bleeding</filename>, whose configuration
5689 file contains the line:
5690 <literallayout class='monospaced'>
5691 require conf/distro/include/poky-floating-revisions.inc
5692 </literallayout>
5693 This line pulls in the listed include file that contains
5694 numerous lines of exactly that form:
5695 <literallayout class='monospaced'>
5696 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
5697 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
5698 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
5699 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
5700 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
5701 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
5702 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
5703 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
5704 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
5705 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
5706 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
5707 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
5708 SRCREV_pn-screenshot ?= "${AUTOREV}"
5709 SRCREV_pn-libfakekey ?= "${AUTOREV}"
5710 SRCREV_pn-oprofileui ?= "${AUTOREV}"
5711 .
5712 .
5713 .
5714 </literallayout>
5715 These lines allow you to experiment with building a
5716 distribution that tracks the latest development source
5717 for numerous packages.
5718 <note><title>Caution</title>
5719 The <filename>poky-bleeding</filename> distribution
5720 is not tested on a regular basis.
5721 Keep this in mind if you use it.
5722 </note>
5723 </para>
5724 </section>
5725
5726 <section id='creating-a-read-only-root-filesystem'>
5727 <title>Creating a Read-Only Root Filesystem</title>
5728
5729 <para>
5730 Suppose, for security reasons, you need to disable
5731 your target device's root filesystem's write permissions
5732 (i.e. you need a read-only root filesystem).
5733 Or, perhaps you are running the device's operating system
5734 from a read-only storage device.
5735 For either case, you can customize your image for
5736 that behavior.
5737 </para>
5738
5739 <note>
5740 Supporting a read-only root filesystem requires that the system and
5741 applications do not try to write to the root filesystem.
5742 You must configure all parts of the target system to write
5743 elsewhere, or to gracefully fail in the event of attempting to
5744 write to the root filesystem.
5745 </note>
5746
5747 <section id='creating-the-root-filesystem'>
5748 <title>Creating the Root Filesystem</title>
5749
5750 <para>
5751 To create the read-only root filesystem, simply add the
5752 "read-only-rootfs" feature to your image.
5753 Using either of the following statements in your
5754 image recipe or from within the
5755 <filename>local.conf</filename> file found in the
5756 <link linkend='build-directory'>Build Directory</link>
5757 causes the build system to create a read-only root filesystem:
5758 <literallayout class='monospaced'>
5759 IMAGE_FEATURES = "read-only-rootfs"
5760 </literallayout>
5761 or
5762 <literallayout class='monospaced'>
5763 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
5764 </literallayout>
5765 </para>
5766
5767 <para>
5768 For more information on how to use these variables, see the
5769 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
5770 section.
5771 For information on the variables, see
5772 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5773 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
5774 </para>
5775 </section>
5776
5777 <section id='post-installation-scripts'>
5778 <title>Post-Installation Scripts</title>
5779
5780 <para>
5781 It is very important that you make sure all
5782 post-Installation (<filename>pkg_postinst</filename>) scripts
5783 for packages that are installed into the image can be run
5784 at the time when the root filesystem is created during the
5785 build on the host system.
5786 These scripts cannot attempt to run during first-boot on the
5787 target device.
5788 With the "read-only-rootfs" feature enabled,
5789 the build system checks during root filesystem creation to make
5790 sure all post-installation scripts succeed.
5791 If any of these scripts still need to be run after the root
5792 filesystem is created, the build immediately fails.
5793 These build-time checks ensure that the build fails
5794 rather than the target device fails later during its
5795 initial boot operation.
5796 </para>
5797
5798 <para>
5799 Most of the common post-installation scripts generated by the
5800 build system for the out-of-the-box Yocto Project are engineered
5801 so that they can run during root filesystem creation
5802 (e.g. post-installation scripts for caching fonts).
5803 However, if you create and add custom scripts, you need
5804 to be sure they can be run during this file system creation.
5805 </para>
5806
5807 <para>
5808 Here are some common problems that prevent
5809 post-installation scripts from running during root filesystem
5810 creation:
5811 <itemizedlist>
5812 <listitem><para>
5813 <emphasis>Not using $D in front of absolute
5814 paths:</emphasis>
5815 The build system defines
5816 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
5817 when the root filesystem is created.
5818 Furthermore, <filename>$D</filename> is blank when the
5819 script is run on the target device.
5820 This implies two purposes for <filename>$D</filename>:
5821 ensuring paths are valid in both the host and target
5822 environments, and checking to determine which
5823 environment is being used as a method for taking
5824 appropriate actions.
5825 </para></listitem>
5826 <listitem><para>
5827 <emphasis>Attempting to run processes that are
5828 specific to or dependent on the target
5829 architecture:</emphasis>
5830 You can work around these attempts by using native
5831 tools to accomplish the same tasks, or
5832 by alternatively running the processes under QEMU,
5833 which has the <filename>qemu_run_binary</filename>
5834 function.
5835 For more information, see the
5836 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
5837 class.</para></listitem>
5838 </itemizedlist>
5839 </para>
5840 </section>
5841
5842 <section id='areas-with-write-access'>
5843 <title>Areas With Write Access</title>
5844
5845 <para>
5846 With the "read-only-rootfs" feature enabled,
5847 any attempt by the target to write to the root filesystem at
5848 runtime fails.
5849 Consequently, you must make sure that you configure processes
5850 and applications that attempt these types of writes do so
5851 to directories with write access (e.g.
5852 <filename>/tmp</filename> or <filename>/var/run</filename>).
5853 </para>
5854 </section>
5855 </section>
5856
5857 <section id="performing-automated-runtime-testing">
5858 <title>Performing Automated Runtime Testing</title>
5859
5860 <para>
5861 The OpenEmbedded build system makes available a series of automated
5862 tests for images to verify runtime functionality.
5863 You can run these tests on either QEMU or actual target hardware.
5864 Tests are written in Python making use of the
5865 <filename>unittest</filename> module, and the majority of them
5866 run commands on the target system over SSH.
5867 This section describes how you set up the environment to use these
5868 tests, run available tests, and write and add your own tests.
5869 </para>
5870
5871 <section id='enabling-tests'>
5872 <title>Enabling Tests</title>
5873
5874 <para>
5875 Depending on whether you are planning on running tests using
5876 QEMU or on running them on the hardware, you have to take
5877 different steps to enable the tests.
5878 See the following subsections for information on how to
5879 enable both types of tests.
5880 </para>
5881
5882 <section id='qemu-image-enabling-tests'>
5883 <title>Enabling Runtime Tests on QEMU</title>
5884
5885 <para>
5886 In order to run tests, you need to do the following:
5887 <itemizedlist>
5888 <listitem><para><emphasis>Set up to avoid interaction
5889 with <filename>sudo</filename> for networking:</emphasis>
5890 To accomplish this, you must do one of the
5891 following:
5892 <itemizedlist>
5893 <listitem><para>Add
5894 <filename>NOPASSWD</filename> for your user
5895 in <filename>/etc/sudoers</filename> either for
5896 ALL commands or just for
5897 <filename>runqemu-ifup</filename>.
5898 You must provide the full path as that can
5899 change if you are using multiple clones of the
5900 source repository.
5901 <note>
5902 On some distributions, you also need to
5903 comment out "Defaults requiretty" in
5904 <filename>/etc/sudoers</filename>.
5905 </note></para></listitem>
5906 <listitem><para>Manually configure a tap interface
5907 for your system.</para></listitem>
5908 <listitem><para>Run as root the script in
5909 <filename>scripts/runqemu-gen-tapdevs</filename>,
5910 which should generate a list of tap devices.
5911 This is the option typically chosen for
5912 Autobuilder-type environments.
5913 </para></listitem>
5914 </itemizedlist></para></listitem>
5915 <listitem><para><emphasis>Set the
5916 <filename>DISPLAY</filename> variable:</emphasis>
5917 You need to set this variable so that you have an X
5918 server available (e.g. start
5919 <filename>vncserver</filename> for a headless machine).
5920 </para></listitem>
5921 <listitem><para><emphasis>Be sure your host's firewall
5922 accepts incoming connections from
5923 192.168.7.0/24:</emphasis>
5924 Some of the tests (in particular smart tests) start an
5925 HTTP server on a random high number port, which is
5926 used to serve files to the target.
5927 The smart module serves
5928 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
5929 smart channel commands. That means your host's firewall
5930 must accept incoming connections from 192.168.7.0/24,
5931 which is the default IP range used for tap devices
5932 by <filename>runqemu</filename>.</para></listitem>
5933 </itemizedlist>
5934 </para>
5935
5936 <para>
5937 Once you start running the tests, the following happens:
5938 <itemizedlist>
5939 <listitem><para>A copy of the root filesystem is written
5940 to <filename>${WORKDIR}/testimage</filename>.
5941 </para></listitem>
5942 <listitem><para>The image is booted under QEMU using the
5943 standard <filename>runqemu</filename> script.
5944 </para></listitem>
5945 <listitem><para>A default timeout of 500 seconds occurs
5946 to allow for the boot process to reach the login prompt.
5947 You can change the timeout period by setting
5948 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
5949 in the <filename>local.conf</filename> file.
5950 </para></listitem>
5951 <listitem><para>Once the boot process is reached and the
5952 login prompt appears, the tests run.
5953 The full boot log is written to
5954 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
5955 </para></listitem>
5956 <listitem><para>Each test module loads in the order found
5957 in <filename>TEST_SUITES</filename>.
5958 You can find the full output of the commands run over
5959 SSH in
5960 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
5961 </para></listitem>
5962 <listitem><para>If no failures occur, the task running the
5963 tests ends successfully.
5964 You can find the output from the
5965 <filename>unittest</filename> in the task log at
5966 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
5967 </para></listitem>
5968 </itemizedlist>
5969 </para>
5970 </section>
5971
5972 <section id='hardware-image-enabling-tests'>
5973 <title>Enabling Runtime Tests on Hardware</title>
5974
5975 <para>
5976 The OpenEmbedded build system can run tests on real
5977 hardware, and for certain devices it can also deploy
5978 the image to be tested onto the device beforehand.
5979 </para>
5980
5981 <para>
5982 For automated deployment, a "master image" is installed
5983 onto the hardware once as part of setup.
5984 Then, each time tests are to be run, the following
5985 occurs:
5986 <orderedlist>
5987 <listitem><para>The master image is booted into and
5988 used to write the image to be tested to
5989 a second partition.
5990 </para></listitem>
5991 <listitem><para>The device is then rebooted using an
5992 external script that you need to provide.
5993 </para></listitem>
5994 <listitem><para>The device boots into the image to be
5995 tested.
5996 </para></listitem>
5997 </orderedlist>
5998 </para>
5999
6000 <para>
6001 When running tests (independent of whether the image
6002 has been deployed automatically or not), the device is
6003 expected to be connected to a network on a
6004 pre-determined IP address.
6005 You can either use static IP addresses written into
6006 the image, or set the image to use DHCP and have your
6007 DHCP server on the test network assign a known IP address
6008 based on the MAC address of the device.
6009 </para>
6010
6011 <para>
6012 In order to run tests on hardware, you need to set
6013 <filename>TEST_TARGET</filename> to an appropriate value.
6014 For QEMU, you do not have to change anything, the default
6015 value is "QemuTarget".
6016 For running tests on hardware, two options exist:
6017 "SimpleRemoteTarget" and "GummibootTarget".
6018 <itemizedlist>
6019 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
6020 Choose "SimpleRemoteTarget" if you are going to
6021 run tests on a target system that is already
6022 running the image to be tested and is available
6023 on the network.
6024 You can use "SimpleRemoteTarget" in conjunction
6025 with either real hardware or an image running
6026 within a separately started QEMU or any
6027 other virtual machine manager.
6028 </para></listitem>
6029 <listitem><para><emphasis>"GummibootTarget":</emphasis>
6030 Choose "GummibootTarget" if your hardware is
6031 an EFI-based machine with
6032 <filename>gummiboot</filename> as bootloader and
6033 <filename>core-image-testmaster</filename>
6034 (or something similar) is installed.
6035 Also, your hardware under test must be in a
6036 DHCP-enabled network that gives it the same IP
6037 address for each reboot.</para>
6038 <para>If you choose "GummibootTarget", there are
6039 additional requirements and considerations.
6040 See the
6041 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
6042 section, which follows, for more information.
6043 </para></listitem>
6044 </itemizedlist>
6045 </para>
6046 </section>
6047
6048 <section id='selecting-gummiboottarget'>
6049 <title>Selecting GummibootTarget</title>
6050
6051 <para>
6052 If you did not set <filename>TEST_TARGET</filename> to
6053 "GummibootTarget", then you do not need any information
6054 in this section.
6055 You can skip down to the
6056 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
6057 section.
6058 </para>
6059
6060 <para>
6061 If you did set <filename>TEST_TARGET</filename> to
6062 "GummibootTarget", you also need to perform a one-time
6063 setup of your master image by doing the following:
6064 <orderedlist>
6065 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
6066 Be sure that <filename>EFI_PROVIDER</filename>
6067 is as follows:
6068 <literallayout class='monospaced'>
6069 EFI_PROVIDER = "gummiboot"
6070 </literallayout>
6071 </para></listitem>
6072 <listitem><para><emphasis>Build the master image:</emphasis>
6073 Build the <filename>core-image-testmaster</filename>
6074 image.
6075 The <filename>core-image-testmaster</filename>
6076 recipe is provided as an example for a
6077 "master" image and you can customize the image
6078 recipe as you would any other recipe.
6079 </para>
6080 <para>Here are the image recipe requirements:
6081 <itemizedlist>
6082 <listitem><para>Inherits
6083 <filename>core-image</filename>
6084 so that kernel modules are installed.
6085 </para></listitem>
6086 <listitem><para>Installs normal linux utilities
6087 not busybox ones (e.g.
6088 <filename>bash</filename>,
6089 <filename>coreutils</filename>,
6090 <filename>tar</filename>,
6091 <filename>gzip</filename>, and
6092 <filename>kmod</filename>).
6093 </para></listitem>
6094 <listitem><para>Uses a custom
6095 initramfs image with a custom installer.
6096 A normal image that you can install usually
6097 creates a single rootfs partition.
6098 This image uses another installer that
6099 creates a specific partition layout.
6100 Not all Board Support Packages (BSPs)
6101 can use an installer.
6102 For such cases, you need to manually create
6103 the following partition layout on the
6104 target:
6105 <itemizedlist>
6106 <listitem><para>First partition mounted
6107 under <filename>/boot</filename>,
6108 labeled "boot".
6109 </para></listitem>
6110 <listitem><para>The main rootfs
6111 partition where this image gets
6112 installed, which is mounted under
6113 <filename>/</filename>.
6114 </para></listitem>
6115 <listitem><para>Another partition
6116 labeled "testrootfs" where test
6117 images get deployed.
6118 </para></listitem>
6119 </itemizedlist>
6120 </para></listitem>
6121 </itemizedlist>
6122 </para></listitem>
6123 <listitem><para><emphasis>Install image:</emphasis>
6124 Install the image that you just built on the target
6125 system.
6126 </para></listitem>
6127 </orderedlist>
6128 </para>
6129
6130 <para>
6131 The final thing you need to do when setting
6132 <filename>TEST_TARGET</filename> to "GummibootTarget" is
6133 to set up the test image:
6134 <orderedlist>
6135 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
6136 Make sure you have the following statements in
6137 your <filename>local.conf</filename> file:
6138 <literallayout class='monospaced'>
6139 IMAGE_FSTYPES += "tar.gz"
6140 INHERIT += "testimage"
6141 TEST_TARGET = "GummibootTarget"
6142 TEST_TARGET_IP = "192.168.2.3"
6143 </literallayout>
6144 </para></listitem>
6145 <listitem><para><emphasis>Build your test image:</emphasis>
6146 Use BitBake to build the image:
6147 <literallayout class='monospaced'>
6148 $ bitbake core-image-sato
6149 </literallayout>
6150 </para></listitem>
6151 </orderedlist>
6152 </para>
6153
6154 <para>
6155 Here is some additional information regarding running
6156 "GummibootTarget" as your test target:
6157 <itemizedlist>
6158 <listitem><para>
6159 You can use
6160 <filename>TEST_POWERCONTROL_CMD</filename>
6161 together with
6162 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
6163 as a command that runs on the host and does power
6164 cycling.
6165 The test code passes one argument to that command:
6166 off, on or cycle (off then on).
6167 Here is an example that could appear in your
6168 <filename>local.conf</filename> file:
6169 <literallayout class='monospaced'>
6170 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
6171 </literallayout>
6172 In this example, the expect script does the
6173 following:
6174 <literallayout class='monospaced'>
6175 ssh test@10.11.12.1 "pyctl nuc1 &lt;arg&gt;"
6176 </literallayout>
6177 It then runs a Python script that controls power
6178 for a label called <filename>nuc1</filename>.
6179 <note>
6180 You need to customize
6181 <filename>TEST_POWERCONTROL_CMD</filename>
6182 and
6183 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
6184 for your own setup.
6185 The one requirement is that it accepts
6186 "on", "off", and "cycle" as the last argument.
6187 </note>
6188 </para></listitem>
6189 <listitem><para>
6190 When no command is defined, it connects to the
6191 device over SSH and uses the classic reboot command
6192 to reboot the device.
6193 Classic reboot is fine as long as the machine
6194 actually reboots (i.e. the SSH test has not
6195 failed).
6196 It is useful for scenarios where you have a simple
6197 setup, typically with a single board, and where
6198 some manual interaction is okay from time to time.
6199 </para></listitem>
6200 </itemizedlist>
6201 </para>
6202 </section>
6203 </section>
6204
6205 <section id="qemu-image-running-tests">
6206 <title>Running Tests</title>
6207
6208 <para>
6209 You can start the tests automatically or manually:
6210 <itemizedlist>
6211 <listitem><para><emphasis>Automatically running tests:</emphasis>
6212 To run the tests automatically after the
6213 OpenEmbedded build system successfully creates an image,
6214 first set the
6215 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
6216 variable to "1" in your <filename>local.conf</filename>
6217 file in the
6218 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6219 <literallayout class='monospaced'>
6220 TEST_IMAGE = "1"
6221 </literallayout>
6222 Next, build your image.
6223 If the image successfully builds, the tests will be
6224 run:
6225 <literallayout class='monospaced'>
6226 bitbake core-image-sato
6227 </literallayout></para></listitem>
6228 <listitem><para><emphasis>Manually running tests:</emphasis>
6229 To manually run the tests, first globally inherit the
6230 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
6231 class by editing your <filename>local.conf</filename>
6232 file:
6233 <literallayout class='monospaced'>
6234 INHERIT += "testimage"
6235 </literallayout>
6236 Next, use BitBake to run the tests:
6237 <literallayout class='monospaced'>
6238 bitbake -c testimage &lt;image&gt;
6239 </literallayout></para></listitem>
6240 </itemizedlist>
6241 </para>
6242
6243 <para>
6244 All test files reside in
6245 <filename>meta/lib/oeqa/runtime</filename> in the
6246 <link linkend='source-directory'>Source Directory</link>.
6247 A test name maps directly to a Python module.
6248 Each test module may contain a number of individual tests.
6249 Tests are usually grouped together by the area
6250 tested (e.g tests for systemd reside in
6251 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
6252 </para>
6253
6254 <para>
6255 You can add tests to any layer provided you place them in the
6256 proper area and you extend
6257 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6258 in the <filename>local.conf</filename> file as normal.
6259 Be sure that tests reside in
6260 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
6261 <note>
6262 Be sure that module names do not collide with module names
6263 used in the default set of test modules in
6264 <filename>meta/lib/oeqa/runtime</filename>.
6265 </note>
6266 </para>
6267
6268 <para>
6269 You can change the set of tests run by appending or overriding
6270 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
6271 variable in <filename>local.conf</filename>.
6272 Each name in <filename>TEST_SUITES</filename> represents a
6273 required test for the image.
6274 Test modules named within <filename>TEST_SUITES</filename>
6275 cannot be skipped even if a test is not suitable for an image
6276 (e.g. running the RPM tests on an image without
6277 <filename>rpm</filename>).
6278 Appending "auto" to <filename>TEST_SUITES</filename> causes the
6279 build system to try to run all tests that are suitable for the
6280 image (i.e. each test module may elect to skip itself).
6281 </para>
6282
6283 <para>
6284 The order you list tests in <filename>TEST_SUITES</filename>
6285 is important and influences test dependencies.
6286 Consequently, tests that depend on other tests should be added
6287 after the test on which they depend.
6288 For example, since the <filename>ssh</filename> test
6289 depends on the
6290 <filename>ping</filename> test, "ssh" needs to come after
6291 "ping" in the list.
6292 The test class provides no re-ordering or dependency handling.
6293 <note>
6294 Each module can have multiple classes with multiple test
6295 methods.
6296 And, Python <filename>unittest</filename> rules apply.
6297 </note>
6298 </para>
6299
6300 <para>
6301 Here are some things to keep in mind when running tests:
6302 <itemizedlist>
6303 <listitem><para>The default tests for the image are defined
6304 as:
6305 <literallayout class='monospaced'>
6306 DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
6307 </literallayout></para></listitem>
6308 <listitem><para>Add your own test to the list of the
6309 by using the following:
6310 <literallayout class='monospaced'>
6311 TEST_SUITES_append = " mytest"
6312 </literallayout></para></listitem>
6313 <listitem><para>Run a specific list of tests as follows:
6314 <literallayout class='monospaced'>
6315 TEST_SUITES = "test1 test2 test3"
6316 </literallayout>
6317 Remember, order is important.
6318 Be sure to place a test that is dependent on another test
6319 later in the order.</para></listitem>
6320 </itemizedlist>
6321 </para>
6322 </section>
6323
6324 <section id="exporting-tests">
6325 <title>Exporting Tests</title>
6326
6327 <para>
6328 You can export tests so that they can run independently of
6329 the build system.
6330 Exporting tests is required if you want to be able to hand
6331 the test execution off to a scheduler.
6332 You can only export tests that are defined in
6333 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
6334 </para>
6335
6336 <para>
6337 If you image is already built, make sure the following are set
6338 in your <filename>local.conf</filename> file.
6339 Be sure to provide the IP address you need:
6340 <literallayout class='monospaced'>
6341 TEST_EXPORT_ONLY = "1"
6342 TEST_TARGET = "simpleremote"
6343 TEST_TARGET_IP = "192.168.7.2"
6344 TEST_SERVER_IP = "192.168.7.1"
6345 </literallayout>
6346 You can then export the tests with the following:
6347 <literallayout class='monospaced'>
6348 $ bitbake core-image-sato -c testimage
6349 </literallayout>
6350 Exporting the tests places them in the
6351 <link linkend='build-directory'>Build Directory</link> in
6352 <filename>tmp/testimage/core-image-sato</filename>, which
6353 is controlled by the
6354 <filename>TEST_EXPORT_DIR</filename> variable.
6355 </para>
6356
6357 <para>
6358 The exported data (i.e. <filename>testdata.json</filename>)
6359 contains paths to the Build Directory.
6360 Thus, the contents of the directory can be moved
6361 to another machine as long as you update some paths in the
6362 JSON.
6363 Usually you only care about the
6364 ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests
6365 are enabled).
6366 Consequently, running the tests on other machine
6367 means that you have to move the contents and call
6368 <filename>runexported</filename> with "--deploy-dir PATH:
6369 ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json
6370 runexported.py accepts other arguments as well, see --help.
6371 </para>
6372
6373 <para>
6374 You can now run the tests outside of the build environment:
6375 <literallayout class='monospaced'>
6376 $ cd tmp/testimage/core-image-sato
6377 $ ./runexported.py testdata.json
6378 </literallayout>
6379 <note>
6380 This "export" feature does not deploy or boot the target
6381 image.
6382 Your target (be it a Qemu or hardware one)
6383 has to already be up and running when you call
6384 <filename>runexported.py</filename>
6385 </note>
6386 </para>
6387 </section>
6388
6389 <section id="qemu-image-writing-new-tests">
6390 <title>Writing New Tests</title>
6391
6392 <para>
6393 As mentioned previously, all new test files need to be in the
6394 proper place for the build system to find them.
6395 New tests for additional functionality outside of the core
6396 should be added to the layer that adds the functionality, in
6397 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
6398 long as
6399 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6400 is extended in the layer's
6401 <filename>layer.conf</filename> file as normal).
6402 Just remember that filenames need to map directly to test
6403 (module) names and that you do not use module names that
6404 collide with existing core tests.
6405 </para>
6406
6407 <para>
6408 To create a new test, start by copying an existing module
6409 (e.g. <filename>syslog.py</filename> or
6410 <filename>gcc.py</filename> are good ones to use).
6411 Test modules can use code from
6412 <filename>meta/lib/oeqa/utils</filename>, which are helper
6413 classes.
6414 </para>
6415
6416 <note>
6417 Structure shell commands such that you rely on them and they
6418 return a single code for success.
6419 Be aware that sometimes you will need to parse the output.
6420 See the <filename>df.py</filename> and
6421 <filename>date.py</filename> modules for examples.
6422 </note>
6423
6424 <para>
6425 You will notice that all test classes inherit
6426 <filename>oeRuntimeTest</filename>, which is found in
6427 <filename>meta/lib/oetest.py</filename>.
6428 This base class offers some helper attributes, which are
6429 described in the following sections:
6430 </para>
6431
6432 <section id='qemu-image-writing-tests-class-methods'>
6433 <title>Class Methods</title>
6434
6435 <para>
6436 Class methods are as follows:
6437 <itemizedlist>
6438 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
6439 Returns "True" if <filename>pkg</filename> is in the
6440 installed package list of the image, which is based
6441 on the manifest file that is generated during the
6442 <filename>do.rootfs</filename> task.
6443 </para></listitem>
6444 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
6445 Returns "True" if the feature is in
6446 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6447 or
6448 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
6449 </para></listitem>
6450 </itemizedlist>
6451 </para>
6452 </section>
6453
6454 <section id='qemu-image-writing-tests-class-attributes'>
6455 <title>Class Attributes</title>
6456
6457 <para>
6458 Class attributes are as follows:
6459 <itemizedlist>
6460 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
6461 Equals "ps -ef" if <filename>procps</filename> is
6462 installed in the image.
6463 Otherwise, <filename>pscmd</filename> equals
6464 "ps" (busybox).
6465 </para></listitem>
6466 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
6467 The called text context, which gives access to the
6468 following attributes:
6469 <itemizedlist>
6470 <listitem><para><emphasis><filename>d</filename>:</emphasis>
6471 The BitBake datastore, which allows you to
6472 use stuff such as
6473 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
6474 </para></listitem>
6475 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
6476 Used internally.
6477 The tests do not need these.
6478 </para></listitem>
6479 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
6480 The absolute path to
6481 <filename>meta/lib/oeqa/runtime/files</filename>,
6482 which contains helper files for tests meant
6483 for copying on the target such as small
6484 files written in C for compilation.
6485 </para></listitem>
6486 <listitem><para><emphasis><filename>target</filename>:</emphasis>
6487 The target controller object used to deploy
6488 and start an image on a particular target
6489 (e.g. QemuTarget, SimpleRemote, and
6490 GummibootTarget).
6491 Tests usually use the following:
6492 <itemizedlist>
6493 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
6494 The target's IP address.
6495 </para></listitem>
6496 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
6497 The host's IP address, which is
6498 usually used by the "smart" test
6499 suite.
6500 </para></listitem>
6501 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
6502 The single, most used method.
6503 This command is a wrapper for:
6504 <filename>ssh root@host "cmd"</filename>.
6505 The command returns a tuple:
6506 (status, output), which are what
6507 their names imply - the return code
6508 of 'cmd' and whatever output
6509 it produces.
6510 The optional timeout argument
6511 represents the number of seconds the
6512 test should wait for 'cmd' to
6513 return.
6514 If the argument is "None", the
6515 test uses the default instance's
6516 timeout period, which is 300
6517 seconds.
6518 If the argument is "0", the test
6519 runs until the command returns.
6520 </para></listitem>
6521 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
6522 <filename>scp localpath root@ip:remotepath</filename>.
6523 </para></listitem>
6524 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
6525 <filename>scp root@host:remotepath localpath</filename>.
6526 </para></listitem>
6527 </itemizedlist></para></listitem>
6528 </itemizedlist></para></listitem>
6529 </itemizedlist>
6530 </para>
6531 </section>
6532
6533 <section id='qemu-image-writing-tests-instance-attributes'>
6534 <title>Instance Attributes</title>
6535
6536 <para>
6537 A single instance attribute exists, which is
6538 <filename>target</filename>.
6539 The <filename>target</filename> instance attribute is
6540 identical to the class attribute of the same name, which
6541 is described in the previous section.
6542 This attribute exists as both an instance and class
6543 attribute so tests can use
6544 <filename>self.target.run(cmd)</filename> in instance
6545 methods instead of
6546 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
6547 </para>
6548 </section>
6549 </section>
6550 </section>
6551
6552 <section id="platdev-gdb-remotedebug">
6553 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
6554
6555 <para>
6556 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
6557 It also allows you to perform post-mortem style analysis of program crashes.
6558 GDB is available as a package within the Yocto Project and is
6559 installed in SDK images by default.
6560 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
6561 in the Yocto Project Reference Manual for a description of these images.
6562 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
6563 </para>
6564
6565 <tip>
6566 For best results, install DBG (<filename>-dbg</filename>) packages
6567 for the applications you are going to debug.
6568 Doing so makes extra debug symbols available that give you more
6569 meaningful output.
6570 </tip>
6571
6572 <para>
6573 Sometimes, due to memory or disk space constraints, it is not possible
6574 to use GDB directly on the remote target to debug applications.
6575 These constraints arise because GDB needs to load the debugging information and the
6576 binaries of the process being debugged.
6577 Additionally, GDB needs to perform many computations to locate information such as function
6578 names, variable names and values, stack traces and so forth - even before starting the
6579 debugging process.
6580 These extra computations place more load on the target system and can alter the
6581 characteristics of the program being debugged.
6582 </para>
6583
6584 <para>
6585 To help get past the previously mentioned constraints, you can use Gdbserver.
6586 Gdbserver runs on the remote target and does not load any debugging information
6587 from the debugged process.
6588 Instead, a GDB instance processes the debugging information that is run on a
6589 remote computer - the host GDB.
6590 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
6591 program, as well as read or write memory regions of that debugged program.
6592 All the debugging information loaded and processed as well
6593 as all the heavy debugging is done by the host GDB.
6594 Offloading these processes gives the Gdbserver running on the target a chance to remain
6595 small and fast.
6596 </para>
6597
6598 <para>
6599 Because the host GDB is responsible for loading the debugging information and
6600 for doing the necessary processing to make actual debugging happen, the
6601 user has to make sure the host can access the unstripped binaries complete
6602 with their debugging information and also be sure the target is compiled with no optimizations.
6603 The host GDB must also have local access to all the libraries used by the
6604 debugged program.
6605 Because Gdbserver does not need any local debugging information, the binaries on
6606 the remote target can remain stripped.
6607 However, the binaries must also be compiled without optimization
6608 so they match the host's binaries.
6609 </para>
6610
6611 <para>
6612 To remain consistent with GDB documentation and terminology, the binary being debugged
6613 on the remote target machine is referred to as the "inferior" binary.
6614 For documentation on GDB see the
6615 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
6616 </para>
6617
6618 <para>
6619 The remainder of this section describes the steps you need to take
6620 to debug using the GNU project debugger.
6621 </para>
6622
6623 <section id='platdev-gdb-remotedebug-setup'>
6624 <title>Set Up the Cross-Development Debugging Environment</title>
6625
6626 <para>
6627 Before you can initiate a remote debugging session, you need
6628 to be sure you have set up the cross-development environment,
6629 toolchain, and sysroot.
6630 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
6631 chapter of the Yocto Project Application Developer's Guide
6632 describes this process.
6633 Be sure you have read that chapter and have set up
6634 your environment.
6635 </para>
6636 </section>
6637
6638 <section id="platdev-gdb-remotedebug-launch-gdbserver">
6639 <title>Launch Gdbserver on the Target</title>
6640
6641 <para>
6642 Make sure Gdbserver is installed on the target.
6643 If it is not, install the package
6644 <filename>gdbserver</filename>, which needs the
6645 <filename>libthread-db1</filename> package.
6646 </para>
6647
6648 <para>
6649 Here is an example that when entered from the host
6650 connects to the target and launches Gdbserver in order to
6651 "debug" a binary named <filename>helloworld</filename>:
6652 <literallayout class='monospaced'>
6653 $ gdbserver localhost:2345 /usr/bin/helloworld
6654 </literallayout>
6655 Gdbserver should now be listening on port 2345 for debugging
6656 commands coming from a remote GDB process that is running on
6657 the host computer.
6658 Communication between Gdbserver and the host GDB are done
6659 using TCP.
6660 To use other communication protocols, please refer to the
6661 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
6662 </para>
6663 </section>
6664
6665 <section id="platdev-gdb-remotedebug-launch-gdb">
6666 <title>Launch GDB on the Host Computer</title>
6667
6668 <para>
6669 Running GDB on the host computer takes a number of stages, which
6670 this section describes.
6671 </para>
6672
6673 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
6674 <title>Build the Cross-GDB Package</title>
6675 <para>
6676 A suitable GDB cross-binary is required that runs on your
6677 host computer but also knows about the the ABI of the
6678 remote target.
6679 You can get this binary from the
6680 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
6681 Here is an example where the toolchain has been installed
6682 in the default directory
6683 <filename>/opt/poky/&DISTRO;</filename>:
6684 <literallayout class='monospaced'>
6685 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
6686 </literallayout>
6687 where <filename>arm</filename> is the target architecture
6688 and <filename>linux-gnueabi</filename> is the target ABI.
6689 </para>
6690
6691 <para>
6692 Alternatively, you can use BitBake to build the
6693 <filename>gdb-cross</filename> binary.
6694 Here is an example:
6695 <literallayout class='monospaced'>
6696 $ bitbake gdb-cross
6697 </literallayout>
6698 Once the binary is built, you can find it here:
6699 <literallayout class='monospaced'>
6700 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
6701 </literallayout>
6702 </para>
6703 </section>
6704
6705 <section id='create-the-gdb-initialization-file'>
6706 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
6707
6708 <para>
6709 Aside from the GDB cross-binary, you also need a GDB
6710 initialization file in the same top directory in which
6711 your binary resides.
6712 When you start GDB on your host development system, GDB
6713 finds this initialization file and executes all the
6714 commands within.
6715 For information on the <filename>.gdbinit</filename>, see
6716 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
6717 which is maintained by
6718 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
6719 </para>
6720
6721 <para>
6722 You need to add a statement in the
6723 <filename>.gdbinit</filename> file that points to your
6724 root filesystem.
6725 Here is an example that points to the root filesystem for
6726 an ARM-based target device:
6727 <literallayout class='monospaced'>
6728 set sysroot /home/jzhang/sysroot_arm
6729 </literallayout>
6730 </para>
6731 </section>
6732
6733 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
6734 <title>Launch the Host GDB</title>
6735
6736 <para>
6737 Before launching the host GDB, you need to be sure
6738 you have sourced the cross-debugging environment script,
6739 which if you installed the root filesystem in the default
6740 location is at <filename>/opt/poky/&DISTRO;</filename>
6741 and begins with the string "environment-setup".
6742 For more information, see the
6743 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
6744 section in the Yocto Project Application Developer's
6745 Guide.
6746 </para>
6747
6748 <para>
6749 Finally, switch to the directory where the binary resides
6750 and run the <filename>cross-gdb</filename> binary.
6751 Provide the binary file you are going to debug.
6752 For example, the following command continues with the
6753 example used in the previous section by loading
6754 the <filename>helloworld</filename> binary as well as the
6755 debugging information:
6756 <literallayout class='monospaced'>
6757 $ arm-poky-linux-gnuabi-gdb helloworld
6758 </literallayout>
6759 The commands in your <filename>.gdbinit</filename> execute
6760 and the GDB prompt appears.
6761 </para>
6762 </section>
6763 </section>
6764
6765 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
6766 <title>Connect to the Remote GDB Server</title>
6767
6768 <para>
6769 From the target, you need to connect to the remote GDB
6770 server that is running on the host.
6771 You need to specify the remote host and port.
6772 Here is the command continuing with the example:
6773 <literallayout class='monospaced'>
6774 target remote 192.168.7.2:2345
6775 </literallayout>
6776 </para>
6777 </section>
6778
6779 <section id="platdev-gdb-remotedebug-launch-gdb-using">
6780 <title>Use the Debugger</title>
6781
6782 <para>
6783 You can now proceed with debugging as normal - as if you were debugging
6784 on the local machine.
6785 For example, to instruct GDB to break in the "main" function and then
6786 continue with execution of the inferior binary use the following commands
6787 from within GDB:
6788 <literallayout class='monospaced'>
6789 (gdb) break main
6790 (gdb) continue
6791 </literallayout>
6792 </para>
6793
6794 <para>
6795 For more information about using GDB, see the project's online documentation at
6796 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
6797 </para>
6798 </section>
6799 </section>
6800
6801 <section id="examining-builds-using-toaster">
6802 <title>Examining Builds Using the Toaster API</title>
6803
6804 <para>
6805 Toaster is an Application Programming Interface (API) and
6806 web-based interface to the OpenEmbedded build system, which uses
6807 BitBake.
6808 Both interfaces are based on a Representational State Transfer
6809 (REST) API that queries for and returns build information using
6810 <filename>GET</filename> and <filename>JSON</filename>.
6811 These types of search operations retrieve sets of objects from
6812 a datastore used to collect build information.
6813 The results contain all the data for the objects being returned.
6814 You can order the results of the search by key and the search
6815 parameters are consistent for all object types.
6816 </para>
6817
6818 <para>
6819 Using the interfaces you can do the following:
6820 <itemizedlist>
6821 <listitem><para>See information about the tasks executed
6822 and reused during the build.</para></listitem>
6823 <listitem><para>See what is built (recipes and
6824 packages) and what packages were installed into the final
6825 image.</para></listitem>
6826 <listitem><para>See performance-related information such
6827 as build time, CPU usage, and disk I/O.</para></listitem>
6828 <listitem><para>Examine error, warning and trace messages
6829 to aid in debugging.</para></listitem>
6830 </itemizedlist>
6831 </para>
6832
6833 <note>
6834 <para>This release of Toaster provides you with information
6835 about a BitBake run.
6836 The tool does not allow you to configure and launch a build.
6837 However, future development includes plans to integrate the
6838 configuration and build launching capabilities of
6839 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
6840 </para>
6841 <para>For more information on using Hob to build an image,
6842 see the
6843 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
6844 section.</para>
6845 </note>
6846
6847 <para>
6848 The remainder of this section describes what you need to have in
6849 place to use Toaster, how to start it, use it, and stop it.
6850 For additional information on installing and running Toaster, see the
6851 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
6852 section of the "Toaster" wiki page.
6853 For complete information on the API and its search operation
6854 URI, parameters, and responses, see the
6855 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
6856 Wiki page.
6857 </para>
6858
6859 <section id='starting-toaster'>
6860 <title>Starting Toaster</title>
6861
6862 <para>
6863 Getting set up to use and start Toaster is simple.
6864 First, be sure you have met the following requirements:
6865 <itemizedlist>
6866 <listitem><para>You have set up your
6867 <link linkend='source-directory'>Source Directory</link>
6868 by cloning the upstream <filename>poky</filename>
6869 repository.
6870 See the
6871 <link linkend='local-yp-release'>Yocto Project Release</link>
6872 item for information on how to set up the Source
6873 Directory.</para></listitem>
6874 <listitem><para>Be sure your build machine has
6875 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
6876 version 1.5 installed.</para></listitem>
6877 <listitem><para>Make sure that port 8000 and 8200 are
6878 free (i.e. they have no servers on them).
6879 </para></listitem>
6880 </itemizedlist>
6881 </para>
6882
6883 <para>
6884 Once you have met the requirements, follow these steps to
6885 start Toaster running in the background of your shell:
6886 <orderedlist>
6887 <listitem><para><emphasis>Set up your build environment:</emphasis>
6888 Source a build environment script (i.e.
6889 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
6890 or
6891 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
6892 </para></listitem>
6893 <listitem><para><emphasis>Start Toaster:</emphasis>
6894 Start the Toaster service using this
6895 command from within your
6896 <link linkend='build-directory'>Build Directory</link>:
6897 <literallayout class='monospaced'>
6898 $ source toaster start
6899 </literallayout></para></listitem>
6900 <note>
6901 The Toaster must be started and running in order
6902 for it to collect data.
6903 </note>
6904 </orderedlist>
6905 </para>
6906
6907 <para>
6908 When Toaster starts, it creates some additional files in your
6909 Build Directory.
6910 Deleting these files will cause you to lose data or interrupt
6911 Toaster:
6912 <itemizedlist>
6913 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
6914 Toaster's database file.</para></listitem>
6915 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
6916 The log file of the web server.</para></listitem>
6917 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
6918 The log file of the user interface component.
6919 </para></listitem>
6920 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
6921 The PID of the web server.</para></listitem>
6922 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
6923 The PID of the DSI data bridge.</para></listitem>
6924 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
6925 The BitBake server's log file.</para></listitem>
6926 </itemizedlist>
6927 </para>
6928 </section>
6929
6930 <section id='using-toaster'>
6931 <title>Using Toaster</title>
6932
6933 <para>
6934 Once Toaster is running, it logs information for any BitBake
6935 run from your Build Directory.
6936 This logging is automatic.
6937 All you need to do is access and use the information.
6938 </para>
6939
6940 <para>
6941 You access the information one of two ways:
6942 <itemizedlist>
6943 <listitem><para>Open a Browser and enter
6944 <filename>http://localhost:8000</filename>
6945 for the URL.
6946 </para></listitem>
6947 <listitem><para>Use the <filename>xdg-open</filename>
6948 tool from the shell and pass it the same URL.
6949 </para></listitem>
6950 </itemizedlist>
6951 Either method opens the home page for the Toaster interface.
6952 </para>
6953
6954 <note><title>Notes</title>
6955 <para>
6956 For information on how to delete information from the Toaster
6957 database, see the
6958 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
6959 wiki page.
6960 </para>
6961
6962 <para>
6963 For information on how to set up an instance of Toaster on
6964 a remote host, see the
6965 <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>
6966 wiki page.
6967 </para>
6968 </note>
6969 </section>
6970
6971 <section id='examining-toaster-data'>
6972 <title>Examining Toaster Data</title>
6973
6974 <para>
6975 The Toaster database is persistent regardless of whether you
6976 start or stop the service.
6977 </para>
6978
6979 <para>
6980 Toaster's interface shows you a list of builds
6981 (successful and unsuccessful) for which it has data.
6982 You can click on any build to see related information.
6983 This information includes configuration details, information
6984 about tasks, all recipes and packages built and their
6985 dependencies, packages and their directory structure as
6986 installed in your final image,
6987 execution time, CPU usage and disk I/O per task.
6988 </para>
6989
6990 <para>
6991 For details on the interface, see the
6992 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
6993 </para>
6994 </section>
6995
6996 <section id='stopping-toaster'>
6997 <title>Stopping Toaster</title>
6998
6999 <para>
7000 Stop the Toaster service with the following command
7001 from with the
7002 <link linkend='build-directory'>Build Directory</link>:
7003 <literallayout class='monospaced'>
7004 $ source toaster stop
7005 </literallayout>
7006 The service stops but the Toaster database remains persistent.
7007 </para>
7008 </section>
7009 </section>
7010
7011 <section id="platdev-oprofile">
7012 <title>Profiling with OProfile</title>
7013
7014 <para>
7015 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
7016 statistical profiler well suited for finding performance
7017 bottlenecks in both user-space software and in the kernel.
7018 This profiler provides answers to questions like "Which functions does my application spend
7019 the most time in when doing X?"
7020 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
7021 applications on target hardware straight forward.
7022 <note>
7023 For more information on how to set up and run OProfile, see the
7024 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
7025 section in the Yocto Project Profiling and Tracing Manual.
7026 </note>
7027 </para>
7028
7029 <para>
7030 To use OProfile, you need an image that has OProfile installed.
7031 The easiest way to do this is with "tools-profile" in the
7032 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
7033 You also need debugging symbols to be available on the system where the analysis
7034 takes place.
7035 You can gain access to the symbols by using "dbg-pkgs" in the
7036 <filename>IMAGE_FEATURES</filename> variable or by
7037 installing the appropriate DBG (<filename>-dbg</filename>) packages.
7038 </para>
7039
7040 <para>
7041 For successful call graph analysis, the binaries must preserve the frame
7042 pointer register and should also be compiled with the
7043 <filename>-fno-omit-framepointer</filename> flag.
7044 You can achieve this by setting the
7045 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
7046 variable with the following options:
7047 <literallayout class='monospaced'>
7048 -fexpensive-optimizations
7049 -fno-omit-framepointer
7050 -frename-registers
7051 -O2
7052 </literallayout>
7053 You can also achieve it by setting the
7054 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
7055 variable to "1" in the <filename>local.conf</filename> configuration file.
7056 If you use the <filename>DEBUG_BUILD</filename> variable,
7057 you also add extra debugging information that can make the debug
7058 packages large.
7059 </para>
7060
7061 <section id="platdev-oprofile-target">
7062 <title>Profiling on the Target</title>
7063
7064 <para>
7065 Using OProfile, you can perform all the profiling work on the target device.
7066 A simple OProfile session might look like the following:
7067 </para>
7068
7069 <para>
7070 <literallayout class='monospaced'>
7071 # opcontrol --reset
7072 # opcontrol --start --separate=lib --no-vmlinux -c 5
7073 .
7074 .
7075 [do whatever is being profiled]
7076 .
7077 .
7078 # opcontrol --stop
7079 $ opreport -cl
7080 </literallayout>
7081 </para>
7082
7083 <para>
7084 In this example, the <filename>reset</filename> command clears any previously profiled data.
7085 The next command starts OProfile.
7086 The options used when starting the profiler separate dynamic library data
7087 within applications, disable kernel profiling, and enable callgraphing up to
7088 five levels deep.
7089 <note>
7090 To profile the kernel, you would specify the
7091 <filename>--vmlinux=/path/to/vmlinux</filename> option.
7092 The <filename>vmlinux</filename> file is usually in the source directory in the
7093 <filename>/boot/</filename> directory and must match the running kernel.
7094 </note>
7095 </para>
7096
7097 <para>
7098 After you perform your profiling tasks, the next command stops the profiler.
7099 After that, you can view results with the <filename>opreport</filename> command with options
7100 to see the separate library symbols and callgraph information.
7101 </para>
7102
7103 <para>
7104 Callgraphing logs information about time spent in functions and about a function's
7105 calling function (parent) and called functions (children).
7106 The higher the callgraphing depth, the more accurate the results.
7107 However, higher depths also increase the logging overhead.
7108 Consequently, you should take care when setting the callgraphing depth.
7109 <note>
7110 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
7111 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
7112 with <filename>gcc</filename>.
7113 </note>
7114 </para>
7115
7116 <para>
7117 For more information on using OProfile, see the OProfile
7118 online documentation at
7119 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
7120 </para>
7121 </section>
7122
7123 <section id="platdev-oprofile-oprofileui">
7124 <title>Using OProfileUI</title>
7125
7126 <para>
7127 A graphical user interface for OProfile is also available.
7128 You can download and build this interface from the Yocto Project at
7129 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
7130 If the "tools-profile" image feature is selected, all necessary binaries
7131 are installed onto the target device for OProfileUI interaction.
7132 For a list of image features that ship with the Yocto Project,
7133 see the
7134 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
7135 section in the Yocto Project Reference Manual.
7136 </para>
7137
7138 <para>
7139 Even though the source directory usually includes all needed patches on the target device, you
7140 might find you need other OProfile patches for recent OProfileUI features.
7141 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
7142 OProfileUI README</ulink> for the most recent information.
7143 </para>
7144
7145 <section id="platdev-oprofile-oprofileui-online">
7146 <title>Online Mode</title>
7147
7148 <para>
7149 Using OProfile in online mode assumes a working network connection with the target
7150 hardware.
7151 With this connection, you just need to run "oprofile-server" on the device.
7152 By default, OProfile listens on port 4224.
7153 <note>
7154 You can change the port using the <filename>--port</filename> command-line
7155 option.
7156 </note>
7157 </para>
7158
7159 <para>
7160 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
7161 straight forward.
7162 You access key functionality through the buttons on the toolbar, which
7163 are duplicated in the menus.
7164 Here are the buttons:
7165 <itemizedlist>
7166 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
7167 You can also supply the IP address or hostname.</para></listitem>
7168 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
7169 </para></listitem>
7170 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
7171 </para></listitem>
7172 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
7173 downloads the data to the local host.
7174 Stopping the profiler generates the profile and displays it in the viewer.
7175 </para></listitem>
7176 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
7177 target and generates the profile, which appears in the viewer.</para></listitem>
7178 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
7179 Resetting the data removes sample information collected from previous
7180 sampling runs.
7181 Be sure you reset the data if you do not want to include old sample information.
7182 </para></listitem>
7183 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
7184 target to another directory for later examination.</para></listitem>
7185 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
7186 </para></listitem>
7187 </itemizedlist>
7188 </para>
7189
7190 <para>
7191 The client downloads the complete profile archive from
7192 the target to the host for processing.
7193 This archive is a directory that contains the sample data, the object files,
7194 and the debug information for the object files.
7195 The archive is then converted using the <filename>oparchconv</filename> script, which is
7196 included in this distribution.
7197 The script uses <filename>opimport</filename> to convert the archive from
7198 the target to something that can be processed on the host.
7199 </para>
7200
7201 <para>
7202 Downloaded archives reside in the
7203 <link linkend='build-directory'>Build Directory</link> in
7204 <filename>tmp</filename> and are cleared up when they are no longer in use.
7205 </para>
7206
7207 <para>
7208 If you wish to perform kernel profiling, you need to be sure
7209 a <filename>vmlinux</filename> file that matches the running kernel is available.
7210 In the source directory, that file is usually located in
7211 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
7212 <filename>KERNEL-version</filename> is the version of the kernel.
7213 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
7214 packages for each kernel it builds.
7215 Thus, it should just be a question of making sure a matching package is
7216 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
7217 The files are automatically installed into development and profiling images
7218 alongside OProfile.
7219 A configuration option exists within the OProfileUI settings page that you can use to
7220 enter the location of the <filename>vmlinux</filename> file.
7221 </para>
7222
7223 <para>
7224 Waiting for debug symbols to transfer from the device can be slow, and it
7225 is not always necessary to actually have them on the device for OProfile use.
7226 All that is needed is a copy of the filesystem with the debug symbols present
7227 on the viewer system.
7228 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
7229 section covers how to create such a directory within
7230 the source directory and how to use the OProfileUI Settings
7231 Dialog to specify the location.
7232 If you specify the directory, it will be used when the file checksums
7233 match those on the system you are profiling.
7234 </para>
7235 </section>
7236
7237 <section id="platdev-oprofile-oprofileui-offline">
7238 <title>Offline Mode</title>
7239
7240 <para>
7241 If network access to the target is unavailable, you can generate
7242 an archive for processing in <filename>oprofile-viewer</filename> as follows:
7243 <literallayout class='monospaced'>
7244 # opcontrol --reset
7245 # opcontrol --start --separate=lib --no-vmlinux -c 5
7246 .
7247 .
7248 [do whatever is being profiled]
7249 .
7250 .
7251 # opcontrol --stop
7252 # oparchive -o my_archive
7253 </literallayout>
7254 </para>
7255
7256 <para>
7257 In the above example, <filename>my_archive</filename> is the name of the
7258 archive directory where you would like the profile archive to be kept.
7259 After the directory is created, you can copy it to another host and load it
7260 using <filename>oprofile-viewer</filename> open functionality.
7261 If necessary, the archive is converted.
7262 </para>
7263 </section>
7264 </section>
7265 </section>
7266
7267 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
7268 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
7269
7270 <para>
7271 One of the concerns for a development organization using open source
7272 software is how to maintain compliance with various open source
7273 licensing during the lifecycle of the product.
7274 While this section does not provide legal advice or
7275 comprehensively cover all scenarios, it does
7276 present methods that you can use to
7277 assist you in meeting the compliance requirements during a software
7278 release.
7279 </para>
7280
7281 <para>
7282 With hundreds of different open source licenses that the Yocto
7283 Project tracks, it is difficult to know the requirements of each
7284 and every license.
7285 However, the requirements of the major FLOSS licenses can begin
7286 to be covered by
7287 assuming that three main areas of concern exist:
7288 <itemizedlist>
7289 <listitem><para>Source code must be provided.</para></listitem>
7290 <listitem><para>License text for the software must be
7291 provided.</para></listitem>
7292 <listitem><para>Compilation scripts and modifications to the
7293 source code must be provided.
7294 </para></listitem>
7295 </itemizedlist>
7296 There are other requirements beyond the scope of these
7297 three and the methods described in this section
7298 (e.g. the mechanism through which source code is distributed).
7299 </para>
7300
7301 <para>
7302 As different organizations have different methods of complying with
7303 open source licensing, this section is not meant to imply that
7304 there is only one single way to meet your compliance obligations,
7305 but rather to describe one method of achieving compliance.
7306 The remainder of this section describes methods supported to meet the
7307 previously mentioned three requirements.
7308 Once you take steps to meet these requirements,
7309 and prior to releasing images, sources, and the build system,
7310 you should audit all artifacts to ensure completeness.
7311 <note>
7312 The Yocto Project generates a license manifest during
7313 image creation that is located
7314 in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
7315 to assist with any audits.
7316 </note>
7317 </para>
7318
7319 <section id='providing-the-source-code'>
7320 <title>Providing the Source Code</title>
7321
7322 <para>
7323 Compliance activities should begin before you generate the
7324 final image.
7325 The first thing you should look at is the requirement that
7326 tops the list for most compliance groups - providing
7327 the source.
7328 The Yocto Project has a few ways of meeting this
7329 requirement.
7330 </para>
7331
7332 <para>
7333 One of the easiest ways to meet this requirement is
7334 to provide the entire
7335 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
7336 used by the build.
7337 This method, however, has a few issues.
7338 The most obvious is the size of the directory since it includes
7339 all sources used in the build and not just the source used in
7340 the released image.
7341 It will include toolchain source, and other artifacts, which
7342 you would not generally release.
7343 However, the more serious issue for most companies is accidental
7344 release of proprietary software.
7345 The Yocto Project provides an
7346 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
7347 class to help avoid some of these concerns.
7348 </para>
7349
7350 <para>
7351 Before you employ <filename>DL_DIR</filename> or the
7352 archiver class, you need to decide how you choose to
7353 provide source.
7354 The source archiver class can generate tarballs and SRPMs
7355 and can create them with various levels of compliance in mind.
7356 </para>
7357
7358 <para>
7359 One way of doing this (but certainly not the only way) is to
7360 release just the source as a tarball.
7361 You can do this by adding the following to the
7362 <filename>local.conf</filename> file found in the
7363 <link linkend='build-directory'>Build Directory</link>:
7364 <literallayout class='monospaced'>
7365 INHERIT += "archiver"
7366 ARCHIVER_MODE[src] = "original"
7367 </literallayout>
7368 During the creation of your image, the source from all
7369 recipes that deploy packages to the image is placed within
7370 subdirectories of
7371 <filename>DEPLOY_DIR/sources</filename> based on the
7372 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
7373 for each recipe.
7374 Releasing the entire directory enables you to comply with
7375 requirements concerning providing the unmodified source.
7376 It is important to note that the size of the directory can
7377 get large.
7378 </para>
7379
7380 <para>
7381 A way to help mitigate the size issue is to only release
7382 tarballs for licenses that require the release of
7383 source.
7384 Let us assume you are only concerned with GPL code as
7385 identified with the following:
7386 <literallayout class='monospaced'>
7387 $ cd poky/build/tmp/deploy/sources
7388 $ mkdir ~/gpl_source_release
7389 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
7390 </literallayout>
7391 At this point, you could create a tarball from the
7392 <filename>gpl_source_release</filename> directory and
7393 provide that to the end user.
7394 This method would be a step toward achieving compliance
7395 with section 3a of GPLv2 and with section 6 of GPLv3.
7396 </para>
7397 </section>
7398
7399 <section id='providing-license-text'>
7400 <title>Providing License Text</title>
7401
7402 <para>
7403 One requirement that is often overlooked is inclusion
7404 of license text.
7405 This requirement also needs to be dealt with prior to
7406 generating the final image.
7407 Some licenses require the license text to accompany
7408 the binary.
7409 You can achieve this by adding the following to your
7410 <filename>local.conf</filename> file:
7411 <literallayout class='monospaced'>
7412 COPY_LIC_MANIFEST = "1"
7413 COPY_LIC_DIRS = "1"
7414 </literallayout>
7415 Adding these statements to the configuration file ensures
7416 that the licenses collected during package generation
7417 are included on your image.
7418 As the source archiver has already archived the original
7419 unmodified source that contains the license files,
7420 you would have already met the requirements for inclusion
7421 of the license information with source as defined by the GPL
7422 and other open source licenses.
7423 </para>
7424 </section>
7425
7426 <section id='providing-compilation-scripts-and-source-code-modifications'>
7427 <title>Providing Compilation Scripts and Source Code Modifications</title>
7428
7429 <para>
7430 At this point, we have addressed all we need to address
7431 prior to generating the image.
7432 The next two requirements are addressed during the final
7433 packaging of the release.
7434 </para>
7435
7436 <para>
7437 By releasing the version of the OpenEmbedded build system
7438 and the layers used during the build, you will be providing both
7439 compilation scripts and the source code modifications in one
7440 step.
7441 </para>
7442
7443 <para>
7444 If the deployment team has a
7445 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
7446 and a distro layer, and those those layers are used to patch,
7447 compile, package, or modify (in any way) any open source
7448 software included in your released images, you
7449 might be required to to release those layers under section 3 of
7450 GPLv2 or section 1 of GPLv3.
7451 One way of doing that is with a clean
7452 checkout of the version of the Yocto Project and layers used
7453 during your build.
7454 Here is an example:
7455 <literallayout class='monospaced'>
7456 # We built using the &DISTRO_NAME; branch of the poky repo
7457 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
7458 $ cd poky
7459 # We built using the release_branch for our layers
7460 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
7461 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
7462 # clean up the .git repos
7463 $ find . -name ".git" -type d -exec rm -rf {} \;
7464 </literallayout>
7465 One thing a development organization might want to consider
7466 for end-user convenience is to modify
7467 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
7468 ensure that when the end user utilizes the released build
7469 system to build an image, the development organization's
7470 layers are included in the <filename>bblayers.conf</filename>
7471 file automatically:
7472 <literallayout class='monospaced'>
7473 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
7474 # changes incompatibly
7475 LCONF_VERSION = "6"
7476
7477 BBPATH = "${TOPDIR}"
7478 BBFILES ?= ""
7479
7480 BBLAYERS ?= " \
7481 ##OEROOT##/meta \
7482 ##OEROOT##/meta-yocto \
7483 ##OEROOT##/meta-yocto-bsp \
7484 ##OEROOT##/meta-mylayer \
7485 "
7486
7487 BBLAYERS_NON_REMOVABLE ?= " \
7488 ##OEROOT##/meta \
7489 ##OEROOT##/meta-yocto \
7490 "
7491 </literallayout>
7492 Creating and providing an archive of the
7493 <link linkend='metadata'>Metadata</link> layers
7494 (recipes, configuration files, and so forth)
7495 enables you to meet your
7496 requirements to include the scripts to control compilation
7497 as well as any modifications to the original source.
7498 </para>
7499 </section>
7500 </section>
7501
7502 <section id='using-the-error-reporting-tool'>
7503 <title>Using the Error Reporting Tool</title>
7504
7505 <para>
7506 The error reporting tool allows you to
7507 submit errors encountered during builds to a central database.
7508 Outside of the build environment, you can use a web interface to
7509 browse errors, view statistics, and query for errors.
7510 The tool works using a client-server system where the client
7511 portion is integrated with the installed Yocto Project
7512 <link linkend='source-directory'>Source Directory</link>
7513 (e.g. <filename>poky</filename>).
7514 The server receives the information collected and saves it in a
7515 database.
7516 </para>
7517
7518 <para>
7519 A live instance of the error reporting server exists at
7520 <ulink url='http://errors.yoctoproject.org'></ulink>.
7521 This server exists so that when you want to get help with
7522 build failures, you can submit all of the information on the
7523 failure easily and then point to the URL in your bug report
7524 or send an email to the mailing list.
7525 <note>
7526 If you send error reports to this server, the reports become
7527 publicly visible.
7528 </note>
7529 </para>
7530
7531 <section id='enabling-and-using-the-tool'>
7532 <title>Enabling and Using the Tool</title>
7533
7534 <para>
7535 By default, the error reporting tool is disabled.
7536 You can enable it by inheriting the
7537 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
7538 class by adding the following statement to the end of
7539 your <filename>local.conf</filename> file in your
7540 <link linkend='build-directory'>Build Directory</link>.
7541 <literallayout class='monospaced'>
7542 INHERIT += "report-error"
7543 </literallayout>
7544 </para>
7545
7546 <para>
7547 By default, the error reporting feature stores information in
7548 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
7549 However, you can specify a directory to use by adding the following
7550 to your <filename>local.conf</filename> file:
7551 <literallayout class='monospaced'>
7552 ERR_REPORT_DIR = "path"
7553 </literallayout>
7554 Enabling error reporting causes the build process to collect
7555 the errors and store them in a file as previously described.
7556 When the build system encounters an error, it includes a command
7557 as part of the console output.
7558 You can run the command to send the error file to the server.
7559 For example, the following command sends the errors to an upstream
7560 server:
7561 <literallayout class='monospaced'>
7562 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
7563 </literallayout>
7564 In the above example, the <filename>server</filename> parameter is
7565 optional.
7566 By default, the errors are sent to a database used by the entire
7567 community.
7568 If you specify a particular server, you can send them to a different
7569 database.
7570 </para>
7571
7572 <para>
7573 When sending the error file, you receive a link that corresponds
7574 to your entry in the database.
7575 For example, here is a typical link:
7576 <literallayout class='monospaced'>
7577 http://localhost:8000/Errors/Search/1/158
7578 </literallayout>
7579 Following the link takes you to a web interface where you can
7580 browse, query the errors, and view statistics.
7581 </para>
7582 </section>
7583
7584 <section id='disabling-the-tool'>
7585 <title>Disabling the Tool</title>
7586
7587 <para>
7588 To disable the error reporting feature, simply remove or comment
7589 out the following statement from the end of your
7590 <filename>local.conf</filename> file in your
7591 <link linkend='build-directory'>Build Directory</link>.
7592 <literallayout class='monospaced'>
7593 INHERIT += "report-error"
7594 </literallayout>
7595 </para>
7596 </section>
7597
7598 <section id='setting-up-your-own-error-reporting-server'>
7599 <title>Setting Up Your Own Error Reporting Server</title>
7600
7601 <para>
7602 If you want to set up your own error reporting server, you
7603 can obtain the code from the Git repository at
7604 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
7605 Instructions on how to set it up are in the README document.
7606 </para>
7607 </section>
7608 </section>
7609</chapter>
7610
7611<!--
7612vim: expandtab tw=80 ts=4
7613-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-02-26 13:53:33 +0000