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