summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml9738
-rw-r--r--documentation/dev-manual/dev-manual-customization.xsl19
-rw-r--r--documentation/dev-manual/dev-manual-eclipse-customization.xsl27
-rw-r--r--documentation/dev-manual/dev-manual-intro.xml240
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2112
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml1692
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml419
-rw-r--r--documentation/dev-manual/dev-manual-start.xml418
-rw-r--r--documentation/dev-manual/dev-manual.xml124
-rw-r--r--documentation/dev-manual/dev-style.css984
-rw-r--r--documentation/dev-manual/figures/app-dev-flow.pngbin0 -> 53301 bytes
-rw-r--r--documentation/dev-manual/figures/bsp-dev-flow.pngbin0 -> 42751 bytes
-rw-r--r--documentation/dev-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/dev-manual/figures/git-workflow.pngbin0 -> 26586 bytes
-rw-r--r--documentation/dev-manual/figures/index-downloads.pngbin0 -> 100374 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin0 -> 35561 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-1.pngbin0 -> 35839 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-2-generic.pngbin0 -> 39931 bytes
-rw-r--r--documentation/dev-manual/figures/recipe-workflow.pngbin0 -> 48276 bytes
-rw-r--r--documentation/dev-manual/figures/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/dev-manual/figures/yp-download.pngbin0 -> 230971 bytes
21 files changed, 15773 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
new file mode 100644
index 0000000000..64504299cc
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,9738 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='extendpoky'>
6
7<title>Common Tasks</title>
8 <para>
9 This chapter describes fundamental procedures such as creating layers,
10 adding new software packages, extending or customizing images,
11 porting work to new hardware (adding a new machine), and so forth.
12 You will find that the procedures documented here occur often in the
13 development cycle using the Yocto Project.
14 </para>
15
16 <section id="understanding-and-creating-layers">
17 <title>Understanding and Creating Layers</title>
18
19 <para>
20 The OpenEmbedded build system supports organizing
21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from
23 each other.
24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular your Metadata, the easier
27 it is to cope with future changes.
28 </para>
29
30 <para>
31 To illustrate how layers are used to keep things modular, consider
32 machine customizations.
33 These types of customizations typically reside in a special layer,
34 rather than a general layer, called a Board Support Package (BSP)
35 Layer.
36 Furthermore, the machine customizations should be isolated from
37 recipes and Metadata that support a new GUI environment,
38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
44 with those machine-specific changes.
45 You can accomplish this through a recipe that is a BitBake append
46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
48 </para>
49
50 <para>
51 </para>
52
53 <section id='yocto-project-layers'>
54 <title>Layers</title>
55
56 <para>
57 The <link linkend='source-directory'>Source Directory</link>
58 contains both general layers and BSP
59 layers right out of the box.
60 You can easily identify layers that ship with a
61 Yocto Project release in the Source Directory by their
62 folder names.
63 Folders that represent layers typically have names that begin with
64 the string <filename>meta-</filename>.
65 <note>
66 It is not a requirement that a layer name begin with the
67 prefix <filename>meta-</filename>, but it is a commonly
68 accepted standard in the Yocto Project community.
69 </note>
70 For example, when you set up the Source Directory structure,
71 you will see several layers:
72 <filename>meta</filename>,
73 <filename>meta-skeleton</filename>,
74 <filename>meta-selftest</filename>,
75 <filename>meta-yocto</filename>, and
76 <filename>meta-yocto-bsp</filename>.
77 Each of these folders represents a distinct layer.
78 </para>
79
80 <para>
81 As another example, if you set up a local copy of the
82 <filename>meta-intel</filename> Git repository
83 and then explore the folder of that general layer,
84 you will discover many Intel-specific BSP layers inside.
85 For more information on BSP layers, see the
86 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
87 section in the Yocto Project Board Support Package (BSP)
88 Developer's Guide.
89 </para>
90 </section>
91
92 <section id='creating-your-own-layer'>
93 <title>Creating Your Own Layer</title>
94
95 <para>
96 It is very easy to create your own layers to use with the
97 OpenEmbedded build system.
98 The Yocto Project ships with scripts that speed up creating
99 general layers and BSP layers.
100 This section describes the steps you perform by hand to create
101 a layer so that you can better understand them.
102 For information about the layer-creation scripts, see the
103 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
104 section in the Yocto Project Board Support Package (BSP)
105 Developer's Guide and the
106 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
107 section further down in this manual.
108 </para>
109
110 <para>
111 Follow these general steps to create your layer:
112 <orderedlist>
113 <listitem><para><emphasis>Check Existing Layers:</emphasis>
114 Before creating a new layer, you should be sure someone
115 has not already created a layer containing the Metadata
116 you need.
117 You can see the
118 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
119 for a list of layers from the OpenEmbedded community
120 that can be used in the Yocto Project.
121 </para></listitem>
122 <listitem><para><emphasis>Create a Directory:</emphasis>
123 Create the directory for your layer.
124 While not strictly required, prepend the name of the
125 folder with the string <filename>meta-</filename>.
126 For example:
127 <literallayout class='monospaced'>
128 meta-mylayer
129 meta-GUI_xyz
130 meta-mymachine
131 </literallayout>
132 </para></listitem>
133 <listitem><para><emphasis>Create a Layer Configuration
134 File:</emphasis>
135 Inside your new layer folder, you need to create a
136 <filename>conf/layer.conf</filename> file.
137 It is easiest to take an existing layer configuration
138 file and copy that to your layer's
139 <filename>conf</filename> directory and then modify the
140 file as needed.</para>
141 <para>The
142 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
143 demonstrates the required syntax:
144 <literallayout class='monospaced'>
145 # We have a conf and classes directory, add to BBPATH
146 BBPATH .= ":${LAYERDIR}"
147
148 # We have recipes-* directories, add to BBFILES
149 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
150 ${LAYERDIR}/recipes-*/*/*.bbappend"
151
152 BBFILE_COLLECTIONS += "yoctobsp"
153 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
154 BBFILE_PRIORITY_yoctobsp = "5"
155 LAYERVERSION_yoctobsp = "3"
156 </literallayout></para>
157 <para>Here is an explanation of the example:
158 <itemizedlist>
159 <listitem><para>The configuration and
160 classes directory is appended to
161 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
162 <note>
163 All non-distro layers, which include all BSP
164 layers, are expected to append the layer
165 directory to the
166 <filename>BBPATH</filename>.
167 On the other hand, distro layers, such as
168 <filename>meta-yocto</filename>, can choose
169 to enforce their own precedence over
170 <filename>BBPATH</filename>.
171 For an example of that syntax, see the
172 <filename>layer.conf</filename> file for
173 the <filename>meta-yocto</filename> layer.
174 </note></para></listitem>
175 <listitem><para>The recipes for the layers are
176 appended to
177 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
178 </para></listitem>
179 <listitem><para>The
180 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
181 variable is then appended with the layer name.
182 </para></listitem>
183 <listitem><para>The
184 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
185 variable is set to a regular expression and is
186 used to match files from
187 <filename>BBFILES</filename> into a particular
188 layer.
189 In this case,
190 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
191 is used to make <filename>BBFILE_PATTERN</filename> match within the
192 layer's path.</para></listitem>
193 <listitem><para>The
194 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
195 variable then assigns a priority to the layer.
196 Applying priorities is useful in situations
197 where the same recipe might appear in multiple
198 layers and allows you to choose the layer
199 that takes precedence.</para></listitem>
200 <listitem><para>The
201 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
202 variable optionally specifies the version of a
203 layer as a single number.</para></listitem>
204 </itemizedlist></para>
205 <para>Note the use of the
206 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
207 variable, which expands to the directory of the current
208 layer.</para>
209 <para>Through the use of the <filename>BBPATH</filename>
210 variable, BitBake locates class files
211 (<filename>.bbclass</filename>),
212 configuration files, and files that are included
213 with <filename>include</filename> and
214 <filename>require</filename> statements.
215 For these cases, BitBake uses the first file that
216 matches the name found in <filename>BBPATH</filename>.
217 This is similar to the way the <filename>PATH</filename>
218 variable is used for binaries.
219 It is recommended, therefore, that you use unique
220 class and configuration
221 filenames in your custom layer.</para></listitem>
222 <listitem><para><emphasis>Add Content:</emphasis> Depending
223 on the type of layer, add the content.
224 If the layer adds support for a machine, add the machine
225 configuration in a <filename>conf/machine/</filename>
226 file within the layer.
227 If the layer adds distro policy, add the distro
228 configuration in a <filename>conf/distro/</filename>
229 file within the layer.
230 If the layer introduces new recipes, put the recipes
231 you need in <filename>recipes-*</filename>
232 subdirectories within the layer.
233 <note>In order to be compliant with the Yocto Project,
234 a layer must contain a
235 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
236 </note></para></listitem>
237 </orderedlist>
238 </para>
239 </section>
240
241 <section id='best-practices-to-follow-when-creating-layers'>
242 <title>Best Practices to Follow When Creating Layers</title>
243
244 <para>
245 To create layers that are easier to maintain and that will
246 not impact builds for other machines, you should consider the
247 information in the following sections.
248 </para>
249
250 <section id='avoid-overlaying-entire-recipes'>
251 <title>Avoid "Overlaying" Entire Recipes</title>
252
253 <para>
254 Avoid "overlaying" entire recipes from other layers in your
255 configuration.
256 In other words, do not copy an entire recipe into your
257 layer and then modify it.
258 Rather, use an append file (<filename>.bbappend</filename>)
259 to override
260 only those parts of the original recipe you need to modify.
261 </para>
262 </section>
263
264 <section id='avoid-duplicating-include-files'>
265 <title>Avoid Duplicating Include Files</title>
266
267 <para>
268 Avoid duplicating include files.
269 Use append files (<filename>.bbappend</filename>)
270 for each recipe
271 that uses an include file.
272 Or, if you are introducing a new recipe that requires
273 the included file, use the path relative to the original
274 layer directory to refer to the file.
275 For example, use
276 <filename>require recipes-core/somepackage/somefile.inc</filename>
277 instead of <filename>require somefile.inc</filename>.
278 If you're finding you have to overlay the include file,
279 it could indicate a deficiency in the include file in
280 the layer to which it originally belongs.
281 If this is the case, you need to address that deficiency
282 instead of overlaying the include file.
283 </para>
284
285 <para>
286 For example, consider how support plug-ins for the Qt 4
287 database are configured.
288 The Source Directory does not have MySQL or PostgreSQL.
289 However, OpenEmbedded's layer <filename>meta-oe</filename>
290 does.
291 Consequently, <filename>meta-oe</filename> uses
292 append files to modify the
293 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
294 enable the appropriate plug-ins.
295 This variable was added to the <filename>qt4.inc</filename>
296 include file in the Source Directory specifically to allow
297 the <filename>meta-oe</filename> layer to be able to control
298 which plug-ins are built.
299 </para>
300 </section>
301
302 <section id='structure-your-layers'>
303 <title>Structure Your Layers</title>
304
305 <para>
306 Proper use of overrides within append files and placement
307 of machine-specific files within your layer can ensure that
308 a build is not using the wrong Metadata and negatively
309 impacting a build for a different machine.
310 Following are some examples:
311 <itemizedlist>
312 <listitem><para><emphasis>Modifying Variables to Support
313 a Different Machine:</emphasis>
314 Suppose you have a layer named
315 <filename>meta-one</filename> that adds support
316 for building machine "one".
317 To do so, you use an append file named
318 <filename>base-files.bbappend</filename> and
319 create a dependency on "foo" by altering the
320 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
321 variable:
322 <literallayout class='monospaced'>
323 DEPENDS = "foo"
324 </literallayout>
325 The dependency is created during any build that
326 includes the layer
327 <filename>meta-one</filename>.
328 However, you might not want this dependency
329 for all machines.
330 For example, suppose you are building for
331 machine "two" but your
332 <filename>bblayers.conf</filename> file has the
333 <filename>meta-one</filename> layer included.
334 During the build, the
335 <filename>base-files</filename> for machine
336 "two" will also have the dependency on
337 <filename>foo</filename>.</para>
338 <para>To make sure your changes apply only when
339 building machine "one", use a machine override
340 with the <filename>DEPENDS</filename> statement:
341 <literallayout class='monospaced'>
342 DEPENDS_one = "foo"
343 </literallayout>
344 You should follow the same strategy when using
345 <filename>_append</filename> and
346 <filename>_prepend</filename> operations:
347 <literallayout class='monospaced'>
348 DEPENDS_append_one = " foo"
349 DEPENDS_prepend_one = "foo "
350 </literallayout>
351 As an actual example, here's a line from the recipe for
352 the OProfile profiler, which lists an extra build-time
353 dependency when building specifically for 64-bit PowerPC:
354 <literallayout class='monospaced'>
355 DEPENDS_append_powerpc64 = " libpfm4"
356 </literallayout>
357 <note>
358 Avoiding "+=" and "=+" and using
359 machine-specific
360 <filename>_append</filename>
361 and <filename>_prepend</filename> operations
362 is recommended as well.
363 </note></para></listitem>
364 <listitem><para><emphasis>Place Machine-Specific Files
365 in Machine-Specific Locations:</emphasis>
366 When you have a base recipe, such as
367 <filename>base-files.bb</filename>, that
368 contains a
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
370 statement to a file, you can use an append file
371 to cause the build to use your own version of
372 the file.
373 For example, an append file in your layer at
374 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
375 could extend
376 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
377 using
378 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
379 as follows:
380 <literallayout class='monospaced'>
381 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
382 </literallayout>
383 The build for machine "one" will pick up your
384 machine-specific file as long as you have the
385 file in
386 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
387 However, if you are building for a different
388 machine and the
389 <filename>bblayers.conf</filename> file includes
390 the <filename>meta-one</filename> layer and
391 the location of your machine-specific file is
392 the first location where that file is found
393 according to <filename>FILESPATH</filename>,
394 builds for all machines will also use that
395 machine-specific file.</para>
396 <para>You can make sure that a machine-specific
397 file is used for a particular machine by putting
398 the file in a subdirectory specific to the
399 machine.
400 For example, rather than placing the file in
401 <filename>meta-one/recipes-core/base-files/base-files/</filename>
402 as shown above, put it in
403 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
404 Not only does this make sure the file is used
405 only when building for machine "one", but the
406 build process locates the file more quickly.</para>
407 <para>In summary, you need to place all files
408 referenced from <filename>SRC_URI</filename>
409 in a machine-specific subdirectory within the
410 layer in order to restrict those files to
411 machine-specific builds.</para></listitem>
412 </itemizedlist>
413 </para>
414 </section>
415
416 <section id='other-recommendations'>
417 <title>Other Recommendations</title>
418
419 <para>
420 We also recommend the following:
421 <itemizedlist>
422 <listitem><para>Store custom layers in a Git repository
423 that uses the
424 <filename>meta-<replaceable>layer_name</replaceable></filename> format.
425 </para></listitem>
426 <listitem><para>Clone the repository alongside other
427 <filename>meta</filename> directories in the
428 <link linkend='source-directory'>Source Directory</link>.
429 </para></listitem>
430 </itemizedlist>
431 Following these recommendations keeps your Source Directory and
432 its configuration entirely inside the Yocto Project's core
433 base.
434 </para>
435 </section>
436 </section>
437
438 <section id='enabling-your-layer'>
439 <title>Enabling Your Layer</title>
440
441 <para>
442 Before the OpenEmbedded build system can use your new layer,
443 you need to enable it.
444 To enable your layer, simply add your layer's path to the
445 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
446 variable in your <filename>conf/bblayers.conf</filename> file,
447 which is found in the
448 <link linkend='build-directory'>Build Directory</link>.
449 The following example shows how to enable a layer named
450 <filename>meta-mylayer</filename>:
451 <literallayout class='monospaced'>
452 LCONF_VERSION = "6"
453
454 BBPATH = "${TOPDIR}"
455 BBFILES ?= ""
456
457 BBLAYERS ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 $HOME/poky/meta-yocto-bsp \
461 $HOME/poky/meta-mylayer \
462 "
463
464 BBLAYERS_NON_REMOVABLE ?= " \
465 $HOME/poky/meta \
466 $HOME/poky/meta-yocto \
467 "
468 </literallayout>
469 </para>
470
471 <para>
472 BitBake parses each <filename>conf/layer.conf</filename> file
473 as specified in the <filename>BBLAYERS</filename> variable
474 within the <filename>conf/bblayers.conf</filename> file.
475 During the processing of each
476 <filename>conf/layer.conf</filename> file, BitBake adds the
477 recipes, classes and configurations contained within the
478 particular layer to the source directory.
479 </para>
480 </section>
481
482 <section id='using-bbappend-files'>
483 <title>Using .bbappend Files</title>
484
485 <para>
486 Recipes used to append Metadata to other recipes are called
487 BitBake append files.
488 BitBake append files use the <filename>.bbappend</filename> file
489 type suffix, while the corresponding recipes to which Metadata
490 is being appended use the <filename>.bb</filename> file type
491 suffix.
492 </para>
493
494 <para>
495 A <filename>.bbappend</filename> file allows your layer to make
496 additions or changes to the content of another layer's recipe
497 without having to copy the other recipe into your layer.
498 Your <filename>.bbappend</filename> file resides in your layer,
499 while the main <filename>.bb</filename> recipe file to
500 which you are appending Metadata resides in a different layer.
501 </para>
502
503 <para>
504 Append files must have the same root names as their corresponding
505 recipes.
506 For example, the append file
507 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
508 <filename>someapp_&DISTRO;.bb</filename>.
509 This means the original recipe and append file names are version
510 number-specific.
511 If the corresponding recipe is renamed to update to a newer
512 version, the corresponding <filename>.bbappend</filename> file must
513 be renamed (and possibly updated) as well.
514 During the build process, BitBake displays an error on starting
515 if it detects a <filename>.bbappend</filename> file that does
516 not have a corresponding recipe with a matching name.
517 See the
518 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
519 variable for information on how to handle this error.
520 </para>
521
522 <para>
523 Being able to append information to an existing recipe not only
524 avoids duplication, but also automatically applies recipe
525 changes in a different layer to your layer.
526 If you were copying recipes, you would have to manually merge
527 changes as they occur.
528 </para>
529
530 <para>
531 As an example, consider the main formfactor recipe and a
532 corresponding formfactor append file both from the
533 <link linkend='source-directory'>Source Directory</link>.
534 Here is the main formfactor recipe, which is named
535 <filename>formfactor_0.0.bb</filename> and located in the
536 "meta" layer at
537 <filename>meta/recipes-bsp/formfactor</filename>:
538 <literallayout class='monospaced'>
539 SUMMARY = "Device formfactor information"
540 SECTION = "base"
541 LICENSE = "MIT"
542 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
543 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
544 PR = "r45"
545
546 SRC_URI = "file://config file://machconfig"
547 S = "${WORKDIR}"
548
549 PACKAGE_ARCH = "${MACHINE_ARCH}"
550 INHIBIT_DEFAULT_DEPS = "1"
551
552 do_install() {
553 # Install file only if it has contents
554 install -d ${D}${sysconfdir}/formfactor/
555 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
556 if [ -s "${S}/machconfig" ]; then
557 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
558 fi
559 }
560 </literallayout>
561 In the main recipe, note the
562 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
563 variable, which tells the OpenEmbedded build system where to
564 find files during the build.
565 </para>
566
567 <para>
568 Following is the append file, which is named
569 <filename>formfactor_0.0.bbappend</filename> and is from the
570 Crown Bay BSP Layer named
571 <filename>meta-intel/meta-crownbay</filename>.
572 The file is in <filename>recipes-bsp/formfactor</filename>:
573 <literallayout class='monospaced'>
574 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
575 </literallayout>
576 </para>
577
578 <para>
579 By default, the build system uses the
580 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
581 variable to locate files.
582 This append file extends the locations by setting the
583 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
584 variable.
585 Setting this variable in the <filename>.bbappend</filename>
586 file is the most reliable and recommended method for adding
587 directories to the search path used by the build system
588 to find files.
589 </para>
590
591 <para>
592 The statement in this example extends the directories to include
593 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
594 which resolves to a directory named
595 <filename>formfactor</filename> in the same directory
596 in which the append file resides (i.e.
597 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
598 This implies that you must have the supporting directory
599 structure set up that will contain any files or patches you
600 will be including from the layer.
601 </para>
602
603 <para>
604 Using the immediate expansion assignment operator
605 <filename>:=</filename> is important because of the reference to
606 <filename>THISDIR</filename>.
607 The trailing colon character is important as it ensures that
608 items in the list remain colon-separated.
609 <note>
610 <para>
611 BitBake automatically defines the
612 <filename>THISDIR</filename> variable.
613 You should never set this variable yourself.
614 Using "_prepend" ensures your path will
615 be searched prior to other paths in the final list.
616 </para>
617
618 <para>
619 Also, not all append files add extra files.
620 Many append files simply exist to add build options
621 (e.g. <filename>systemd</filename>).
622 For these cases, it is not necessary to use the
623 "_prepend" part of the statement.
624 </para>
625 </note>
626 </para>
627 </section>
628
629 <section id='prioritizing-your-layer'>
630 <title>Prioritizing Your Layer</title>
631
632 <para>
633 Each layer is assigned a priority value.
634 Priority values control which layer takes precedence if there
635 are recipe files with the same name in multiple layers.
636 For these cases, the recipe file from the layer with a higher
637 priority number takes precedence.
638 Priority values also affect the order in which multiple
639 <filename>.bbappend</filename> files for the same recipe are
640 applied.
641 You can either specify the priority manually, or allow the
642 build system to calculate it based on the layer's dependencies.
643 </para>
644
645 <para>
646 To specify the layer's priority manually, use the
647 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
648 variable.
649 For example:
650 <literallayout class='monospaced'>
651 BBFILE_PRIORITY_mylayer = "1"
652 </literallayout>
653 </para>
654
655 <note>
656 <para>It is possible for a recipe with a lower version number
657 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
658 in a layer that has a higher priority to take precedence.</para>
659 <para>Also, the layer priority does not currently affect the
660 precedence order of <filename>.conf</filename>
661 or <filename>.bbclass</filename> files.
662 Future versions of BitBake might address this.</para>
663 </note>
664 </section>
665
666 <section id='managing-layers'>
667 <title>Managing Layers</title>
668
669 <para>
670 You can use the BitBake layer management tool to provide a view
671 into the structure of recipes across a multi-layer project.
672 Being able to generate output that reports on configured layers
673 with their paths and priorities and on
674 <filename>.bbappend</filename> files and their applicable
675 recipes can help to reveal potential problems.
676 </para>
677
678 <para>
679 Use the following form when running the layer management tool.
680 <literallayout class='monospaced'>
681 $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>]
682 </literallayout>
683 The following list describes the available commands:
684 <itemizedlist>
685 <listitem><para><filename><emphasis>help:</emphasis></filename>
686 Displays general help or help on a specified command.
687 </para></listitem>
688 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
689 Shows the current configured layers.
690 </para></listitem>
691 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
692 Lists available recipes and the layers that provide them.
693 </para></listitem>
694 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
695 Lists overlayed recipes.
696 A recipe is overlayed when a recipe with the same name
697 exists in another layer that has a higher layer
698 priority.
699 </para></listitem>
700 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
701 Lists <filename>.bbappend</filename> files and the
702 recipe files to which they apply.
703 </para></listitem>
704 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
705 Lists dependency relationships between recipes that
706 cross layer boundaries.
707 </para></listitem>
708 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
709 Flattens the layer configuration into a separate output
710 directory.
711 Flattening your layer configuration builds a "flattened"
712 directory that contains the contents of all layers,
713 with any overlayed recipes removed and any
714 <filename>.bbappend</filename> files appended to the
715 corresponding recipes.
716 You might have to perform some manual cleanup of the
717 flattened layer as follows:
718 <itemizedlist>
719 <listitem><para>Non-recipe files (such as patches)
720 are overwritten.
721 The flatten command shows a warning for these
722 files.
723 </para></listitem>
724 <listitem><para>Anything beyond the normal layer
725 setup has been added to the
726 <filename>layer.conf</filename> file.
727 Only the lowest priority layer's
728 <filename>layer.conf</filename> is used.
729 </para></listitem>
730 <listitem><para>Overridden and appended items from
731 <filename>.bbappend</filename> files need to be
732 cleaned up.
733 The contents of each
734 <filename>.bbappend</filename> end up in the
735 flattened recipe.
736 However, if there are appended or changed
737 variable values, you need to tidy these up
738 yourself.
739 Consider the following example.
740 Here, the <filename>bitbake-layers</filename>
741 command adds the line
742 <filename>#### bbappended ...</filename> so that
743 you know where the following lines originate:
744 <literallayout class='monospaced'>
745 ...
746 DESCRIPTION = "A useful utility"
747 ...
748 EXTRA_OECONF = "&dash;&dash;enable-something"
749 ...
750
751 #### bbappended from meta-anotherlayer ####
752
753 DESCRIPTION = "Customized utility"
754 EXTRA_OECONF += "&dash;&dash;enable-somethingelse"
755 </literallayout>
756 Ideally, you would tidy up these utilities as
757 follows:
758 <literallayout class='monospaced'>
759 ...
760 DESCRIPTION = "Customized utility"
761 ...
762 EXTRA_OECONF = "&dash;&dash;enable-something &dash;&dash;enable-somethingelse"
763 ...
764 </literallayout></para></listitem>
765 </itemizedlist></para></listitem>
766 </itemizedlist>
767 </para>
768 </section>
769
770 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
771 <title>Creating a General Layer Using the yocto-layer Script</title>
772
773 <para>
774 The <filename>yocto-layer</filename> script simplifies
775 creating a new general layer.
776 <note>
777 For information on BSP layers, see the
778 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
779 section in the Yocto Project Board Specific (BSP)
780 Developer's Guide.
781 </note>
782 The default mode of the script's operation is to prompt you for
783 information needed to generate the layer:
784 <itemizedlist>
785 <listitem><para>The layer priority.
786 </para></listitem>
787 <listitem><para>Whether or not to create a sample recipe.
788 </para></listitem>
789 <listitem><para>Whether or not to create a sample
790 append file.
791 </para></listitem>
792 </itemizedlist>
793 </para>
794
795 <para>
796 Use the <filename>yocto-layer create</filename> sub-command
797 to create a new general layer.
798 In its simplest form, you can create a layer as follows:
799 <literallayout class='monospaced'>
800 $ yocto-layer create mylayer
801 </literallayout>
802 The previous example creates a layer named
803 <filename>meta-mylayer</filename> in the current directory.
804 </para>
805
806 <para>
807 As the <filename>yocto-layer create</filename> command runs,
808 default values for the prompts appear in brackets.
809 Pressing enter without supplying anything for the prompts
810 or pressing enter and providing an invalid response causes the
811 script to accept the default value.
812 Once the script completes, the new layer
813 is created in the current working directory.
814 The script names the layer by prepending
815 <filename>meta-</filename> to the name you provide.
816 </para>
817
818 <para>
819 Minimally, the script creates the following within the layer:
820 <itemizedlist>
821 <listitem><para><emphasis>The <filename>conf</filename>
822 directory:</emphasis>
823 This directory contains the layer's configuration file.
824 The root name for the file is the same as the root name
825 your provided for the layer (e.g.
826 <filename><replaceable>layer</replaceable>.conf</filename>).
827 </para></listitem>
828 <listitem><para><emphasis>The
829 <filename>COPYING.MIT</filename> file:</emphasis>
830 The copyright and use notice for the software.
831 </para></listitem>
832 <listitem><para><emphasis>The <filename>README</filename>
833 file:</emphasis>
834 A file describing the contents of your new layer.
835 </para></listitem>
836 </itemizedlist>
837 </para>
838
839 <para>
840 If you choose to generate a sample recipe file, the script
841 prompts you for the name for the recipe and then creates it
842 in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>.
843 The script creates a <filename>.bb</filename> file and a
844 directory, which contains a sample
845 <filename>helloworld.c</filename> source file, along with
846 a sample patch file.
847 If you do not provide a recipe name, the script uses
848 "example".
849 </para>
850
851 <para>
852 If you choose to generate a sample append file, the script
853 prompts you for the name for the file and then creates it
854 in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>.
855 The script creates a <filename>.bbappend</filename> file and a
856 directory, which contains a sample patch file.
857 If you do not provide a recipe name, the script uses
858 "example".
859 The script also prompts you for the version of the append file.
860 The version should match the recipe to which the append file
861 is associated.
862 </para>
863
864 <para>
865 The easiest way to see how the <filename>yocto-layer</filename>
866 script works is to experiment with the script.
867 You can also read the usage information by entering the
868 following:
869 <literallayout class='monospaced'>
870 $ yocto-layer help
871 </literallayout>
872 </para>
873
874 <para>
875 Once you create your general layer, you must add it to your
876 <filename>bblayers.conf</filename> file.
877 Here is an example where a layer named
878 <filename>meta-mylayer</filename> is added:
879 <literallayout class='monospaced'>
880 BBLAYERS = ?" \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 /usr/local/src/yocto/meta-yocto-bsp \
884 /usr/local/src/yocto/meta-mylayer \
885 "
886
887 BBLAYERS_NON_REMOVABLE ?= " \
888 /usr/local/src/yocto/meta \
889 /usr/local/src/yocto/meta-yocto \
890 "
891 </literallayout>
892 Adding the layer to this file enables the build system to
893 locate the layer during the build.
894 </para>
895 </section>
896 </section>
897
898 <section id='usingpoky-extend-customimage'>
899 <title>Customizing Images</title>
900
901 <para>
902 You can customize images to satisfy particular requirements.
903 This section describes several methods and provides guidelines for each.
904 </para>
905
906 <section id='usingpoky-extend-customimage-localconf'>
907 <title>Customizing Images Using <filename>local.conf</filename></title>
908
909 <para>
910 Probably the easiest way to customize an image is to add a
911 package by way of the <filename>local.conf</filename>
912 configuration file.
913 Because it is limited to local use, this method generally only
914 allows you to add packages and is not as flexible as creating
915 your own customized image.
916 When you add packages using local variables this way, you need
917 to realize that these variable changes are in effect for every
918 build and consequently affect all images, which might not
919 be what you require.
920 </para>
921
922 <para>
923 To add a package to your image using the local configuration
924 file, use the
925 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
926 variable with the <filename>_append</filename> operator:
927 <literallayout class='monospaced'>
928 IMAGE_INSTALL_append = " strace"
929 </literallayout>
930 Use of the syntax is important - specifically, the space between
931 the quote and the package name, which is
932 <filename>strace</filename> in this example.
933 This space is required since the <filename>_append</filename>
934 operator does not add the space.
935 </para>
936
937 <para>
938 Furthermore, you must use <filename>_append</filename> instead
939 of the <filename>+=</filename> operator if you want to avoid
940 ordering issues.
941 The reason for this is because doing so unconditionally appends
942 to the variable and avoids ordering problems due to the
943 variable being set in image recipes and
944 <filename>.bbclass</filename> files with operators like
945 <filename>?=</filename>.
946 Using <filename>_append</filename> ensures the operation takes
947 affect.
948 </para>
949
950 <para>
951 As shown in its simplest use,
952 <filename>IMAGE_INSTALL_append</filename> affects all images.
953 It is possible to extend the syntax so that the variable
954 applies to a specific image only.
955 Here is an example:
956 <literallayout class='monospaced'>
957 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
958 </literallayout>
959 This example adds <filename>strace</filename> to the
960 <filename>core-image-minimal</filename> image only.
961 </para>
962
963 <para>
964 You can add packages using a similar approach through the
965 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
966 variable.
967 If you use this variable, only
968 <filename>core-image-*</filename> images are affected.
969 </para>
970 </section>
971
972 <section id='usingpoky-extend-customimage-imagefeatures'>
973 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
974 <filename>EXTRA_IMAGE_FEATURES</filename></title>
975
976 <para>
977 Another method for customizing your image is to enable or
978 disable high-level image features by using the
979 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
980 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
981 variables.
982 Although the functions for both variables are nearly equivalent,
983 best practices dictate using <filename>IMAGE_FEATURES</filename>
984 from within a recipe and using
985 <filename>EXTRA_IMAGE_FEATURES</filename> from within
986 your <filename>local.conf</filename> file, which is found in the
987 <link linkend='build-directory'>Build Directory</link>.
988 </para>
989
990 <para>
991 To understand how these features work, the best reference is
992 <filename>meta/classes/core-image.bbclass</filename>.
993 In summary, the file looks at the contents of the
994 <filename>IMAGE_FEATURES</filename> variable and then maps
995 those contents into a set of package groups.
996 Based on this information, the build system automatically
997 adds the appropriate packages to the
998 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
999 variable.
1000 Effectively, you are enabling extra features by extending the
1001 class or creating a custom class for use with specialized image
1002 <filename>.bb</filename> files.
1003 </para>
1004
1005 <para>
1006 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1007 from within your local configuration file.
1008 Using a separate area from which to enable features with
1009 this variable helps you avoid overwriting the features in the
1010 image recipe that are enabled with
1011 <filename>IMAGE_FEATURES</filename>.
1012 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1013 to <filename>IMAGE_FEATURES</filename> within
1014 <filename>meta/conf/bitbake.conf</filename>.
1015 </para>
1016
1017 <para>
1018 To illustrate how you can use these variables to modify your
1019 image, consider an example that selects the SSH server.
1020 The Yocto Project ships with two SSH servers you can use
1021 with your images: Dropbear and OpenSSH.
1022 Dropbear is a minimal SSH server appropriate for
1023 resource-constrained environments, while OpenSSH is a
1024 well-known standard SSH server implementation.
1025 By default, the <filename>core-image-sato</filename> image
1026 is configured to use Dropbear.
1027 The <filename>core-image-full-cmdline</filename> and
1028 <filename>core-image-lsb</filename> images both
1029 include OpenSSH.
1030 The <filename>core-image-minimal</filename> image does not
1031 contain an SSH server.
1032 </para>
1033
1034 <para>
1035 You can customize your image and change these defaults.
1036 Edit the <filename>IMAGE_FEATURES</filename> variable
1037 in your recipe or use the
1038 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1039 <filename>local.conf</filename> file so that it configures the
1040 image you are working with to include
1041 <filename>ssh-server-dropbear</filename> or
1042 <filename>ssh-server-openssh</filename>.
1043 </para>
1044
1045 <note>
1046 See the
1047 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1048 section in the Yocto Project Reference Manual for a complete
1049 list of image features that ship with the Yocto Project.
1050 </note>
1051 </section>
1052
1053 <section id='usingpoky-extend-customimage-custombb'>
1054 <title>Customizing Images Using Custom .bb Files</title>
1055
1056 <para>
1057 You can also customize an image by creating a custom recipe
1058 that defines additional software as part of the image.
1059 The following example shows the form for the two lines you need:
1060 <literallayout class='monospaced'>
1061 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1062
1063 inherit core-image
1064 </literallayout>
1065 </para>
1066
1067 <para>
1068 Defining the software using a custom recipe gives you total
1069 control over the contents of the image.
1070 It is important to use the correct names of packages in the
1071 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1072 variable.
1073 You must use the OpenEmbedded notation and not the Debian notation for the names
1074 (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>).
1075 </para>
1076
1077 <para>
1078 The other method for creating a custom image is to base it on an existing image.
1079 For example, if you want to create an image based on <filename>core-image-sato</filename>
1080 but add the additional package <filename>strace</filename> to the image,
1081 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1082 new <filename>.bb</filename> and add the following line to the end of the copy:
1083 <literallayout class='monospaced'>
1084 IMAGE_INSTALL += "strace"
1085 </literallayout>
1086 </para>
1087 </section>
1088
1089 <section id='usingpoky-extend-customimage-customtasks'>
1090 <title>Customizing Images Using Custom Package Groups</title>
1091
1092 <para>
1093 For complex custom images, the best approach for customizing
1094 an image is to create a custom package group recipe that is
1095 used to build the image or images.
1096 A good example of a package group recipe is
1097 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1098 The
1099 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1100 variable lists the package group packages you wish to produce.
1101 <filename>inherit packagegroup</filename> sets appropriate
1102 default values and automatically adds <filename>-dev</filename>,
1103 <filename>-dbg</filename>, and <filename>-ptest</filename>
1104 complementary packages for every package specified in
1105 <filename>PACKAGES</filename>.
1106 Note that the inherit line should be towards
1107 the top of the recipe, certainly before you set
1108 <filename>PACKAGES</filename>.
1109 For each package you specify in <filename>PACKAGES</filename>,
1110 you can use
1111 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1112 and
1113 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1114 entries to provide a list of packages the parent task package
1115 should contain.
1116 Following is an example:
1117 <literallayout class='monospaced'>
1118 DESCRIPTION = "My Custom Package Groups"
1119
1120 inherit packagegroup
1121
1122 PACKAGES = "\
1123 packagegroup-custom-apps \
1124 packagegroup-custom-tools \
1125 "
1126
1127 RDEPENDS_packagegroup-custom-apps = "\
1128 dropbear \
1129 portmap \
1130 psplash"
1131
1132 RDEPENDS_packagegroup-custom-tools = "\
1133 oprofile \
1134 oprofileui-server \
1135 lttng-control \
1136 lttng-viewer"
1137
1138 RRECOMMENDS_packagegroup-custom-tools = "\
1139 kernel-module-oprofile"
1140 </literallayout>
1141 </para>
1142
1143 <para>
1144 In the previous example, two package group packages are created with their dependencies and their
1145 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1146 <filename>packagegroup-custom-tools</filename>.
1147 To build an image using these package group packages, you need to add
1148 <filename>packagegroup-custom-apps</filename> and/or
1149 <filename>packagegroup-custom-tools</filename> to
1150 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1151 For other forms of image dependencies see the other areas of this section.
1152 </para>
1153 </section>
1154 </section>
1155
1156 <section id='new-recipe-writing-a-new-recipe'>
1157 <title>Writing a New Recipe</title>
1158
1159 <para>
1160 Recipes (<filename>.bb</filename> files) are fundamental components
1161 in the Yocto Project environment.
1162 Each software component built by the OpenEmbedded build system
1163 requires a recipe to define the component.
1164 This section describes how to create, write, and test a new
1165 recipe.
1166 <note>
1167 For information on variables that are useful for recipes and
1168 for information about recipe naming issues, see the
1169 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1170 section of the Yocto Project Reference Manual.
1171 </note>
1172 </para>
1173
1174 <section id='new-recipe-overview'>
1175 <title>Overview</title>
1176
1177 <para>
1178 The following figure shows the basic process for creating a
1179 new recipe.
1180 The remainder of the section provides details for the steps.
1181 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1182 </para>
1183 </section>
1184
1185 <section id='new-recipe-locate-a-base-recipe'>
1186 <title>Locate a Base Recipe</title>
1187
1188 <para>
1189 Before writing a recipe from scratch, it is often useful to
1190 discover whether someone else has already written one that
1191 meets (or comes close to meeting) your needs.
1192 The Yocto Project and OpenEmbedded communities maintain many
1193 recipes that might be candidates for what you are doing.
1194 You can find a good central index of these recipes in the
1195 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1196 </para>
1197
1198 <para>
1199 Working from an existing recipe or a skeleton recipe is the
1200 best way to get started.
1201 Here are some points on both methods:
1202 <itemizedlist>
1203 <listitem><para><emphasis>Locate and modify a recipe that
1204 is close to what you want to do:</emphasis>
1205 This method works when you are familiar with the
1206 current recipe space.
1207 The method does not work so well for those new to
1208 the Yocto Project or writing recipes.</para>
1209 <para>Some risks associated with this method are
1210 using a recipe that has areas totally unrelated to
1211 what you are trying to accomplish with your recipe,
1212 not recognizing areas of the recipe that you might
1213 have to add from scratch, and so forth.
1214 All these risks stem from unfamiliarity with the
1215 existing recipe space.</para></listitem>
1216 <listitem><para><emphasis>Use and modify the following
1217 skeleton recipe:</emphasis>
1218 <literallayout class='monospaced'>
1219 SUMMARY = ""
1220 HOMEPAGE = ""
1221 LICENSE = ""
1222
1223 LIC_FILES_CHKSUM = ""
1224
1225 SRC_URI = ""
1226 SRC_URI[md5sum] = ""
1227 SRC_URI[sha256sum] = ""
1228
1229 S = "${WORKDIR}/${PN}-${PV}"
1230
1231 inherit <replaceable>stuff</replaceable>
1232 </literallayout>
1233 Modifying this recipe is the recommended method for
1234 creating a new recipe.
1235 The recipe provides the fundamental areas that you need
1236 to include, exclude, or alter to fit your needs.
1237 </para></listitem>
1238 </itemizedlist>
1239 </para>
1240 </section>
1241
1242 <section id='new-recipe-storing-and-naming-the-recipe'>
1243 <title>Storing and Naming the Recipe</title>
1244
1245 <para>
1246 Once you have your base recipe, you should put it in your
1247 own layer and name it appropriately.
1248 Locating it correctly ensures that the OpenEmbedded build
1249 system can find it when you use BitBake to process the
1250 recipe.
1251 </para>
1252
1253 <itemizedlist>
1254 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1255 The OpenEmbedded build system locates your recipe
1256 through the layer's <filename>conf/layer.conf</filename>
1257 file and the
1258 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1259 variable.
1260 This variable sets up a path from which the build system can
1261 locate recipes.
1262 Here is the typical use:
1263 <literallayout class='monospaced'>
1264 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1265 ${LAYERDIR}/recipes-*/*/*.bbappend"
1266 </literallayout>
1267 Consequently, you need to be sure you locate your new recipe
1268 inside your layer such that it can be found.</para>
1269 <para>You can find more information on how layers are
1270 structured in the
1271 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1272 section.</para></listitem>
1273 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1274 When you name your recipe, you need to follow this naming
1275 convention:
1276 <literallayout class='monospaced'>
1277 <replaceable>basename</replaceable>_<replaceable>version</replaceable>.bb
1278 </literallayout>
1279 Use lower-cased characters and do not include the reserved
1280 suffixes <filename>-native</filename>,
1281 <filename>-cross</filename>, <filename>-initial</filename>,
1282 or <filename>-dev</filename> casually (i.e. do not use them
1283 as part of your recipe name unless the string applies).
1284 Here are some examples:
1285 <literallayout class='monospaced'>
1286 cups_1.7.0.bb
1287 gawk_4.0.2.bb
1288 irssi_0.8.16-rc1.bb
1289 </literallayout></para></listitem>
1290 </itemizedlist>
1291 </section>
1292
1293 <section id='understanding-recipe-syntax'>
1294 <title>Understanding Recipe Syntax</title>
1295
1296 <para>
1297 Understanding recipe file syntax is important for
1298 writing recipes.
1299 The following list overviews the basic items that make up a
1300 BitBake recipe file.
1301 For more complete BitBake syntax descriptions, see the
1302 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
1303 chapter of the BitBake User Manual.
1304 <itemizedlist>
1305 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1306 Variable assignments allow a value to be assigned to a
1307 variable.
1308 The assignment can be static text or might include
1309 the contents of other variables.
1310 In addition to the assignment, appending and prepending
1311 operations are also supported.</para>
1312 <para>The following example shows some of the ways
1313 you can use variables in recipes:
1314 <literallayout class='monospaced'>
1315 S = "${WORKDIR}/postfix-${PV}"
1316 CFLAGS += "-DNO_ASM"
1317 SRC_URI_append = " file://fixup.patch"
1318 </literallayout>
1319 </para></listitem>
1320 <listitem><para><emphasis>Functions:</emphasis>
1321 Functions provide a series of actions to be performed.
1322 You usually use functions to override the default
1323 implementation of a task function or to complement
1324 a default function (i.e. append or prepend to an
1325 existing function).
1326 Standard functions use <filename>sh</filename> shell
1327 syntax, although access to OpenEmbedded variables and
1328 internal methods are also available.</para>
1329 <para>The following is an example function from the
1330 <filename>sed</filename> recipe:
1331 <literallayout class='monospaced'>
1332 do_install () {
1333 autotools_do_install
1334 install -d ${D}${base_bindir}
1335 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
1336 rmdir ${D}${bindir}/
1337 }
1338 </literallayout>
1339 It is also possible to implement new functions that
1340 are called between existing tasks as long as the
1341 new functions are not replacing or complementing the
1342 default functions.
1343 You can implement functions in Python
1344 instead of shell.
1345 Both of these options are not seen in the majority of
1346 recipes.</para></listitem>
1347 <listitem><para><emphasis>Keywords:</emphasis>
1348 BitBake recipes use only a few keywords.
1349 You use keywords to include common
1350 functions (<filename>inherit</filename>), load parts
1351 of a recipe from other files
1352 (<filename>include</filename> and
1353 <filename>require</filename>) and export variables
1354 to the environment (<filename>export</filename>).</para>
1355 <para>The following example shows the use of some of
1356 these keywords:
1357 <literallayout class='monospaced'>
1358 export POSTCONF = "${STAGING_BINDIR}/postconf"
1359 inherit autoconf
1360 require otherfile.inc
1361 </literallayout>
1362 </para></listitem>
1363 <listitem><para><emphasis>Comments:</emphasis>
1364 Any lines that begin with the hash character
1365 (<filename>#</filename>) are treated as comment lines
1366 and are ignored:
1367 <literallayout class='monospaced'>
1368 # This is a comment
1369 </literallayout>
1370 </para></listitem>
1371 </itemizedlist>
1372 </para>
1373
1374 <para>
1375 This next list summarizes the most important and most commonly
1376 used parts of the recipe syntax.
1377 For more information on these parts of the syntax, you can
1378 reference the
1379 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1380 chapter in the BitBake User Manual.
1381 <itemizedlist>
1382 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1383 Use the backward slash (<filename>\</filename>)
1384 character to split a statement over multiple lines.
1385 Place the slash character at the end of the line that
1386 is to be continued on the next line:
1387 <literallayout class='monospaced'>
1388 VAR = "A really long \
1389 line"
1390 </literallayout>
1391 <note>
1392 You cannot have any characters including spaces
1393 or tabs after the slash character.
1394 </note>
1395 </para></listitem>
1396 <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1397 Use the <filename>${<replaceable>varname</replaceable>}</filename> syntax to
1398 access the contents of a variable:
1399 <literallayout class='monospaced'>
1400 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1401 </literallayout>
1402 </para></listitem>
1403 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1404 Use double quotes around the value in all variable
1405 assignments.
1406 <literallayout class='monospaced'>
1407 VAR1 = "${OTHERVAR}"
1408 VAR2 = "The version is ${PV}"
1409 </literallayout>
1410 </para></listitem>
1411 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1412 Conditional assignment is used to assign a value to
1413 a variable, but only when the variable is currently
1414 unset.
1415 Use the question mark followed by the equal sign
1416 (<filename>?=</filename>) to make a "soft" assignment
1417 used for conditional assignment.
1418 Typically, "soft" assignments are used in the
1419 <filename>local.conf</filename> file for variables
1420 that are allowed to come through from the external
1421 environment.
1422 </para>
1423 <para>Here is an example where
1424 <filename>VAR1</filename> is set to "New value" if
1425 it is currently empty.
1426 However, if <filename>VAR1</filename> has already been
1427 set, it remains unchanged:
1428 <literallayout class='monospaced'>
1429 VAR1 ?= "New value"
1430 </literallayout>
1431 In this next example, <filename>VAR1</filename>
1432 is left with the value "Original value":
1433 <literallayout class='monospaced'>
1434 VAR1 = "Original value"
1435 VAR1 ?= "New value"
1436 </literallayout>
1437 </para></listitem>
1438 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1439 Use the plus character followed by the equals sign
1440 (<filename>+=</filename>) to append values to existing
1441 variables.
1442 <note>
1443 This operator adds a space between the existing
1444 content of the variable and the new content.
1445 </note></para>
1446 <para>Here is an example:
1447 <literallayout class='monospaced'>
1448 SRC_URI += "file://fix-makefile.patch"
1449 </literallayout>
1450 </para></listitem>
1451 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1452 Use the equals sign followed by the plus character
1453 (<filename>=+</filename>) to prepend values to existing
1454 variables.
1455 <note>
1456 This operator adds a space between the new content
1457 and the existing content of the variable.
1458 </note></para>
1459 <para>Here is an example:
1460 <literallayout class='monospaced'>
1461 VAR =+ "Starts"
1462 </literallayout>
1463 </para></listitem>
1464 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1465 Use the <filename>_append</filename> operator to
1466 append values to existing variables.
1467 This operator does not add any additional space.
1468 Also, the operator is applied after all the
1469 <filename>+=</filename>, and
1470 <filename>=+</filename> operators have been applied and
1471 after all <filename>=</filename> assignments have
1472 occurred.
1473 </para>
1474 <para>The following example shows the space being
1475 explicitly added to the start to ensure the appended
1476 value is not merged with the existing value:
1477 <literallayout class='monospaced'>
1478 SRC_URI_append = " file://fix-makefile.patch"
1479 </literallayout>
1480 You can also use the <filename>_append</filename>
1481 operator with overrides, which results in the actions
1482 only being performed for the specified target or
1483 machine:
1484 <literallayout class='monospaced'>
1485 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1486 </literallayout>
1487 </para></listitem>
1488 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1489 Use the <filename>_prepend</filename> operator to
1490 prepend values to existing variables.
1491 This operator does not add any additional space.
1492 Also, the operator is applied after all the
1493 <filename>+=</filename>, and
1494 <filename>=+</filename> operators have been applied and
1495 after all <filename>=</filename> assignments have
1496 occurred.
1497 </para>
1498 <para>The following example shows the space being
1499 explicitly added to the end to ensure the prepended
1500 value is not merged with the existing value:
1501 <literallayout class='monospaced'>
1502 CFLAGS_prepend = "-I${S}/myincludes "
1503 </literallayout>
1504 You can also use the <filename>_prepend</filename>
1505 operator with overrides, which results in the actions
1506 only being performed for the specified target or
1507 machine:
1508 <literallayout class='monospaced'>
1509 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1510 </literallayout>
1511 </para></listitem>
1512 <listitem><para><emphasis>Overrides:</emphasis> -
1513 You can use overrides to set a value conditionally,
1514 typically based on how the recipe is being built.
1515 For example, to set the
1516 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1517 variable's value to "standard/base" for any target
1518 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1519 except for qemuarm where it should be set to
1520 "standard/arm-versatile-926ejs", you would do the
1521 following:
1522 <literallayout class='monospaced'>
1523 KBRANCH = "standard/base"
1524 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1525 </literallayout>
1526 Overrides are also used to separate alternate values
1527 of a variable in other situations.
1528 For example, when setting variables such as
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1530 and
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1532 that are specific to individual packages produced by
1533 a recipe, you should always use an override that
1534 specifies the name of the package.
1535 </para></listitem>
1536 <listitem><para><emphasis>Indentation:</emphasis>
1537 Use spaces for indentation rather than than tabs.
1538 For shell functions, both currently work.
1539 However, it is a policy decision of the Yocto Project
1540 to use tabs in shell functions.
1541 Realize that some layers have a policy to use spaces
1542 for all indentation.
1543 </para></listitem>
1544 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1545 For more advanced processing, it is possible to use
1546 Python code during variable assignments (e.g.
1547 search and replacement on a variable).</para>
1548 <para>You indicate Python code using the
1549 <filename>${@<replaceable>python_code</replaceable>}</filename>
1550 syntax for the variable assignment:
1551 <literallayout class='monospaced'>
1552 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1553 </literallayout>
1554 </para></listitem>
1555 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1556 Write shell functions as if you were writing a shell
1557 script when you describe a list of actions to take.
1558 You should ensure that your script works with a generic
1559 <filename>sh</filename> and that it does not require
1560 any <filename>bash</filename> or other shell-specific
1561 functionality.
1562 The same considerations apply to various system
1563 utilities (e.g. <filename>sed</filename>,
1564 <filename>grep</filename>, <filename>awk</filename>,
1565 and so forth) that you might wish to use.
1566 If in doubt, you should check with multiple
1567 implementations - including those from BusyBox.
1568 </para></listitem>
1569 </itemizedlist>
1570 </para>
1571 </section>
1572
1573 <section id='new-recipe-running-a-build-on-the-recipe'>
1574 <title>Running a Build on the Recipe</title>
1575
1576 <para>
1577 Creating a new recipe is usually an iterative process that
1578 requires using BitBake to process the recipe multiple times in
1579 order to progressively discover and add information to the
1580 recipe file.
1581 </para>
1582
1583 <para>
1584 Assuming you have sourced a build environment setup script (i.e.
1585 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1586 or
1587 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1588 and you are in the
1589 <link linkend='build-directory'>Build Directory</link>,
1590 use BitBake to process your recipe.
1591 All you need to provide is the
1592 <filename><replaceable>basename</replaceable></filename> of the recipe as described
1593 in the previous section:
1594 <literallayout class='monospaced'>
1595 $ bitbake <replaceable>basename</replaceable>
1596 </literallayout>
1597
1598 </para>
1599
1600 <para>
1601 During the build, the OpenEmbedded build system creates a
1602 temporary work directory for each recipe
1603 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1604 where it keeps extracted source files, log files, intermediate
1605 compilation and packaging files, and so forth.
1606 </para>
1607
1608 <para>
1609 The per-recipe temporary work directory is constructed as follows and
1610 depends on several factors:
1611 <literallayout class='monospaced'>
1612 BASE_WORKDIR ?= "${TMPDIR}/work"
1613 WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
1614 </literallayout>
1615 As an example, assume a Source Directory top-level folder named
1616 <filename>poky</filename>, a default Build Directory at
1617 <filename>poky/build</filename>, and a
1618 <filename>qemux86-poky-linux</filename> machine target system.
1619 Furthermore, suppose your recipe is named
1620 <filename>foo_1.3.0.bb</filename>.
1621 In this case, the work directory the build system uses to
1622 build the package would be as follows:
1623 <literallayout class='monospaced'>
1624 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1625 </literallayout>
1626 Inside this directory you can find sub-directories such as
1627 <filename>image</filename>, <filename>packages-split</filename>,
1628 and <filename>temp</filename>.
1629 After the build, you can examine these to determine how well
1630 the build went.
1631 <note>
1632 You can find log files for each task in the recipe's
1633 <filename>temp</filename> directory (e.g.
1634 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1635 Log files are named <filename>log.<replaceable>taskname</replaceable></filename>
1636 (e.g. <filename>log.do_configure</filename>,
1637 <filename>log.do_fetch</filename>, and
1638 <filename>log.do_compile</filename>).
1639 </note>
1640 </para>
1641
1642 <para>
1643 You can find more information about the build process in the
1644 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1645 chapter of the Yocto Project Reference Manual.
1646 </para>
1647
1648 <para>
1649 You can also reference the following variables in the
1650 Yocto Project Reference Manual's glossary for more information:
1651 <itemizedlist>
1652 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1653 The top-level build output directory</listitem>
1654 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1655 The target system identifier</listitem>
1656 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1657 The recipe name</listitem>
1658 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1659 The epoch - (if
1660 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1661 is not specified, which is usually the case for most
1662 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1663 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1664 The recipe version</listitem>
1665 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1666 The recipe revision</listitem>
1667 </itemizedlist>
1668 </para>
1669 </section>
1670
1671 <section id='new-recipe-fetching-code'>
1672 <title>Fetching Code</title>
1673
1674 <para>
1675 The first thing your recipe must do is specify how to fetch
1676 the source files.
1677 Fetching is controlled mainly through the
1678 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1679 variable.
1680 Your recipe must have a <filename>SRC_URI</filename> variable
1681 that points to where the source is located.
1682 For a graphical representation of source locations, see the
1683 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1684 section in the Yocto Project Reference Manual.
1685 </para>
1686
1687 <para>
1688 The
1689 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1690 task uses the prefix of each entry in the
1691 <filename>SRC_URI</filename> variable value to determine which
1692 fetcher to use to get your source files.
1693 It is the <filename>SRC_URI</filename> variable that triggers
1694 the fetcher.
1695 The
1696 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1697 task uses the variable after source is fetched to apply
1698 patches.
1699 The OpenEmbedded build system uses
1700 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1701 for scanning directory locations for local files in
1702 <filename>SRC_URI</filename>.
1703 </para>
1704
1705 <para>
1706 The <filename>SRC_URI</filename> variable in your recipe must
1707 define each unique location for your source files.
1708 It is good practice to not hard-code pathnames in an URL used
1709 in <filename>SRC_URI</filename>.
1710 Rather than hard-code these paths, use
1711 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1712 which causes the fetch process to use the version specified in
1713 the recipe filename.
1714 Specifying the version in this manner means that upgrading the
1715 recipe to a future version is as simple as renaming the recipe
1716 to match the new version.
1717 </para>
1718
1719 <para>
1720 Here is a simple example from the
1721 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb</filename>
1722 recipe where the source comes from a single tarball.
1723 Notice the use of the
1724 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1725 variable:
1726 <literallayout class='monospaced'>
1727 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1728 </literallayout>
1729 </para>
1730
1731 <para>
1732 Files mentioned in <filename>SRC_URI</filename> whose names end
1733 in a typical archive extension (e.g. <filename>.tar</filename>,
1734 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1735 <filename>.zip</filename>, and so forth), are automatically
1736 extracted during the
1737 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1738 task.
1739 For another example that specifies these types of files, see
1740 the
1741 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1742 section.
1743 </para>
1744
1745 <para>
1746 Another way of specifying source is from an SCM.
1747 For Git repositories, you must specify
1748 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1749 and you should specify
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1751 to include the revision with
1752 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1753 Here is an example from the recipe
1754 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1755 <literallayout class='monospaced'>
1756 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1757
1758 PR = "r6"
1759 PV = "1.0.5+git${SRCPV}"
1760
1761 SRC_URI = "git://git.kernel.dk/blktrace.git \
1762 file://ldflags.patch"
1763 </literallayout>
1764 </para>
1765
1766 <para>
1767 If your <filename>SRC_URI</filename> statement includes
1768 URLs pointing to individual files fetched from a remote server
1769 other than a version control system, BitBake attempts to
1770 verify the files against checksums defined in your recipe to
1771 ensure they have not been tampered with or otherwise modified
1772 since the recipe was written.
1773 Two checksums are used:
1774 <filename>SRC_URI[md5sum]</filename> and
1775 <filename>SRC_URI[sha256sum]</filename>.
1776 </para>
1777
1778 <para>
1779 If your <filename>SRC_URI</filename> variable points to
1780 more than a single URL (excluding SCM URLs), you need to
1781 provide the <filename>md5</filename> and
1782 <filename>sha256</filename> checksums for each URL.
1783 For these cases, you provide a name for each URL as part of
1784 the <filename>SRC_URI</filename> and then reference that name
1785 in the subsequent checksum statements.
1786 Here is an example:
1787 <literallayout class='monospaced'>
1788 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1789 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1790
1791 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1792 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1793
1794 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1795 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1796 </literallayout>
1797 </para>
1798
1799 <para>
1800 Proper values for <filename>md5</filename> and
1801 <filename>sha256</filename> checksums might be available
1802 with other signatures on the download page for the upstream
1803 source (e.g. <filename>md5</filename>,
1804 <filename>sha1</filename>, <filename>sha256</filename>,
1805 <filename>GPG</filename>, and so forth).
1806 Because the OpenEmbedded build system only deals with
1807 <filename>sha256sum</filename> and <filename>md5sum</filename>,
1808 you should verify all the signatures you find by hand.
1809 </para>
1810
1811 <para>
1812 If no <filename>SRC_URI</filename> checksums are specified
1813 when you attempt to build the recipe, the build will produce
1814 an error for each missing checksum.
1815 As part of the error message, the build system provides
1816 the checksum string corresponding to the fetched file.
1817 Once you have the correct checksums, you can copy and paste
1818 them into your recipe and then run the build again to continue.
1819 <note>
1820 As mentioned, if the upstream source provides signatures
1821 for verifying the downloaded source code, you should
1822 verify those manually before setting the checksum values
1823 in the recipe and continuing with the build.
1824 </note>
1825 </para>
1826
1827 <para>
1828 This final example is a bit more complicated and is from the
1829 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb</filename>
1830 recipe.
1831 The example's <filename>SRC_URI</filename> statement identifies
1832 multiple files as the source files for the recipe: a tarball, a
1833 patch file, a desktop file, and an icon.
1834 <literallayout class='monospaced'>
1835 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1836 file://xwc.patch \
1837 file://rxvt.desktop \
1838 file://rxvt.png"
1839 </literallayout>
1840 </para>
1841
1842 <para>
1843 When you specify local files using the
1844 <filename>file://</filename> URI protocol, the build system
1845 fetches files from the local machine.
1846 The path is relative to the
1847 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1848 variable and searches specific directories in a certain order:
1849 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1850 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1851 and <filename>files</filename>.
1852 The directories are assumed to be subdirectories of the
1853 directory in which the recipe or append file resides.
1854 For another example that specifies these types of files, see the
1855 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1856 section.
1857 </para>
1858
1859 <para>
1860 The previous example also specifies a patch file.
1861 Patch files are files whose names end in
1862 <filename>.patch</filename> or <filename>.diff</filename>.
1863 The build system automatically applies patches as described
1864 in the
1865 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1866 </para>
1867 </section>
1868
1869 <section id='new-recipe-unpacking-code'>
1870 <title>Unpacking Code</title>
1871
1872 <para>
1873 During the build, the
1874 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1875 task unpacks the source with
1876 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1877 pointing to where it is unpacked.
1878 </para>
1879
1880 <para>
1881 If you are fetching your source files from an upstream source
1882 archived tarball and the tarball's internal structure matches
1883 the common convention of a top-level subdirectory named
1884 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1885 then you do not need to set <filename>S</filename>.
1886 However, if <filename>SRC_URI</filename> specifies to fetch
1887 source from an archive that does not use this convention,
1888 or from an SCM like Git or Subversion, your recipe needs to
1889 define <filename>S</filename>.
1890 </para>
1891
1892 <para>
1893 If processing your recipe using BitBake successfully unpacks
1894 the source files, you need to be sure that the directory
1895 pointed to by <filename>${S}</filename> matches the structure
1896 of the source.
1897 </para>
1898 </section>
1899
1900 <section id='new-recipe-patching-code'>
1901 <title>Patching Code</title>
1902
1903 <para>
1904 Sometimes it is necessary to patch code after it has been
1905 fetched.
1906 Any files mentioned in <filename>SRC_URI</filename> whose
1907 names end in <filename>.patch</filename> or
1908 <filename>.diff</filename> are treated as patches.
1909 The
1910 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1911 task automatically applies these patches.
1912 </para>
1913
1914 <para>
1915 The build system should be able to apply patches with the "-p1"
1916 option (i.e. one directory level in the path will be stripped
1917 off).
1918 If your patch needs to have more directory levels stripped off,
1919 specify the number of levels using the "striplevel" option in
1920 the <filename>SRC_URI</filename> entry for the patch.
1921 Alternatively, if your patch needs to be applied in a specific
1922 subdirectory that is not specified in the patch file, use the
1923 "patchdir" option in the entry.
1924 </para>
1925
1926 <para>
1927 As with all local files referenced in
1928 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1929 using <filename>file://</filename>, you should place
1930 patch files in a directory next to the recipe either
1931 named the same as the base name of the recipe
1932 (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
1933 or "files".
1934 </para>
1935 </section>
1936
1937 <section id='new-recipe-licensing'>
1938 <title>Licensing</title>
1939
1940 <para>
1941 Your recipe needs to have both the
1942 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1943 and
1944 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1945 variables:
1946 <itemizedlist>
1947 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1948 This variable specifies the license for the software.
1949 If you do not know the license under which the software
1950 you are building is distributed, you should go to the
1951 source code and look for that information.
1952 Typical files containing this information include
1953 <filename>COPYING</filename>,
1954 <filename>LICENSE</filename>, and
1955 <filename>README</filename> files.
1956 You could also find the information near the top of
1957 a source file.
1958 For example, given a piece of software licensed under
1959 the GNU General Public License version 2, you would
1960 set <filename>LICENSE</filename> as follows:
1961 <literallayout class='monospaced'>
1962 LICENSE = "GPLv2"
1963 </literallayout></para>
1964 <para>The licenses you specify within
1965 <filename>LICENSE</filename> can have any name as long
1966 as you do not use spaces, since spaces are used as
1967 separators between license names.
1968 For standard licenses, use the names of the files in
1969 <filename>meta/files/common-licenses/</filename>
1970 or the <filename>SPDXLICENSEMAP</filename> flag names
1971 defined in <filename>meta/conf/licenses.conf</filename>.
1972 </para></listitem>
1973 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1974 The OpenEmbedded build system uses this variable to
1975 make sure the license text has not changed.
1976 If it has, the build produces an error and it affords
1977 you the chance to figure it out and correct the problem.
1978 </para>
1979 <para>You need to specify all applicable licensing
1980 files for the software.
1981 At the end of the configuration step, the build process
1982 will compare the checksums of the files to be sure
1983 the text has not changed.
1984 Any differences result in an error with the message
1985 containing the current checksum.
1986 For more explanation and examples of how to set the
1987 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1988 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1989 section in the Yocto Project Reference Manual.</para>
1990 <para>To determine the correct checksum string, you
1991 can list the appropriate files in the
1992 <filename>LIC_FILES_CHKSUM</filename> variable with
1993 incorrect md5 strings, attempt to build the software,
1994 and then note the resulting error messages that will
1995 report the correct md5 strings.
1996 See the
1997 "<link linkend='new-recipe-fetching-code'>Fetching Code</link>"
1998 section for additional information.
1999 </para>
2000
2001 <para>
2002 Here is an example that assumes the software has a
2003 <filename>COPYING</filename> file:
2004 <literallayout class='monospaced'>
2005 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
2006 </literallayout>
2007 When you try to build the software, the build system
2008 will produce an error and give you the correct string
2009 that you can substitute into the recipe file for a
2010 subsequent build.
2011 </para></listitem>
2012 </itemizedlist>
2013 </para>
2014
2015<!--
2016
2017 <para>
2018 For trying this out I created a new recipe named
2019 <filename>htop_1.0.2.bb</filename> and put it in
2020 <filename>poky/meta/recipes-extended/htop</filename>.
2021 There are two license type statements in my very simple
2022 recipe:
2023 <literallayout class='monospaced'>
2024 LICENSE = ""
2025
2026 LIC_FILES_CHKSUM = ""
2027
2028 SRC_URI[md5sum] = ""
2029 SRC_URI[sha256sum] = ""
2030 </literallayout>
2031 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
2032 Next, you delete or comment out the two <filename>SRC_URI</filename>
2033 lines at the end and then attempt to build the software with
2034 <filename>bitbake htop</filename>.
2035 Doing so causes BitBake to report some errors and and give
2036 you the actual strings you need for the last two
2037 <filename>SRC_URI</filename> lines.
2038 Prior to this, you have to dig around in the home page of the
2039 source for <filename>htop</filename> and determine that the
2040 software is released under GPLv2.
2041 You can provide that in the <filename>LICENSE</filename>
2042 statement.
2043 Now you edit your recipe to have those two strings for
2044 the <filename>SRC_URI</filename> statements:
2045 <literallayout class='monospaced'>
2046 LICENSE = "GPLv2"
2047
2048 LIC_FILES_CHKSUM = ""
2049
2050 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
2051 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
2052 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
2053 </literallayout>
2054 At this point, you can build the software again using the
2055 <filename>bitbake htop</filename> command.
2056 There is just a set of errors now associated with the
2057 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
2058 </para>
2059-->
2060
2061 </section>
2062
2063 <section id='new-recipe-configuring-the-recipe'>
2064 <title>Configuring the Recipe</title>
2065
2066 <para>
2067 Most software provides some means of setting build-time
2068 configuration options before compilation.
2069 Typically, setting these options is accomplished by running a
2070 configure script with some options, or by modifying a build
2071 configuration file.
2072 </para>
2073
2074 <para>
2075 A major part of build-time configuration is about checking for
2076 build-time dependencies and possibly enabling optional
2077 functionality as a result.
2078 You need to specify any build-time dependencies for the
2079 software you are building in your recipe's
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2081 value, in terms of other recipes that satisfy those
2082 dependencies.
2083 You can often find build-time or runtime
2084 dependencies described in the software's documentation.
2085 </para>
2086
2087 <para>
2088 The following list provides configuration items of note based
2089 on how your software is built:
2090 <itemizedlist>
2091 <listitem><para><emphasis>Autotools:</emphasis>
2092 If your source files have a
2093 <filename>configure.ac</filename> file, then your
2094 software is built using Autotools.
2095 If this is the case, you just need to worry about
2096 modifying the configuration.</para>
2097 <para>When using Autotools, your recipe needs to inherit
2098 the
2099 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2100 class and your recipe does not have to contain a
2101 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2102 task.
2103 However, you might still want to make some adjustments.
2104 For example, you can set
2105 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
2106 to pass any needed configure options that are specific
2107 to the recipe.</para></listitem>
2108 <listitem><para><emphasis>CMake:</emphasis>
2109 If your source files have a
2110 <filename>CMakeLists.txt</filename> file, then your
2111 software is built using CMake.
2112 If this is the case, you just need to worry about
2113 modifying the configuration.</para>
2114 <para>When you use CMake, your recipe needs to inherit
2115 the
2116 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2117 class and your recipe does not have to contain a
2118 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2119 task.
2120 You can make some adjustments by setting
2121 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
2122 to pass any needed configure options that are specific
2123 to the recipe.</para></listitem>
2124 <listitem><para><emphasis>Other:</emphasis>
2125 If your source files do not have a
2126 <filename>configure.ac</filename> or
2127 <filename>CMakeLists.txt</filename> file, then your
2128 software is built using some method other than Autotools
2129 or CMake.
2130 If this is the case, you normally need to provide a
2131 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2132 task in your recipe
2133 unless, of course, there is nothing to configure.
2134 </para>
2135 <para>Even if your software is not being built by
2136 Autotools or CMake, you still might not need to deal
2137 with any configuration issues.
2138 You need to determine if configuration is even a required step.
2139 You might need to modify a Makefile or some configuration file
2140 used for the build to specify necessary build options.
2141 Or, perhaps you might need to run a provided, custom
2142 configure script with the appropriate options.</para>
2143 <para>For the case involving a custom configure
2144 script, you would run
2145 <filename>./configure &dash;&dash;help</filename> and look for
2146 the options you need to set.</para></listitem>
2147 </itemizedlist>
2148 </para>
2149
2150 <para>
2151 Once configuration succeeds, it is always good practice to
2152 look at the <filename>log.do_configure</filename> file to
2153 ensure that the appropriate options have been enabled and no
2154 additional build-time dependencies need to be added to
2155 <filename>DEPENDS</filename>.
2156 For example, if the configure script reports that it found
2157 something not mentioned in <filename>DEPENDS</filename>, or
2158 that it did not find something that it needed for some
2159 desired optional functionality, then you would need to add
2160 those to <filename>DEPENDS</filename>.
2161 Looking at the log might also reveal items being checked for,
2162 enabled, or both that you do not want, or items not being found
2163 that are in <filename>DEPENDS</filename>, in which case
2164 you would need to look at passing extra options to the
2165 configure script as needed.
2166 For reference information on configure options specific to the
2167 software you are building, you can consult the output of the
2168 <filename>./configure &dash;&dash;help</filename> command within
2169 <filename>${S}</filename> or consult the software's upstream
2170 documentation.
2171 </para>
2172 </section>
2173
2174 <section id='new-recipe-compilation'>
2175 <title>Compilation</title>
2176
2177 <para>
2178 During a build, the <filename>do_compile</filename> task
2179 happens after source is fetched, unpacked, and configured.
2180 If the recipe passes through <filename>do_compile</filename>
2181 successfully, nothing needs to be done.
2182 </para>
2183
2184 <para>
2185 However, if the compile step fails, you need to diagnose the
2186 failure.
2187 Here are some common issues that cause failures:
2188 <itemizedlist>
2189 <listitem><para><emphasis>Parallel build failures:</emphasis>
2190 These failures manifest themselves as intermittent
2191 errors, or errors reporting that a file or directory
2192 that should be created by some other part of the build
2193 process could not be found.
2194 This type of failure can occur even if, upon inspection,
2195 the file or directory does exist after the build has
2196 failed, because that part of the build process happened
2197 in the wrong order.</para>
2198 <para>To fix the problem, you need to either satisfy
2199 the missing dependency in the Makefile or whatever
2200 script produced the Makefile, or (as a workaround)
2201 set
2202 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
2203 to an empty string:
2204 <literallayout class='monospaced'>
2205 PARALLEL_MAKE = ""
2206 </literallayout></para>
2207 <para>
2208 For information on parallel Makefile issues, see the
2209 "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
2210 section.
2211 </para></listitem>
2212 <listitem><para><emphasis>Improper host path usage:</emphasis>
2213 This failure applies to recipes building for the target
2214 or <filename>nativesdk</filename> only.
2215 The failure occurs when the compilation process uses
2216 improper headers, libraries, or other files from the
2217 host system when cross-compiling for the target.
2218 </para>
2219 <para>To fix the problem, examine the
2220 <filename>log.do_compile</filename> file to identify
2221 the host paths being used (e.g.
2222 <filename>/usr/include</filename>,
2223 <filename>/usr/lib</filename>, and so forth) and then
2224 either add configure options, apply a patch, or do both.
2225 </para></listitem>
2226 <listitem><para><emphasis>Failure to find required
2227 libraries/headers:</emphasis>
2228 If a build-time dependency is missing because it has
2229 not been declared in
2230 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2231 or because the dependency exists but the path used by
2232 the build process to find the file is incorrect and the
2233 configure step did not detect it, the compilation
2234 process could fail.
2235 For either of these failures, the compilation process
2236 notes that files could not be found.
2237 In these cases, you need to go back and add additional
2238 options to the configure script as well as possibly
2239 add additional build-time dependencies to
2240 <filename>DEPENDS</filename>.</para>
2241 <para>Occasionally, it is necessary to apply a patch
2242 to the source to ensure the correct paths are used.
2243 If you need to specify paths to find files staged
2244 into the sysroot from other recipes, use the variables
2245 that the OpenEmbedded build system provides
2246 (e.g.
2247 <filename>STAGING_BINDIR</filename>,
2248 <filename>STAGING_INCDIR</filename>,
2249 <filename>STAGING_DATADIR</filename>, and so forth).
2250<!--
2251 (e.g.
2252 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
2253 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
2254 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
2255 and so forth).
2256-->
2257 </para></listitem>
2258 </itemizedlist>
2259 </para>
2260 </section>
2261
2262 <section id='new-recipe-installing'>
2263 <title>Installing</title>
2264
2265 <para>
2266 During <filename>do_install</filename>, the task copies the
2267 built files along with their hierarchy to locations that
2268 would mirror their locations on the target device.
2269 The installation process copies files from the
2270 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
2271 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
2272 and
2273 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
2274 directories to the
2275 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
2276 directory to create the structure as it should appear on the
2277 target system.
2278 </para>
2279
2280 <para>
2281 How your software is built affects what you must do to be
2282 sure your software is installed correctly.
2283 The following list describes what you must do for installation
2284 depending on the type of build system used by the software
2285 being built:
2286 <itemizedlist>
2287 <listitem><para><emphasis>Autotools and CMake:</emphasis>
2288 If the software your recipe is building uses Autotools
2289 or CMake, the OpenEmbedded build
2290 system understands how to install the software.
2291 Consequently, you do not have to have a
2292 <filename>do_install</filename> task as part of your
2293 recipe.
2294 You just need to make sure the install portion of the
2295 build completes with no issues.
2296 However, if you wish to install additional files not
2297 already being installed by
2298 <filename>make install</filename>, you should do this
2299 using a <filename>do_install_append</filename> function
2300 using the install command as described in
2301 the "Manual" bulleted item later in this list.
2302 </para></listitem>
2303 <listitem><para><emphasis>Other (using
2304 <filename>make install</filename>):</emphasis>
2305 You need to define a
2306 <filename>do_install</filename> function in your
2307 recipe.
2308 The function should call
2309 <filename>oe_runmake install</filename> and will likely
2310 need to pass in the destination directory as well.
2311 How you pass that path is dependent on how the
2312 <filename>Makefile</filename> being run is written
2313 (e.g. <filename>DESTDIR=${D}</filename>,
2314 <filename>PREFIX=${D}</filename>,
2315 <filename>INSTALLROOT=${D}</filename>, and so forth).
2316 </para>
2317 <para>For an example recipe using
2318 <filename>make install</filename>, see the
2319 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
2320 section.</para></listitem>
2321 <listitem><para><emphasis>Manual:</emphasis>
2322 You need to define a
2323 <filename>do_install</filename> function in your
2324 recipe.
2325 The function must first use
2326 <filename>install -d</filename> to create the
2327 directories under
2328 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
2329 Once the directories exist, your function can use
2330 <filename>install</filename> to manually install the
2331 built software into the directories.</para>
2332 <para>You can find more information on
2333 <filename>install</filename> at
2334 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
2335 </para></listitem>
2336 </itemizedlist>
2337 </para>
2338
2339 <para>
2340 For the scenarios that do not use Autotools or
2341 CMake, you need to track the installation
2342 and diagnose and fix any issues until everything installs
2343 correctly.
2344 You need to look in the default location of
2345 <filename>${D}</filename>, which is
2346 <filename>${WORKDIR}/image</filename>, to be sure your
2347 files have been installed correctly.
2348 </para>
2349
2350 <note><title>Notes</title>
2351 <itemizedlist>
2352 <listitem><para>
2353 During the installation process, you might need to
2354 modify some of the installed files to suit the target
2355 layout.
2356 For example, you might need to replace hard-coded paths
2357 in an initscript with values of variables provided by
2358 the build system, such as replacing
2359 <filename>/usr/bin/</filename> with
2360 <filename>${bindir}</filename>.
2361 If you do perform such modifications during
2362 <filename>do_install</filename>, be sure to modify the
2363 destination file after copying rather than before
2364 copying.
2365 Modifying after copying ensures that the build system
2366 can re-execute <filename>do_install</filename> if
2367 needed.
2368 </para></listitem>
2369 <listitem><para>
2370 <filename>oe_runmake install</filename>, which can be
2371 run directly or can be run indirectly by the
2372 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2373 and
2374 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2375 classes, runs <filename>make install</filename> in
2376 parallel.
2377 Sometimes, a Makefile can have missing dependencies
2378 between targets that can result in race conditions.
2379 If you experience intermittent failures during
2380 <filename>do_install</filename>, you might be able to
2381 work around them by disabling parallel Makefile
2382 installs by adding the following to the recipe:
2383 <literallayout class='monospaced'>
2384 PARALLEL_MAKEINST = ""
2385 </literallayout>
2386 See
2387 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2388 for additional information.
2389 </para></listitem>
2390 </itemizedlist>
2391 </note>
2392 </section>
2393
2394 <section id='new-recipe-enabling-system-services'>
2395 <title>Enabling System Services</title>
2396
2397 <para>
2398 If you want to install a service, which is a process that
2399 usually starts on boot and runs in the background, then
2400 you must include some additional definitions in your recipe.
2401 </para>
2402
2403 <para>
2404 If you are adding services and the service initialization
2405 script or the service file itself is not installed, you must
2406 provide for that installation in your recipe using a
2407 <filename>do_install_append</filename> function.
2408 If your recipe already has a <filename>do_install</filename>
2409 function, update the function near its end rather than
2410 adding an additional <filename>do_install_append</filename>
2411 function.
2412 </para>
2413
2414 <para>
2415 When you create the installation for your services, you need
2416 to accomplish what is normally done by
2417 <filename>make install</filename>.
2418 In other words, make sure your installation arranges the output
2419 similar to how it is arranged on the target system.
2420 </para>
2421
2422 <para>
2423 The OpenEmbedded build system provides support for starting
2424 services two different ways:
2425 <itemizedlist>
2426 <listitem><para><emphasis>SysVinit:</emphasis>
2427 SysVinit is a system and service manager that
2428 manages the init system used to control the very basic
2429 functions of your system.
2430 The init program is the first program
2431 started by the Linux kernel when the system boots.
2432 Init then controls the startup, running and shutdown
2433 of all other programs.</para>
2434 <para>To enable a service using SysVinit, your recipe
2435 needs to inherit the
2436 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2437 class.
2438 The class helps facilitate safely installing the
2439 package on the target.</para>
2440 <para>You will need to set the
2441 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2442 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2443 and
2444 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2445 variables within your recipe.</para></listitem>
2446 <listitem><para><emphasis>systemd:</emphasis>
2447 System Management Daemon (systemd) was designed to
2448 replace SysVinit and to provide
2449 enhanced management of services.
2450 For more information on systemd, see the systemd
2451 homepage at
2452 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2453 </para>
2454 <para>To enable a service using systemd, your recipe
2455 needs to inherit the
2456 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2457 class.
2458 See the <filename>systemd.bbclass</filename> file
2459 located in your
2460 <link linkend='source-directory'>Source Directory</link>.
2461 section for more information.
2462 </para></listitem>
2463 </itemizedlist>
2464 </para>
2465 </section>
2466
2467 <section id='new-recipe-packaging'>
2468 <title>Packaging</title>
2469
2470 <para>
2471 Successful packaging is a combination of automated processes
2472 performed by the OpenEmbedded build system and some
2473 specific steps you need to take.
2474 The following list describes the process:
2475 <itemizedlist>
2476 <listitem><para><emphasis>Splitting Files</emphasis>:
2477 The <filename>do_package</filename> task splits the
2478 files produced by the recipe into logical components.
2479 Even software that produces a single binary might
2480 still have debug symbols, documentation, and other
2481 logical components that should be split out.
2482 The <filename>do_package</filename> task ensures
2483 that files are split up and packaged correctly.
2484 </para></listitem>
2485 <listitem><para><emphasis>Running QA Checks</emphasis>:
2486 The
2487 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2488 class adds a step to
2489 the package generation process so that output quality
2490 assurance checks are generated by the OpenEmbedded
2491 build system.
2492 This step performs a range of checks to be sure the
2493 build's output is free of common problems that show
2494 up during runtime.
2495 For information on these checks, see the
2496 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2497 class and the
2498 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
2499 chapter in the Yocto Project Reference Manual.
2500 </para></listitem>
2501 <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
2502 After you build your software, you need to be sure
2503 your packages are correct.
2504 Examine the
2505 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2506 directory and make sure files are where you expect
2507 them to be.
2508 If you discover problems, you can set
2509 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2510 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2511 <filename>do_install(_append)</filename>, and so forth as
2512 needed.
2513 </para></listitem>
2514 <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
2515 If you need to split an application into several
2516 packages, see the
2517 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2518 section for an example.
2519 </para></listitem>
2520 <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
2521 For an example showing how to install a
2522 post-installation script, see the
2523 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2524 section.
2525 </para></listitem>
2526 <listitem><para><emphasis>Marking Package Architecture</emphasis>:
2527 Depending on what your recipe is building and how it
2528 is configured, it might be important to mark the
2529 packages produced as being specific to a particular
2530 machine, or to mark them as not being specific to
2531 a particular machine or architecture at all.
2532 By default, packages produced for the target are
2533 marked as being specific to the architecture of the
2534 target machine because that is usually the desired
2535 result.
2536 However, if the recipe configures the software to be
2537 built specific to the target machine (e.g. the
2538 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2539 value is passed into the configure script or a patch
2540 is applied only for a particular machine), then you
2541 should mark the packages produced as being
2542 machine-specific by adding the following to the
2543 recipe:
2544 <literallayout class='monospaced'>
2545 PACKAGE_ARCH = "${MACHINE_ARCH}"
2546 </literallayout>
2547 On the other hand, if the recipe produces packages
2548 that do not contain anything specific to the target
2549 machine or architecture at all (e.g. recipes
2550 that simply package script files or configuration
2551 files), you should use the
2552 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
2553 class to do this for you by adding this to your
2554 recipe:
2555 <literallayout class='monospaced'>
2556 inherit allarch
2557 </literallayout>
2558 Ensuring that the package architecture is correct is
2559 not critical while you are doing the first few builds
2560 of your recipe.
2561 However, it is important in order
2562 to ensure that your recipe rebuilds (or does not
2563 rebuild) appropriately in response to changes in
2564 configuration, and to ensure that you get the
2565 appropriate packages installed on the target machine,
2566 particularly if you run separate builds for more
2567 than one target machine.
2568 </para></listitem>
2569 </itemizedlist>
2570 </para>
2571 </section>
2572
2573 <section id='properly-versioning-pre-release-recipes'>
2574 <title>Properly Versioning Pre-Release Recipes</title>
2575
2576 <para>
2577 Sometimes the name of a recipe can lead to versioning
2578 problems when the recipe is upgraded to a final release.
2579 For example, consider the
2580 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2581 the list of example recipes in the
2582 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2583 section.
2584 This recipe is at a release candidate stage (i.e.
2585 "rc1").
2586 When the recipe is released, the recipe filename becomes
2587 <filename>irssi_0.8.16.bb</filename>.
2588 The version change from <filename>0.8.16-rc1</filename>
2589 to <filename>0.8.16</filename> is seen as a decrease by the
2590 build system and package managers, so the resulting packages
2591 will not correctly trigger an upgrade.
2592 </para>
2593
2594 <para>
2595 In order to ensure the versions compare properly, the
2596 recommended convention is to set
2597 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2598 within the recipe to
2599 "<replaceable>previous_version</replaceable>+<replaceable>current_version</replaceable>".
2600 You can use an additional variable so that you can use the
2601 current version elsewhere.
2602 Here is an example:
2603 <literallayout class='monospaced'>
2604 REALPV = "0.8.16-rc1"
2605 PV = "0.8.15+${REALPV}"
2606 </literallayout>
2607 </para>
2608 </section>
2609
2610 <section id='new-recipe-post-installation-scripts'>
2611 <title>Post-Installation Scripts</title>
2612
2613 <para>
2614 Post-installation scripts run immediately after installing
2615 a package on the target or during image creation when a
2616 package is included in an image.
2617 To add a post-installation script to a package, add a
2618 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2619 the recipe file (<filename>.bb</filename>) and replace
2620 <filename>PACKAGENAME</filename> with the name of the package
2621 you want to attach to the <filename>postinst</filename>
2622 script.
2623 To apply the post-installation script to the main package
2624 for the recipe, which is usually what is required, specify
2625 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2626 in place of <filename>PACKAGENAME</filename>.
2627 </para>
2628
2629 <para>
2630 A post-installation function has the following structure:
2631 <literallayout class='monospaced'>
2632 pkg_postinst_PACKAGENAME() {
2633 #!/bin/sh -e
2634 # Commands to carry out
2635 }
2636 </literallayout>
2637 </para>
2638
2639 <para>
2640 The script defined in the post-installation function is
2641 called when the root filesystem is created.
2642 If the script succeeds, the package is marked as installed.
2643 If the script fails, the package is marked as unpacked and
2644 the script is executed when the image boots again.
2645 </para>
2646
2647 <para>
2648 Sometimes it is necessary for the execution of a
2649 post-installation script to be delayed until the first boot.
2650 For example, the script might need to be executed on the
2651 device itself.
2652 To delay script execution until boot time, use the following
2653 structure in the post-installation script:
2654 <literallayout class='monospaced'>
2655 pkg_postinst_PACKAGENAME() {
2656 #!/bin/sh -e
2657 if [ x"$D" = "x" ]; then
2658 # Actions to carry out on the device go here
2659 else
2660 exit 1
2661 fi
2662 }
2663 </literallayout>
2664 </para>
2665
2666 <para>
2667 The previous example delays execution until the image boots
2668 again because the environment variable <filename>D</filename>
2669 points to the directory containing the image when
2670 the root filesystem is created at build time but is unset
2671 when executed on the first boot.
2672 </para>
2673
2674 <note>
2675 Equivalent support for pre-install, pre-uninstall, and
2676 post-uninstall scripts exist by way of
2677 <filename>pkg_preinst</filename>,
2678 <filename>pkg_prerm</filename>, and
2679 <filename>pkg_postrm</filename>, respectively.
2680 These scrips work in exactly the same way as does
2681 <filename>pkg_postinst</filename> with the exception that they
2682 run at different times.
2683 Also, because of when they run, they are not applicable to
2684 being run at image creation time like
2685 <filename>pkg_postinst</filename>.
2686 </note>
2687 </section>
2688
2689 <section id='new-recipe-testing'>
2690 <title>Testing</title>
2691
2692 <para>
2693 The final step for completing your recipe is to be sure that
2694 the software you built runs correctly.
2695 To accomplish runtime testing, add the build's output
2696 packages to your image and test them on the target.
2697 </para>
2698
2699 <para>
2700 For information on how to customize your image by adding
2701 specific packages, see the
2702 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2703 section.
2704 </para>
2705 </section>
2706
2707 <section id='new-recipe-testing-examples'>
2708 <title>Examples</title>
2709
2710 <para>
2711 To help summarize how to write a recipe, this section provides
2712 some examples given various scenarios:
2713 <itemizedlist>
2714 <listitem><para>Recipes that use local files</para></listitem>
2715 <listitem><para>Using an Autotooled package</para></listitem>
2716 <listitem><para>Using a Makefile-based package</para></listitem>
2717 <listitem><para>Splitting an application into multiple packages</para></listitem>
2718 <listitem><para>Adding binaries to an image</para></listitem>
2719 </itemizedlist>
2720 </para>
2721
2722 <section id='new-recipe-single-c-file-package-hello-world'>
2723 <title>Single .c File Package (Hello World!)</title>
2724
2725 <para>
2726 Building an application from a single file that is stored
2727 locally (e.g. under <filename>files</filename>) requires
2728 a recipe that has the file listed in the
2729 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2730 variable.
2731 Additionally, you need to manually write the
2732 <filename>do_compile</filename> and
2733 <filename>do_install</filename> tasks.
2734 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2735 variable defines the directory containing the source code,
2736 which is set to
2737 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2738 in this case - the directory BitBake uses for the build.
2739 <literallayout class='monospaced'>
2740 SUMMARY = "Simple helloworld application"
2741 SECTION = "examples"
2742 LICENSE = "MIT"
2743 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2744
2745 SRC_URI = "file://helloworld.c"
2746
2747 S = "${WORKDIR}"
2748
2749 do_compile() {
2750 ${CC} helloworld.c -o helloworld
2751 }
2752
2753 do_install() {
2754 install -d ${D}${bindir}
2755 install -m 0755 helloworld ${D}${bindir}
2756 }
2757 </literallayout>
2758 </para>
2759
2760 <para>
2761 By default, the <filename>helloworld</filename>,
2762 <filename>helloworld-dbg</filename>, and
2763 <filename>helloworld-dev</filename> packages are built.
2764 For information on how to customize the packaging process,
2765 see the
2766 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2767 section.
2768 </para>
2769 </section>
2770
2771 <section id='new-recipe-autotooled-package'>
2772 <title>Autotooled Package</title>
2773 <para>
2774 Applications that use Autotools such as <filename>autoconf</filename> and
2775 <filename>automake</filename> require a recipe that has a source archive listed in
2776 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2777 also inherit the
2778 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2779 class, which contains the definitions of all the steps
2780 needed to build an Autotool-based application.
2781 The result of the build is automatically packaged.
2782 And, if the application uses NLS for localization, packages with local information are
2783 generated (one package per language).
2784 Following is one example: (<filename>hello_2.3.bb</filename>)
2785 <literallayout class='monospaced'>
2786 SUMMARY = "GNU Helloworld application"
2787 SECTION = "examples"
2788 LICENSE = "GPLv2+"
2789 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2790
2791 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2792
2793 inherit autotools gettext
2794 </literallayout>
2795 </para>
2796
2797 <para>
2798 The variable
2799 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2800 is used to track source license changes as described in the
2801 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2802 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2803 </para>
2804 </section>
2805
2806 <section id='new-recipe-makefile-based-package'>
2807 <title>Makefile-Based Package</title>
2808
2809 <para>
2810 Applications that use GNU <filename>make</filename> also require a recipe that has
2811 the source archive listed in
2812 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2813 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2814 starts the <filename>make</filename> command to compile the application.
2815 If you need additional <filename>make</filename> options, you should store them in the
2816 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2817 variable.
2818 BitBake passes these options into the GNU <filename>make</filename> invocation.
2819 Note that a <filename>do_install</filename> task is still required.
2820 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2821 </para>
2822
2823 <para>
2824 Some applications might require extra parameters to be passed to the compiler.
2825 For example, the application might need an additional header path.
2826 You can accomplish this by adding to the
2827 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2828 The following example shows this:
2829 <literallayout class='monospaced'>
2830 CFLAGS_prepend = "-I ${S}/include "
2831 </literallayout>
2832 </para>
2833
2834 <para>
2835 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2836 <literallayout class='monospaced'>
2837 SUMMARY = "Tools for managing memory technology devices"
2838 SECTION = "base"
2839 DEPENDS = "zlib lzo e2fsprogs util-linux"
2840 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2841 LICENSE = "GPLv2+"
2842 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2843 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2844
2845 # Use the latest version at 26 Oct, 2013
2846 SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b"
2847 SRC_URI = "git://git.infradead.org/mtd-utils.git \
2848 file://add-exclusion-to-mkfs-jffs2-git-2.patch \
2849 "
2850
2851 PV = "1.5.1+git${SRCPV}"
2852
2853 S = "${WORKDIR}/git/"
2854
2855 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2856
2857 do_install () {
2858 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir}
2859 }
2860
2861 PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc"
2862
2863 FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool"
2864 FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*"
2865 FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image"
2866
2867 PARALLEL_MAKE = ""
2868
2869 BBCLASSEXTEND = "native"
2870 </literallayout>
2871 </para>
2872 </section>
2873
2874 <section id='splitting-an-application-into-multiple-packages'>
2875 <title>Splitting an Application into Multiple Packages</title>
2876
2877 <para>
2878 You can use the variables
2879 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2880 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2881 to split an application into multiple packages.
2882 </para>
2883
2884 <para>
2885 Following is an example that uses the <filename>libxpm</filename> recipe.
2886 By default, this recipe generates a single package that contains the library along
2887 with a few binaries.
2888 You can modify the recipe to split the binaries into separate packages:
2889 <literallayout class='monospaced'>
2890 require xorg-lib-common.inc
2891
2892 SUMMARY = "X11 Pixmap library"
2893 LICENSE = "X-BSD"
2894 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2895 DEPENDS += "libxext libsm libxt"
2896 PR = "r3"
2897 PE = "1"
2898
2899 XORG_PN = "libXpm"
2900
2901 PACKAGES =+ "sxpm cxpm"
2902 FILES_cxpm = "${bindir}/cxpm"
2903 FILES_sxpm = "${bindir}/sxpm"
2904 </literallayout>
2905 </para>
2906
2907 <para>
2908 In the previous example, we want to ship the <filename>sxpm</filename>
2909 and <filename>cxpm</filename> binaries in separate packages.
2910 Since <filename>bindir</filename> would be packaged into the main
2911 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2912 package by default, we prepend the <filename>PACKAGES</filename>
2913 variable so additional package names are added to the start of list.
2914 This results in the extra <filename>FILES_*</filename>
2915 variables then containing information that define which files and
2916 directories go into which packages.
2917 Files included by earlier packages are skipped by latter packages.
2918 Thus, the main <filename>PN</filename> package
2919 does not include the above listed files.
2920 </para>
2921 </section>
2922
2923 <section id='packaging-externally-produced-binaries'>
2924 <title>Packaging Externally Produced Binaries</title>
2925
2926 <para>
2927 Sometimes, you need to add pre-compiled binaries to an
2928 image.
2929 For example, suppose that binaries for proprietary code
2930 exist, which are created by a particular division of a
2931 company.
2932 Your part of the company needs to use those binaries as
2933 part of an image that you are building using the
2934 OpenEmbedded build system.
2935 Since you only have the binaries and not the source code,
2936 you cannot use a typical recipe that expects to fetch the
2937 source specified in
2938 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2939 and then compile it.
2940 </para>
2941
2942 <para>
2943 One method is to package the binaries and then install them
2944 as part of the image.
2945 Generally, it is not a good idea to package binaries
2946 since, among other things, it can hinder the ability to
2947 reproduce builds and could lead to compatibility problems
2948 with ABI in the future.
2949 However, sometimes you have no choice.
2950 </para>
2951
2952 <para>
2953 The easiest solution is to create a recipe that uses
2954 the
2955 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-bin-package'><filename>bin_package</filename></ulink>
2956 class and to be sure that you are using default locations
2957 for build artifacts.
2958 In most cases, the <filename>bin_package</filename> class
2959 handles "skipping" the configure and compile steps as well
2960 as sets things up to grab packages from the appropriate
2961 area.
2962 In particular, this class sets <filename>noexec</filename>
2963 on both the
2964 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2965 and
2966 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2967 tasks, sets
2968 <filename>FILES_${PN}</filename> to "/" so that it picks
2969 up all files, and sets up a
2970 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
2971 task, which effectively copies all files from
2972 <filename>${S}</filename> to <filename>${D}</filename>.
2973 The <filename>bin_package</filename> class works well when
2974 the files extracted into <filename>${S}</filename> are
2975 already laid out in the way they should be laid out
2976 on the target.
2977 For more information on these variables, see the
2978 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2979 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
2980 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>,
2981 and
2982 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
2983 variables in the Yocto Project Reference Manual's variable
2984 glossary.
2985 </para>
2986
2987 <para>
2988 If you can't use the <filename>bin_package</filename>
2989 class, you need to be sure you are doing the following:
2990 <itemizedlist>
2991 <listitem><para>Create a recipe where the
2992 <filename>do_configure</filename> and
2993 <filename>do_compile</filename> tasks do nothing:
2994 <literallayout class='monospaced'>
2995 do_configure[noexec] = "1"
2996 do_compile[noexec] = "1"
2997 </literallayout>
2998 Alternatively, you can make these tasks an empty
2999 function.
3000 </para></listitem>
3001 <listitem><para>Make sure your
3002 <filename>do_install</filename> task installs the
3003 binaries appropriately.
3004 </para></listitem>
3005 <listitem><para>Ensure that you set up
3006 <filename>FILES</filename> (usually
3007 <filename>FILES_${PN}</filename>) to point to the
3008 files you have installed, which of course depends
3009 on where you have installed them and whether
3010 those files are in different locations than the
3011 defaults.
3012 </para></listitem>
3013 </itemizedlist>
3014 </para>
3015 </section>
3016 </section>
3017 </section>
3018
3019 <section id="platdev-newmachine">
3020 <title>Adding a New Machine</title>
3021
3022 <para>
3023 Adding a new machine to the Yocto Project is a straightforward
3024 process.
3025 This section describes how to add machines that are similar
3026 to those that the Yocto Project already supports.
3027 <note>
3028 Although well within the capabilities of the Yocto Project,
3029 adding a totally new architecture might require
3030 changes to <filename>gcc/glibc</filename> and to the site
3031 information, which is beyond the scope of this manual.
3032 </note>
3033 </para>
3034
3035 <para>
3036 For a complete example that shows how to add a new machine,
3037 see the
3038 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
3039 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
3040 </para>
3041
3042 <section id="platdev-newmachine-conffile">
3043 <title>Adding the Machine Configuration File</title>
3044
3045 <para>
3046 To add a new machine, you need to add a new machine
3047 configuration file to the layer's
3048 <filename>conf/machine</filename> directory.
3049 This configuration file provides details about the device
3050 you are adding.
3051 </para>
3052
3053 <para>
3054 The OpenEmbedded build system uses the root name of the
3055 machine configuration file to reference the new machine.
3056 For example, given a machine configuration file named
3057 <filename>crownbay.conf</filename>, the build system
3058 recognizes the machine as "crownbay".
3059 </para>
3060
3061 <para>
3062 The most important variables you must set in your machine
3063 configuration file or include from a lower-level configuration
3064 file are as follows:
3065 <itemizedlist>
3066 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
3067 (e.g. "arm")</para></listitem>
3068 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
3069 </para></listitem>
3070 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
3071 (e.g. "apm screen wifi")</para></listitem>
3072 </itemizedlist>
3073 </para>
3074
3075 <para>
3076 You might also need these variables:
3077 <itemizedlist>
3078 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
3079 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
3080 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
3081 (e.g. "zImage")</para></listitem>
3082 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
3083 (e.g. "tar.gz jffs2")</para></listitem>
3084 </itemizedlist>
3085 </para>
3086
3087 <para>
3088 You can find full details on these variables in the reference
3089 section.
3090 You can leverage existing machine <filename>.conf</filename>
3091 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
3092 </para>
3093 </section>
3094
3095 <section id="platdev-newmachine-kernel">
3096 <title>Adding a Kernel for the Machine</title>
3097
3098 <para>
3099 The OpenEmbedded build system needs to be able to build a kernel
3100 for the machine.
3101 You need to either create a new kernel recipe for this machine,
3102 or extend an existing kernel recipe.
3103 You can find several kernel recipe examples in the
3104 Source Directory at
3105 <filename>meta/recipes-kernel/linux</filename>
3106 that you can use as references.
3107 </para>
3108
3109 <para>
3110 If you are creating a new kernel recipe, normal recipe-writing
3111 rules apply for setting up a
3112 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
3113 Thus, you need to specify any necessary patches and set
3114 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
3115 to point at the source code.
3116 You need to create a <filename>do_configure</filename> task that
3117 configures the unpacked kernel with a
3118 <filename>defconfig</filename> file.
3119 You can do this by using a <filename>make defconfig</filename>
3120 command or, more commonly, by copying in a suitable
3121 <filename>defconfig</filename> file and then running
3122 <filename>make oldconfig</filename>.
3123 By making use of <filename>inherit kernel</filename> and
3124 potentially some of the <filename>linux-*.inc</filename> files,
3125 most other functionality is centralized and the defaults of the
3126 class normally work well.
3127 </para>
3128
3129 <para>
3130 If you are extending an existing kernel recipe, it is usually
3131 a matter of adding a suitable <filename>defconfig</filename>
3132 file.
3133 The file needs to be added into a location similar to
3134 <filename>defconfig</filename> files used for other machines
3135 in a given kernel recipe.
3136 A possible way to do this is by listing the file in the
3137 <filename>SRC_URI</filename> and adding the machine to the
3138 expression in
3139 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
3140 <literallayout class='monospaced'>
3141 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
3142 </literallayout>
3143 </para>
3144 </section>
3145
3146 <section id="platdev-newmachine-formfactor">
3147 <title>Adding a Formfactor Configuration File</title>
3148
3149 <para>
3150 A formfactor configuration file provides information about the
3151 target hardware for which the image is being built and information that
3152 the build system cannot obtain from other sources such as the kernel.
3153 Some examples of information contained in a formfactor configuration file include
3154 framebuffer orientation, whether or not the system has a keyboard,
3155 the positioning of the keyboard in relation to the screen, and
3156 the screen resolution.
3157 </para>
3158
3159 <para>
3160 The build system uses reasonable defaults in most cases.
3161 However, if customization is
3162 necessary, you need to create a <filename>machconfig</filename> file
3163 in the <filename>meta/recipes-bsp/formfactor/files</filename>
3164 directory.
3165 This directory contains directories for specific machines such as
3166 <filename>qemuarm</filename> and <filename>qemux86</filename>.
3167 For information about the settings available and the defaults, see the
3168 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
3169 same area.
3170 </para>
3171
3172 <para>
3173 Following is an example for "qemuarm" machine:
3174 <literallayout class='monospaced'>
3175 HAVE_TOUCHSCREEN=1
3176 HAVE_KEYBOARD=1
3177
3178 DISPLAY_CAN_ROTATE=0
3179 DISPLAY_ORIENTATION=0
3180 #DISPLAY_WIDTH_PIXELS=640
3181 #DISPLAY_HEIGHT_PIXELS=480
3182 #DISPLAY_BPP=16
3183 DISPLAY_DPI=150
3184 DISPLAY_SUBPIXEL_ORDER=vrgb
3185 </literallayout>
3186 </para>
3187 </section>
3188 </section>
3189
3190 <section id="platdev-working-with-libraries">
3191 <title>Working With Libraries</title>
3192
3193 <para>
3194 Libraries are an integral part of your system.
3195 This section describes some common practices you might find
3196 helpful when working with libraries to build your system:
3197 <itemizedlist>
3198 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
3199 </para></listitem>
3200 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
3201 </para></listitem>
3202 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
3203 </para></listitem>
3204 </itemizedlist>
3205 </para>
3206
3207 <section id='including-static-library-files'>
3208 <title>Including Static Library Files</title>
3209
3210 <para>
3211 If you are building a library and the library offers static linking, you can control
3212 which static library files (<filename>*.a</filename> files) get included in the
3213 built library.
3214 </para>
3215
3216 <para>
3217 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
3218 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
3219 variables in the
3220 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
3221 by the <filename>do_install</filename> task are packaged.
3222 By default, the <filename>PACKAGES</filename> variable includes
3223 <filename>${PN}-staticdev</filename>, which represents all static library files.
3224 <note>
3225 Some previously released versions of the Yocto Project
3226 defined the static library files through
3227 <filename>${PN}-dev</filename>.
3228 </note>
3229 Following is part of the BitBake configuration file, where
3230 you can see how the static library files are defined:
3231 <literallayout class='monospaced'>
3232 PACKAGE_BEFORE_PN ?= ""
3233 PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}"
3234 PACKAGES_DYNAMIC = "^${PN}-locale-.*"
3235 FILES = ""
3236
3237 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
3238 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
3239 ${base_bindir}/* ${base_sbindir}/* \
3240 ${base_libdir}/*${SOLIBS} \
3241 ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \
3242 ${datadir}/${BPN} ${libdir}/${BPN}/* \
3243 ${datadir}/pixmaps ${datadir}/applications \
3244 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
3245 ${libdir}/bonobo/servers"
3246
3247 FILES_${PN}-bin = "${bindir}/* ${sbindir}/*"
3248
3249 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
3250 ${datadir}/gnome/help"
3251 SECTION_${PN}-doc = "doc"
3252
3253 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
3254 FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \
3255 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
3256 ${datadir}/aclocal ${base_libdir}/*.o \
3257 ${libdir}/${BPN}/*.la ${base_libdir}/*.la"
3258 SECTION_${PN}-dev = "devel"
3259 ALLOW_EMPTY_${PN}-dev = "1"
3260 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
3261
3262 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a"
3263 SECTION_${PN}-staticdev = "devel"
3264 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
3265 </literallayout>
3266 </para>
3267 </section>
3268
3269 <section id="combining-multiple-versions-library-files-into-one-image">
3270 <title>Combining Multiple Versions of Library Files into One Image</title>
3271
3272 <para>
3273 The build system offers the ability to build libraries with different
3274 target optimizations or architecture formats and combine these together
3275 into one system image.
3276 You can link different binaries in the image
3277 against the different libraries as needed for specific use cases.
3278 This feature is called "Multilib."
3279 </para>
3280
3281 <para>
3282 An example would be where you have most of a system compiled in 32-bit
3283 mode using 32-bit libraries, but you have something large, like a database
3284 engine, that needs to be a 64-bit application and uses 64-bit libraries.
3285 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
3286 </para>
3287
3288 <para>
3289 While the Multilib feature is most commonly used for 32 and 64-bit differences,
3290 the approach the build system uses facilitates different target optimizations.
3291 You could compile some binaries to use one set of libraries and other binaries
3292 to use a different set of libraries.
3293 The libraries could differ in architecture, compiler options, or other
3294 optimizations.
3295 </para>
3296
3297 <para>
3298 This section overviews the Multilib process only.
3299 For more details on how to implement Multilib, see the
3300 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
3301 page.
3302 </para>
3303
3304 <para>
3305 Aside from this wiki page, several examples exist in the
3306 <filename>meta-skeleton</filename> layer found in the
3307 <link linkend='source-directory'>Source Directory</link>:
3308 <itemizedlist>
3309 <listitem><para><filename>conf/multilib-example.conf</filename>
3310 configuration file</para></listitem>
3311 <listitem><para><filename>conf/multilib-example2.conf</filename>
3312 configuration file</para></listitem>
3313 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
3314 recipe</para></listitem>
3315 </itemizedlist>
3316 </para>
3317
3318 <section id='preparing-to-use-multilib'>
3319 <title>Preparing to Use Multilib</title>
3320
3321 <para>
3322 User-specific requirements drive the Multilib feature.
3323 Consequently, there is no one "out-of-the-box" configuration that likely
3324 exists to meet your needs.
3325 </para>
3326
3327 <para>
3328 In order to enable Multilib, you first need to ensure your recipe is
3329 extended to support multiple libraries.
3330 Many standard recipes are already extended and support multiple libraries.
3331 You can check in the <filename>meta/conf/multilib.conf</filename>
3332 configuration file in the
3333 <link linkend='source-directory'>Source Directory</link> to see how this is
3334 done using the
3335 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
3336 variable.
3337 Eventually, all recipes will be covered and this list will
3338 not be needed.
3339 </para>
3340
3341 <para>
3342 For the most part, the Multilib class extension works automatically to
3343 extend the package name from <filename>${PN}</filename> to
3344 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
3345 is the particular multilib (e.g. "lib32-" or "lib64-").
3346 Standard variables such as
3347 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
3348 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
3349 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
3350 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
3351 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, and
3352 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink>
3353 are automatically extended by the system.
3354 If you are extending any manual code in the recipe, you can use the
3355 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
3356 correctly.
3357 This automatic extension code resides in <filename>multilib.bbclass</filename>.
3358 </para>
3359 </section>
3360
3361 <section id='using-multilib'>
3362 <title>Using Multilib</title>
3363
3364 <para>
3365 After you have set up the recipes, you need to define the actual
3366 combination of multiple libraries you want to build.
3367 You accomplish this through your <filename>local.conf</filename>
3368 configuration file in the
3369 <link linkend='build-directory'>Build Directory</link>.
3370 An example configuration would be as follows:
3371 <literallayout class='monospaced'>
3372 MACHINE = "qemux86-64"
3373 require conf/multilib.conf
3374 MULTILIBS = "multilib:lib32"
3375 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
3376 IMAGE_INSTALL = "lib32-connman"
3377 </literallayout>
3378 This example enables an
3379 additional library named <filename>lib32</filename> alongside the
3380 normal target packages.
3381 When combining these "lib32" alternatives, the example uses "x86" for tuning.
3382 For information on this particular tuning, see
3383 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
3384 </para>
3385
3386 <para>
3387 The example then includes <filename>lib32-connman</filename>
3388 in all the images, which illustrates one method of including a
3389 multiple library dependency.
3390 You can use a normal image build to include this dependency,
3391 for example:
3392 <literallayout class='monospaced'>
3393 $ bitbake core-image-sato
3394 </literallayout>
3395 You can also build Multilib packages specifically with a command like this:
3396 <literallayout class='monospaced'>
3397 $ bitbake lib32-connman
3398 </literallayout>
3399 </para>
3400 </section>
3401
3402 <section id='additional-implementation-details'>
3403 <title>Additional Implementation Details</title>
3404
3405 <para>
3406 Different packaging systems have different levels of native Multilib
3407 support.
3408 For the RPM Package Management System, the following implementation details
3409 exist:
3410 <itemizedlist>
3411 <listitem><para>A unique architecture is defined for the Multilib packages,
3412 along with creating a unique deploy folder under
3413 <filename>tmp/deploy/rpm</filename> in the
3414 <link linkend='build-directory'>Build Directory</link>.
3415 For example, consider <filename>lib32</filename> in a
3416 <filename>qemux86-64</filename> image.
3417 The possible architectures in the system are "all", "qemux86_64",
3418 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
3419 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
3420 <filename>${PN}</filename> during RPM packaging.
3421 The naming for a normal RPM package and a Multilib RPM package in a
3422 <filename>qemux86-64</filename> system resolves to something similar to
3423 <filename>bash-4.1-r2.x86_64.rpm</filename> and
3424 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
3425 </para></listitem>
3426 <listitem><para>When installing a Multilib image, the RPM backend first
3427 installs the base image and then installs the Multilib libraries.
3428 </para></listitem>
3429 <listitem><para>The build system relies on RPM to resolve the identical files in the
3430 two (or more) Multilib packages.</para></listitem>
3431 </itemizedlist>
3432 </para>
3433
3434 <para>
3435 For the IPK Package Management System, the following implementation details exist:
3436 <itemizedlist>
3437 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
3438 <filename>${PN}</filename> during IPK packaging.
3439 The naming for a normal RPM package and a Multilib IPK package in a
3440 <filename>qemux86-64</filename> system resolves to something like
3441 <filename>bash_4.1-r2.x86_64.ipk</filename> and
3442 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
3443 </para></listitem>
3444 <listitem><para>The IPK deploy folder is not modified with
3445 <filename>${MLPREFIX}</filename> because packages with and without
3446 the Multilib feature can exist in the same folder due to the
3447 <filename>${PN}</filename> differences.</para></listitem>
3448 <listitem><para>IPK defines a sanity check for Multilib installation
3449 using certain rules for file comparison, overridden, etc.
3450 </para></listitem>
3451 </itemizedlist>
3452 </para>
3453 </section>
3454 </section>
3455
3456 <section id='installing-multiple-versions-of-the-same-library'>
3457 <title>Installing Multiple Versions of the Same Library</title>
3458
3459 <para>
3460 Situations can exist where you need to install and use
3461 multiple versions of the same library on the same system
3462 at the same time.
3463 These situations almost always exist when a library API
3464 changes and you have multiple pieces of software that
3465 depend on the separate versions of the library.
3466 To accommodate these situations, you can install multiple
3467 versions of the same library in parallel on the same system.
3468 </para>
3469
3470 <para>
3471 The process is straightforward as long as the libraries use
3472 proper versioning.
3473 With properly versioned libraries, all you need to do to
3474 individually specify the libraries is create separate,
3475 appropriately named recipes where the
3476 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
3477 name includes a portion that differentiates each library version
3478 (e.g.the major part of the version number).
3479 Thus, instead of having a single recipe that loads one version
3480 of a library (e.g. <filename>clutter</filename>), you provide
3481 multiple recipes that result in different versions
3482 of the libraries you want.
3483 As an example, the following two recipes would allow the
3484 two separate versions of the <filename>clutter</filename>
3485 library to co-exist on the same system:
3486 <literallayout class='monospaced'>
3487 clutter-1.6_1.6.20.bb
3488 clutter-1.8_1.8.4.bb
3489 </literallayout>
3490 Additionally, if you have other recipes that depend on a given
3491 library, you need to use the
3492 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
3493 variable to create the dependency.
3494 Continuing with the same example, if you want to have a recipe
3495 depend on the 1.8 version of the <filename>clutter</filename>
3496 library, use the following in your recipe:
3497 <literallayout class='monospaced'>
3498 DEPENDS = "clutter-1.8"
3499 </literallayout>
3500 </para>
3501 </section>
3502 </section>
3503
3504 <section id='creating-partitioned-images'>
3505 <title>Creating Partitioned Images</title>
3506
3507 <para>
3508 Creating an image for a particular hardware target using the
3509 OpenEmbedded build system does not necessarily mean you can boot
3510 that image as is on your device.
3511 Physical devices accept and boot images in various ways depending
3512 on the specifics of the device.
3513 Usually, information about the hardware can tell you what image
3514 format the device requires.
3515 Should your device require multiple partitions on an SD card, flash,
3516 or an HDD, you can use the OpenEmbedded Image Creator,
3517 <filename>wic</filename>, to create the properly partitioned image.
3518 </para>
3519
3520 <para>
3521 The <filename>wic</filename> command generates partitioned images
3522 from existing OpenEmbedded build artifacts.
3523 Image generation is driven by partitioning commands contained
3524 in an Openembedded kickstart file (<filename>.wks</filename>)
3525 specified either directly on the command line or as one of a
3526 selection of canned <filename>.wks</filename> files as shown
3527 with the <filename>wic list images</filename> command in the
3528 "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>"
3529 section.
3530 When applied to a given set of build artifacts, the result is an
3531 image or set of images that can be directly written onto media and
3532 used on a particular system.
3533 </para>
3534
3535 <para>
3536 The <filename>wic</filename> command and the infrastructure
3537 it is based on is by definition incomplete.
3538 Its purpose is to allow the generation of customized images,
3539 and as such was designed to be completely extensible through a
3540 plugin interface.
3541 See the
3542 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
3543 section for information on these plugins.
3544 </para>
3545
3546 <para>
3547 This section provides some background information on
3548 <filename>wic</filename>, describes what you need to have in
3549 place to run the tool, provides instruction on how to use
3550 <filename>wic</filename>, and provides several examples.
3551 </para>
3552
3553 <section id='wic-background'>
3554 <title>Background</title>
3555
3556 <para>
3557 This section provides some background on the
3558 <filename>wic</filename> utility.
3559 While none of this information is required to use
3560 <filename>wic</filename>, you might find it interesting.
3561 <itemizedlist>
3562 <listitem><para>
3563 The name "wic" is derived from OpenEmbedded
3564 Image Creator (oeic).
3565 The "oe" diphthong in "oeic" was promoted to the
3566 letter "w", because "oeic" is both difficult to remember and
3567 pronounce.</para></listitem>
3568 <listitem><para>
3569 <filename>wic</filename> is loosely based on the
3570 Meego Image Creator (<filename>mic</filename>)
3571 framework.
3572 The <filename>wic</filename> implementation has been
3573 heavily modified to make direct use of OpenEmbedded
3574 build artifacts instead of package installation and
3575 configuration, which are already incorporated within
3576 the OpenEmbedded artifacts.</para></listitem>
3577 <listitem><para>
3578 <filename>wic</filename> is a completely independent
3579 standalone utility that initially provides
3580 easier-to-use and more flexible replacements for a
3581 couple bits of existing functionality in OE Core's
3582 <filename>boot-directdisk.bbclass</filename> and
3583 <filename>mkefidisk.sh</filename> scripts.
3584 The difference between
3585 <filename>wic</filename> and those examples is
3586 that with <filename>wic</filename> the
3587 functionality of those scripts is implemented
3588 by a general-purpose partitioning language, which is
3589 based on Redhat kickstart syntax.</para></listitem>
3590 </itemizedlist>
3591 </para>
3592 </section>
3593
3594 <section id='wic-requirements'>
3595 <title>Requirements</title>
3596
3597 <para>
3598 In order to use the <filename>wic</filename> utility
3599 with the OpenEmbedded Build system, your system needs
3600 to meet the following requirements:
3601 <itemizedlist>
3602 <listitem><para>The Linux distribution on your
3603 development host must support the Yocto Project.
3604 See the
3605 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
3606 section in the Yocto Project Reference Manual for this
3607 list of distributions.</para></listitem>
3608 <listitem><para>
3609 The standard system utilities, such as
3610 <filename>cp</filename>, must be installed on your
3611 development host system.
3612 </para></listitem>
3613 <listitem><para>
3614 The
3615 <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink>
3616 package must be installed on your development host
3617 system.
3618 </para></listitem>
3619 <listitem><para>
3620 You need to have the build artifacts already
3621 available, which typically means that you must
3622 have already created an image using the
3623 Openembedded build system (e.g.
3624 <filename>core-image-minimal</filename>).
3625 While it might seem redundant to generate an image in
3626 order to create an image using
3627 <filename>wic</filename>, the current version of
3628 <filename>wic</filename> requires the artifacts
3629 in the form generated by the build system.
3630 </para></listitem>
3631 <listitem><para>
3632 You must have sourced one of the build environment
3633 setup scripts (i.e.
3634 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3635 or
3636 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
3637 found in the
3638 <link linkend='build-directory'>Build Directory</link>.
3639 </para></listitem>
3640 </itemizedlist>
3641 </para>
3642 </section>
3643
3644 <section id='wic-getting-help'>
3645 <title>Getting Help</title>
3646
3647 <para>
3648 You can get general help for the <filename>wic</filename>
3649 by entering the <filename>wic</filename> command by itself
3650 or by entering the command with a help argument as follows:
3651 <literallayout class='monospaced'>
3652 $ wic -h
3653 $ wic &dash;&dash;help
3654 </literallayout>
3655 </para>
3656
3657 <para>
3658 Currently, <filename>wic</filename> supports two commands:
3659 <filename>create</filename> and <filename>list</filename>.
3660 You can get help for these commands as follows:
3661 <literallayout class='monospaced'>
3662 $ wic help <replaceable>command</replaceable>
3663 </literallayout>
3664 </para>
3665
3666 <para>
3667 You can also get detailed help on a number of topics
3668 from the help system.
3669 The output of <filename>wic &dash;&dash;help</filename>
3670 displays a list of available help
3671 topics under a "Help topics" heading.
3672 You can have the help system display the help text for
3673 a given topic by prefacing the topic with
3674 <filename>wic help</filename>:
3675 <literallayout class='monospaced'>
3676 $ wic help <replaceable>help_topic</replaceable>
3677 </literallayout>
3678 </para>
3679
3680 <para>
3681 You can find out more about the images
3682 <filename>wic</filename> creates using the existing
3683 kickstart files with the following form of the command:
3684 <literallayout class='monospaced'>
3685 $ wic list <replaceable>image</replaceable> help
3686 </literallayout>
3687 where <filename><replaceable>image</replaceable></filename> is either
3688 <filename>directdisk</filename> or
3689 <filename>mkefidisk</filename>.
3690 </para>
3691 </section>
3692
3693 <section id='operational-modes'>
3694 <title>Operational Modes</title>
3695
3696 <para>
3697 You can use <filename>wic</filename> in two different
3698 modes, depending on how much control you need for
3699 specifying the Openembedded build artifacts that are
3700 used for creating the image: Raw and Cooked:
3701 <itemizedlist>
3702 <listitem><para><emphasis>Raw Mode:</emphasis>
3703 You explicitly specify build artifacts through
3704 command-line arguments.</para></listitem>
3705 <listitem><para><emphasis>Cooked Mode:</emphasis>
3706 The current
3707 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3708 setting and image name are used to automatically locate
3709 and provide the build artifacts.</para></listitem>
3710 </itemizedlist>
3711 </para>
3712
3713 <para>
3714 Regardless of the mode you use, you need to have the build
3715 artifacts ready and available.
3716 Additionally, the environment must be set up using the
3717 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3718 or
3719 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
3720 script found in the
3721 <link linkend='build-directory'>Build Directory</link>.
3722 </para>
3723
3724 <section id='raw-mode'>
3725 <title>Raw Mode</title>
3726
3727 <para>
3728 The general form of the 'wic' command in raw mode is:
3729 <literallayout class='monospaced'>
3730 $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...]
3731
3732 Where:
3733
3734 <replaceable>image_name</replaceable>.wks
3735 An OpenEmbedded kickstart file. You can provide
3736 your own custom file or use a file from a set of
3737 existing files as described by further options.
3738
3739 -o <replaceable>OUTDIR</replaceable>, &dash;&dash;outdir=<replaceable>OUTDIR</replaceable>
3740 The name of a directory in which to create image.
3741
3742 -i <replaceable>PROPERTIES_FILE</replaceable>, &dash;&dash;infile=<replaceable>PROPERTIES_FILE</replaceable>
3743 The name of a file containing the values for image
3744 properties as a JSON file.
3745
3746 -e <replaceable>IMAGE_NAME</replaceable>, &dash;&dash;image-name=<replaceable>IMAGE_NAME</replaceable>
3747 The name of the image from which to use the artifacts
3748 (e.g. <filename>core-image-sato</filename>).
3749
3750 -r <replaceable>ROOTFS_DIR</replaceable>, &dash;&dash;rootfs-dir=<replaceable>ROOTFS_DIR</replaceable>
3751 The path to the <filename>/rootfs</filename> directory to use as the
3752 <filename>.wks</filename> rootfs source.
3753
3754 -b <replaceable>BOOTIMG_DIR</replaceable>, &dash;&dash;bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable>
3755 The path to the directory containing the boot artifacts
3756 (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg
3757 source.
3758
3759 -k <replaceable>KERNEL_DIR</replaceable>, &dash;&dash;kernel-dir=<replaceable>KERNEL_DIR</replaceable>
3760 The path to the directory containing the kernel to use
3761 in the <filename>.wks</filename> boot image.
3762
3763 -n <replaceable>NATIVE_SYSROOT</replaceable>, &dash;&dash;native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable>
3764 The path to the native sysroot containing the tools to use
3765 to build the image.
3766
3767 -s, &dash;&dash;skip-build-check
3768 Skips the build check.
3769
3770 -D, &dash;&dash;debug
3771 Output debug information.
3772 </literallayout>
3773 <note>
3774 You do not need root privileges to run
3775 <filename>wic</filename>.
3776 In fact, you should not run as root when using the
3777 utility.
3778 </note>
3779 </para>
3780 </section>
3781
3782 <section id='cooked-mode'>
3783 <title>Cooked Mode</title>
3784
3785 <para>
3786 The general form of the <filename>wic</filename> command
3787 using Cooked Mode is:
3788 <literallayout class='monospaced'>
3789 $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable>
3790
3791 Where:
3792
3793 <replaceable>kickstart_file</replaceable>
3794 An OpenEmbedded kickstart file. You can provide your own
3795 custom file or supplied file.
3796
3797 <replaceable>image_name</replaceable>
3798 Specifies the image built using the OpenEmbedded build
3799 system.
3800 </literallayout>
3801 This form is the simplest and most user-friendly, as it
3802 does not require specifying all individual parameters.
3803 All you need to provide is your own
3804 <filename>.wks</filename> file or one provided with the
3805 release.
3806 </para>
3807 </section>
3808 </section>
3809
3810 <section id='using-a-provided-kickstart_file'>
3811 <title>Using an Existing Kickstart File</title>
3812
3813 <para>
3814 If you do not want to create your own
3815 <filename>.wks</filename> file, you can use an existing
3816 file provided by the <filename>wic</filename> installation.
3817 Use the following command to list the available files:
3818 <literallayout class='monospaced'>
3819 $ wic list images
3820 directdisk Create a 'pcbios' direct disk image
3821 mkefidisk Create an EFI disk image
3822 </literallayout>
3823 When you use an existing file, you do not have to use the
3824 <filename>.wks</filename> extension.
3825 Here is an example in Raw Mode that uses the
3826 <filename>directdisk</filename> file:
3827 <literallayout class='monospaced'>
3828 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \
3829 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable>
3830 </literallayout>
3831 </para>
3832
3833 <para>
3834 Here are the actual partition language commands
3835 used in the <filename>mkefidisk.wks</filename> file to generate
3836 an image:
3837 <literallayout class='monospaced'>
3838 # short-description: Create an EFI disk image
3839 # long-description: Creates a partitioned EFI disk image that the user
3840 # can directly dd to boot media.
3841
3842 part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024
3843
3844 part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
3845
3846 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
3847
3848 bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0"
3849 </literallayout>
3850 </para>
3851 </section>
3852
3853 <section id='wic-usage-examples'>
3854 <title>Examples</title>
3855
3856 <para>
3857 This section provides several examples that show how to use
3858 the <filename>wic</filename> utility.
3859 All the examples assume the list of requirements in the
3860 "<link linkend='wic-requirements'>Requirements</link>" section
3861 have been met.
3862 The examples assume the previously generated image is
3863 <filename>core-image-minimal</filename>.
3864 </para>
3865
3866 <section id='generate-an-image-using-a-provided-kickstart-file'>
3867 <title>Generate an Image using an Existing Kickstart File</title>
3868
3869 <para>
3870 This example runs in Cooked Mode and uses the
3871 <filename>mkefidisk</filename> kickstart file:
3872 <literallayout class='monospaced'>
3873 $ wic create mkefidisk -e core-image-minimal
3874 Checking basic build environment...
3875 Done.
3876
3877 Creating image(s)...
3878
3879 Info: The new image(s) can be found here:
3880 /var/tmp/wic/build/mkefidisk-201310230946-sda.direct
3881
3882 The following build artifacts were used to create the image(s):
3883 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs
3884 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg
3885 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel
3886 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
3887
3888
3889 The image(s) were created using OE kickstart file:
3890 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks
3891 </literallayout>
3892 This example shows the easiest way to create an image
3893 by running in Cooked Mode and using the
3894 <filename>-e</filename> option with an existing kickstart
3895 file.
3896 All that is necessary is to specify the image used to
3897 generate the artifacts.
3898 Your <filename>local.conf</filename> needs to have the
3899 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3900 variable set to the machine you are using, which is
3901 "minnow" in this example.
3902 </para>
3903
3904 <para>
3905 The output specifies the exact created as well as where
3906 it was created.
3907 The output also names the artifacts used and the exact
3908 <filename>.wks</filename> script that was used to generate
3909 the image.
3910 <note>
3911 You should always verify the details provided in the
3912 output to make sure that the image was indeed created
3913 exactly as expected.
3914 </note>
3915 </para>
3916
3917 <para>
3918 Continuing with the example, you can now directly
3919 <filename>dd</filename> the image to a USB stick, or
3920 whatever media for which you built your image,
3921 and boot the resulting media:
3922 <literallayout class='monospaced'>
3923 $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb
3924 [sudo] password for trz:
3925 182274+0 records in
3926 182274+0 records out
3927 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s
3928 [trz@empanada ~]$ sudo eject /dev/sdb
3929 </literallayout>
3930 </para>
3931 </section>
3932
3933 <section id='using-a-modified-kickstart-file'>
3934 <title>Using a Modified Kickstart File</title>
3935
3936 <para>
3937 Because <filename>wic</filename> image creation is driven
3938 by the kickstart file, it is easy to affect image creation
3939 by changing the parameters in the file.
3940 This next example demonstrates that through modification
3941 of the <filename>directdisk</filename> kickstart file.
3942 </para>
3943
3944 <para>
3945 As mentioned earlier, you can use the command
3946 <filename>wic list images</filename> to show the list
3947 of existing kickstart files.
3948 The directory in which these files reside is
3949 <filename>scripts/lib/image/canned-wks/</filename>
3950 located in the
3951 <link linkend='source-directory'>Source Directory</link>.
3952 Because the available files reside in this directory, you
3953 can create and add your own custom files to the directory.
3954 Subsequent use of the <filename>wic list images</filename>
3955 command would then include your kickstart files.
3956 </para>
3957
3958 <para>
3959 In this example, the existing
3960 <filename>directdisk</filename> file already does most
3961 of what is needed.
3962 However, for the hardware in this example, the image will
3963 need to boot from <filename>sdb</filename> instead of
3964 <filename>sda</filename>, which is what the
3965 <filename>directdisk</filename> kickstart file uses.
3966 </para>
3967
3968 <para>
3969 The example begins by making a copy of the
3970 <filename>directdisk.wks</filename> file in the
3971 <filename>scripts/lib/image/canned-wks</filename>
3972 directory and then changing the lines that specify the
3973 target disk from which to boot.
3974 <literallayout class='monospaced'>
3975 $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \
3976 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
3977 </literallayout>
3978 Next, the example modifies the
3979 <filename>directdisksdb.wks</filename> file and changes all
3980 instances of "<filename>&dash;&dash;ondisk sda</filename>"
3981 to "<filename>&dash;&dash;ondisk sdb</filename>".
3982 The example changes the following two lines and leaves the
3983 remaining lines untouched:
3984 <literallayout class='monospaced'>
3985 part /boot &dash;&dash;source bootimg-pcbios &dash;&dash;ondisk sdb &dash;&dash;label boot &dash;&dash;active &dash;&dash;align 1024
3986 part / &dash;&dash;source rootfs &dash;&dash;ondisk sdb &dash;&dash;fstype=ext3 &dash;&dash;label platform &dash;&dash;align 1024
3987 </literallayout>
3988 Once the lines are changed, the example generates the
3989 <filename>directdisksdb</filename> image.
3990 The command points the process at the
3991 <filename>core-image-minimal</filename> artifacts for the
3992 Next Unit of Computing (nuc)
3993 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3994 the <filename>local.conf</filename>.
3995 <literallayout class='monospaced'>
3996 $ wic create directdisksdb -e core-image-minimal
3997 Checking basic build environment...
3998 Done.
3999
4000 Creating image(s)...
4001
4002 Info: The new image(s) can be found here:
4003 /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct
4004
4005 The following build artifacts were used to create the image(s):
4006 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs
4007 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share
4008 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel
4009 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4010
4011
4012 The image(s) were created using OE kickstart file:
4013 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks
4014 </literallayout>
4015 Continuing with the example, you can now directly
4016 <filename>dd</filename> the image to a USB stick, or
4017 whatever media for which you built your image,
4018 and boot the resulting media:
4019 <literallayout class='monospaced'>
4020 $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb
4021 86018+0 records in
4022 86018+0 records out
4023 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s
4024 [trz@empanada tmp]$ sudo eject /dev/sdb
4025 </literallayout>
4026 </para>
4027 </section>
4028
4029 <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'>
4030 <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title>
4031
4032 <para>
4033 This example creates an image based on
4034 <filename>core-image-minimal</filename> and a
4035 <filename>crownbay-noemgd</filename>
4036 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4037 that works right out of the box.
4038 <literallayout class='monospaced'>
4039 $ wic create directdisk -e core-image-minimal
4040
4041 Checking basic build environment...
4042 Done.
4043
4044 Creating image(s)...
4045
4046 Info: The new image(s) can be found here:
4047 /var/tmp/wic/build/directdisk-201309252350-sda.direct
4048
4049 The following build artifacts were used to create the image(s):
4050
4051 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
4052 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
4053 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4054 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4055
4056 The image(s) were created using OE kickstart file:
4057 /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks
4058 </literallayout>
4059 </para>
4060 </section>
4061
4062 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
4063 <title>Using a Modified Kickstart File and Running in Raw Mode</title>
4064
4065 <para>
4066 This next example manually specifies each build artifact
4067 (runs in Raw Mode) and uses a modified kickstart file.
4068 The example also uses the <filename>-o</filename> option
4069 to cause <filename>wic</filename> to create the output
4070 somewhere other than the default
4071 <filename>/var/tmp/wic</filename> directory:
4072 <literallayout class='monospaced'>
4073 $ wic create ~/test.wks -o /home/trz/testwic &dash;&dash;rootfs-dir \
4074 /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \
4075 &dash;&dash;bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \
4076 &dash;&dash;kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \
4077 &dash;&dash;native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux
4078
4079 Creating image(s)...
4080
4081 Info: The new image(s) can be found here:
4082 /home/trz/testwic/build/test-201309260032-sda.direct
4083
4084 The following build artifacts were used to create the image(s):
4085
4086 ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs
4087 BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share
4088 KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4089 NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel
4090
4091 The image(s) were created using OE kickstart file:
4092 /home/trz/test.wks
4093 </literallayout>
4094 For this example,
4095 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4096 did not have to be specified in the
4097 <filename>local.conf</filename> file since the artifact is
4098 manually specified.
4099 </para>
4100 </section>
4101 </section>
4102
4103 <section id='openembedded-kickstart-plugins'>
4104 <title>Plugins</title>
4105
4106 <para>
4107 Plugins allow <filename>wic</filename> functionality to
4108 be extended and specialized by users.
4109 This section documents the plugin interface, which is
4110 currently restricted to source plugins.
4111 </para>
4112
4113 <para>
4114 Source plugins provide a mechanism to customize
4115 various aspects of the image generation process in
4116 <filename>wic</filename>, mainly the contents of
4117 partitions.
4118 The plugins provide a mechanism for mapping values
4119 specified in <filename>.wks</filename> files using the
4120 <filename>&dash;&dash;source</filename> keyword to a
4121 particular plugin implementation that populates a
4122 corresponding partition.
4123 </para>
4124
4125 <para>
4126 A source plugin is created as a subclass of
4127 <filename>SourcePlugin</filename>.
4128 The plugin file containing it is added to
4129 <filename>scripts/lib/mic/plugins/source/</filename> to
4130 make the plugin implementation available to the
4131 <filename>wic</filename> implementation.
4132 For more information, see
4133 <filename>scripts/lib/mic/pluginbase.py</filename>.
4134 </para>
4135
4136 <para>
4137 Source plugins can also be implemented and added by
4138 external layers.
4139 As such, any plugins found in a
4140 <filename>scripts/lib/mic/plugins/source/</filename>
4141 directory in an external layer are also made
4142 available.
4143 </para>
4144
4145 <para>
4146 When the <filename>wic</filename> implementation needs
4147 to invoke a partition-specific implementation, it looks
4148 for the plugin that has the same name as the
4149 <filename>&dash;&dash;source</filename> parameter given to
4150 that partition.
4151 For example, if the partition is set up as follows:
4152 <literallayout class='monospaced'>
4153 part /boot &dash;&dash;source bootimg-pcbios ...
4154 </literallayout>
4155 The methods defined as class members of the plugin
4156 having the matching <filename>bootimg-pcbios.name</filename>
4157 class member are used.
4158 </para>
4159
4160 <para>
4161 To be more concrete, here is the plugin definition that
4162 matches a
4163 <filename>&dash;&dash;source bootimg-pcbios</filename> usage,
4164 along with an example
4165 method called by the <filename>wic</filename> implementation
4166 when it needs to invoke an implementation-specific
4167 partition-preparation function:
4168 <literallayout class='monospaced'>
4169 class BootimgPcbiosPlugin(SourcePlugin):
4170 name = 'bootimg-pcbios'
4171
4172 @classmethod
4173 def do_prepare_partition(self, part, ...)
4174 </literallayout>
4175 If the subclass itself does not implement a function, a
4176 default version in a superclass is located and
4177 used, which is why all plugins must be derived from
4178 <filename>SourcePlugin</filename>.
4179 </para>
4180
4181 <para>
4182 The <filename>SourcePlugin</filename> class defines the
4183 following methods, which is the current set of methods
4184 that can be implemented or overridden by
4185 <filename>&dash;&dash;source</filename> plugins.
4186 Any methods not implemented by a
4187 <filename>SourcePlugin</filename> subclass inherit the
4188 implementations present in the
4189 <filename>SourcePlugin</filename> class.
4190 For more information, see the
4191 <filename>SourcePlugin</filename> source for details:
4192 </para>
4193
4194 <para>
4195 <itemizedlist>
4196 <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
4197 Called to do the actual content population for a
4198 partition.
4199 In other words, the method prepares the final
4200 partition image that is incorporated into the
4201 disk image.
4202 </para></listitem>
4203 <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
4204 Called before
4205 <filename>do_prepare_partition()</filename>.
4206 This method is typically used to create custom
4207 configuration files for a partition (e.g. syslinux or
4208 grub configuration files).
4209 </para></listitem>
4210 <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
4211 Called after all partitions have been prepared and
4212 assembled into a disk image.
4213 This method provides a hook to allow finalization of a
4214 disk image, (e.g. writing an MBR).
4215 </para></listitem>
4216 <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
4217 Special content-staging hook called before
4218 <filename>do_prepare_partition()</filename>.
4219 This method is normally empty.</para>
4220 <para>Typically, a partition just uses the passed-in
4221 parameters (e.g. the unmodified value of
4222 <filename>bootimg_dir</filename>).
4223 However, in some cases things might need to be
4224 more tailored.
4225 As an example, certain files might additionally
4226 need to be taken from
4227 <filename>bootimg_dir + /boot</filename>.
4228 This hook allows those files to be staged in a
4229 customized fashion.
4230 <note>
4231 <filename>get_bitbake_var()</filename>
4232 allows you to access non-standard variables
4233 that you might want to use for this.
4234 </note>
4235 </para></listitem>
4236 </itemizedlist>
4237 </para>
4238
4239 <para>
4240 This scheme is extensible.
4241 Adding more hooks is a simple matter of adding more
4242 plugin methods to <filename>SourcePlugin</filename> and
4243 derived classes.
4244 The code that then needs to call the plugin methods uses
4245 <filename>plugin.get_source_plugin_methods()</filename>
4246 to find the method or methods needed by the call.
4247 Retrieval of those methods is accomplished
4248 by filling up a dict with keys
4249 containing the method names of interest.
4250 On success, these will be filled in with the actual
4251 methods.
4252 Please see the <filename>wic</filename>
4253 implementation for examples and details.
4254 </para>
4255 </section>
4256
4257 <section id='openembedded-kickstart-wks-reference'>
4258 <title>OpenEmbedded Kickstart (.wks) Reference</title>
4259
4260 <para>
4261 The current <filename>wic</filename> implementation supports
4262 only the basic kickstart partitioning commands:
4263 <filename>partition</filename> (or <filename>part</filename>
4264 for short) and <filename>bootloader</filename>.
4265 <note>
4266 Future updates will implement more commands and options.
4267 If you use anything that is not specifically
4268 supported, results can be unpredictable.
4269 </note>
4270 </para>
4271
4272 <para>
4273 The following is a list of the commands, their syntax,
4274 and meanings.
4275 The commands are based on the Fedora
4276 kickstart versions but with modifications to
4277 reflect <filename>wic</filename> capabilities.
4278 You can see the original documentation for those commands
4279 at the following links:
4280 <itemizedlist>
4281 <listitem><para>
4282 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
4283 </para></listitem>
4284 <listitem><para>
4285 <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
4286 </para></listitem>
4287 </itemizedlist>
4288 </para>
4289
4290 <section id='command-part-or-partition'>
4291 <title>Command: part or partition</title>
4292
4293 <para>
4294 This command creates a partition on the system and uses the
4295 following syntax:
4296 <literallayout class='monospaced'>
4297 part <replaceable>mntpoint</replaceable>
4298 </literallayout>
4299 The <filename><replaceable>mntpoint</replaceable></filename>
4300 is where the
4301 partition will be mounted and must be of one of the
4302 following forms:
4303 <itemizedlist>
4304 <listitem><para><filename>/<replaceable>path</replaceable></filename>:
4305 For example, <filename>/</filename>,
4306 <filename>/usr</filename>, and
4307 <filename>/home</filename></para></listitem>
4308 <listitem><para><filename>swap</filename>:
4309 The partition will be used as swap space.
4310 </para></listitem>
4311 </itemizedlist>
4312 </para>
4313
4314 <para>
4315 Following are the supported options:
4316 <itemizedlist>
4317 <listitem><para><emphasis><filename>&dash;&dash;size</filename>:</emphasis>
4318 The minimum partition size in MBytes.
4319 Specify an integer value such as 500.
4320 Do not append the number with "MB".
4321 You do not need this option if you use
4322 <filename>&dash;&dash;source</filename>.</para></listitem>
4323 <listitem><para><emphasis><filename>&dash;&dash;source</filename>:</emphasis>
4324 This option is a
4325 <filename>wic</filename>-specific option that
4326 names the source of the data that populates
4327 the partition.
4328 The most common value for this option is
4329 "rootfs", but you can use any value that maps to
4330 a valid source plugin.
4331 For information on the source plugins, see the
4332 "<link linkend='openembedded-kickstart-plugins'>Plugins</link>"
4333 section.</para>
4334 <para>If you use
4335 <filename>&dash;&dash;source rootfs</filename>,
4336 <filename>wic</filename> creates a partition as
4337 large as needed and to fill it with the contents of
4338 the root filesystem pointed to by the
4339 <filename>-r</filename> command-line option
4340 or the equivalent rootfs derived from the
4341 <filename>-e</filename> command-line
4342 option.
4343 The filesystem type used to create the
4344 partition is driven by the value of the
4345 <filename>&dash;&dash;fstype</filename> option
4346 specified for the partition.
4347 See the entry on
4348 <filename>&dash;&dash;fstype</filename> that
4349 follows for more information.
4350 </para>
4351 <para>If you use
4352 <filename>&dash;&dash;source <replaceable>plugin-name</replaceable></filename>,
4353 <filename>wic</filename> creates a partition as
4354 large as needed and fills it with the contents of
4355 the partition that is generated by the
4356 specified plugin name using the data pointed
4357 to by the <filename>-r</filename> command-line
4358 option or the equivalent rootfs derived from the
4359 <filename>-e</filename> command-line
4360 option.
4361 Exactly what those contents and
4362 filesystem type end up being are dependent
4363 on the given plugin implementation.
4364 </para></listitem>
4365 <listitem><para><emphasis><filename>&dash;&dash;ondisk</filename> or <filename>&dash;&dash;ondrive</filename>:</emphasis>
4366 Forces the partition to be created on a particular
4367 disk.</para></listitem>
4368 <listitem><para><emphasis><filename>&dash;&dash;fstype</filename>:</emphasis>
4369 Sets the file system type for the partition.
4370 Valid values are:
4371 <itemizedlist>
4372 <listitem><para><filename>ext4</filename>
4373 </para></listitem>
4374 <listitem><para><filename>ext3</filename>
4375 </para></listitem>
4376 <listitem><para><filename>ext2</filename>
4377 </para></listitem>
4378 <listitem><para><filename>btrfs</filename>
4379 </para></listitem>
4380 <listitem><para><filename>squashfs</filename>
4381 </para></listitem>
4382 <listitem><para><filename>swap</filename>
4383 </para></listitem>
4384 </itemizedlist></para></listitem>
4385 <listitem><para><emphasis><filename>&dash;&dash;fsoptions</filename>:</emphasis>
4386 Specifies a free-form string of options to be
4387 used when mounting the filesystem.
4388 This string will be copied into the
4389 <filename>/etc/fstab</filename> file of the
4390 installed system and should be enclosed in
4391 quotes.
4392 If not specified, the default string
4393 is "defaults".
4394 </para></listitem>
4395 <listitem><para><emphasis><filename>&dash;&dash;label label</filename>:</emphasis>
4396 Specifies the label to give to the filesystem to
4397 be made on the partition.
4398 If the given label is already in use by another
4399 filesystem, a new label is created for the
4400 partition.</para></listitem>
4401 <listitem><para><emphasis><filename>&dash;&dash;active</filename>:</emphasis>
4402 Marks the partition as active.</para></listitem>
4403 <listitem><para><emphasis><filename>&dash;&dash;align (in KBytes)</filename>:</emphasis>
4404 This option is a <filename>wic</filename>-specific
4405 option that says to start a partition on an
4406 x KBytes boundary.</para></listitem>
4407 </itemizedlist>
4408 </para>
4409 </section>
4410
4411 <section id='command-bootloader'>
4412 <title>Command: bootloader</title>
4413
4414 <para>
4415 This command specifies how the boot loader should be
4416 configured and supports the following options:
4417 <note>
4418 Bootloader functionality and boot partitions are
4419 implemented by the various
4420 <filename>&dash;&dash;source</filename>
4421 plugins that implement bootloader functionality.
4422 The bootloader command essentially provides a means of
4423 modifying bootloader configuration.
4424 </note>
4425 <itemizedlist>
4426 <listitem><para><emphasis><filename>&dash;&dash;timeout</filename>:</emphasis>
4427 Specifies the number of seconds before the
4428 bootloader times out and boots the default option.
4429 </para></listitem>
4430 <listitem><para><emphasis><filename>&dash;&dash;append</filename>:</emphasis>
4431 Specifies kernel parameters.
4432 These parameters will be added to the syslinux
4433 <filename>APPEND</filename> or
4434 <filename>grub</filename> kernel command line.
4435 </para></listitem>
4436 </itemizedlist>
4437 </para>
4438 </section>
4439 </section>
4440 </section>
4441
4442 <section id='configuring-the-kernel'>
4443 <title>Configuring the Kernel</title>
4444
4445 <para>
4446 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
4447 file has all the right information in it for the image you are building.
4448 You can use the <filename>menuconfig</filename> tool and configuration fragments to
4449 make sure your <filename>.config</filename> file is just how you need it.
4450 This section describes how to use <filename>menuconfig</filename>, create and use
4451 configuration fragments, and how to interactively modify your <filename>.config</filename>
4452 file to create the leanest kernel configuration file possible.
4453 </para>
4454
4455 <para>
4456 For more information on kernel configuration, see the
4457 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
4458 section in the Yocto Project Linux Kernel Development Manual.
4459 </para>
4460
4461 <section id='using-menuconfig'>
4462 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
4463
4464 <para>
4465 The easiest way to define kernel configurations is to set them through the
4466 <filename>menuconfig</filename> tool.
4467 This tool provides an interactive method with which
4468 to set kernel configurations.
4469 For general information on <filename>menuconfig</filename>, see
4470 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
4471 </para>
4472
4473 <para>
4474 To use the <filename>menuconfig</filename> tool in the Yocto Project development
4475 environment, you must launch it using BitBake.
4476 Thus, the environment must be set up using the
4477 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
4478 or
4479 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
4480 script found in the
4481 <link linkend='build-directory'>Build Directory</link>.
4482 The following commands run <filename>menuconfig</filename> assuming the
4483 <link linkend='source-directory'>Source Directory</link>
4484 top-level folder is <filename>~/poky</filename>:
4485 <literallayout class='monospaced'>
4486 $ cd poky
4487 $ source oe-init-build-env
4488 $ bitbake linux-yocto -c menuconfig
4489 </literallayout>
4490 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
4491 interactively examine and configure all the kernel configuration parameters.
4492 After making your changes, simply exit the tool and save your changes to
4493 create an updated version of the <filename>.config</filename> configuration file.
4494 </para>
4495
4496 <para>
4497 Consider an example that configures the <filename>linux-yocto-3.14</filename>
4498 kernel.
4499 The OpenEmbedded build system recognizes this kernel as
4500 <filename>linux-yocto</filename>.
4501 Thus, the following commands from the shell in which you previously sourced the
4502 environment initialization script cleans the shared state cache and the
4503 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
4504 directory and then runs <filename>menuconfig</filename>:
4505 <literallayout class='monospaced'>
4506 $ bitbake linux-yocto -c menuconfig
4507 </literallayout>
4508 </para>
4509
4510 <para>
4511 Once <filename>menuconfig</filename> launches, use the interface
4512 to navigate through the selections to find the configuration settings in
4513 which you are interested.
4514 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
4515 You can find it at <filename>Processor Type and Features</filename> under
4516 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
4517 After highlighting the selection, use the arrow keys to select or deselect
4518 the setting.
4519 When you are finished with all your selections, exit out and save them.
4520 </para>
4521
4522 <para>
4523 Saving the selections updates the <filename>.config</filename> configuration file.
4524 This is the file that the OpenEmbedded build system uses to configure the
4525 kernel during the build.
4526 You can find and examine this file in the Build Directory in
4527 <filename>tmp/work/</filename>.
4528 The actual <filename>.config</filename> is located in the area where the
4529 specific kernel is built.
4530 For example, if you were building a Linux Yocto kernel based on the
4531 Linux 3.14 kernel and you were building a QEMU image targeted for
4532 <filename>x86</filename> architecture, the
4533 <filename>.config</filename> file would be located here:
4534 <literallayout class='monospaced'>
4535 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
4536 ...656ed30-r1/linux-qemux86-standard-build
4537 </literallayout>
4538 <note>
4539 The previous example directory is artificially split and many of the characters
4540 in the actual filename are omitted in order to make it more readable.
4541 Also, depending on the kernel you are using, the exact pathname
4542 for <filename>linux-yocto-3.14...</filename> might differ.
4543 </note>
4544 </para>
4545
4546 <para>
4547 Within the <filename>.config</filename> file, you can see the kernel settings.
4548 For example, the following entry shows that symmetric multi-processor support
4549 is not set:
4550 <literallayout class='monospaced'>
4551 # CONFIG_SMP is not set
4552 </literallayout>
4553 </para>
4554
4555 <para>
4556 A good method to isolate changed configurations is to use a combination of the
4557 <filename>menuconfig</filename> tool and simple shell commands.
4558 Before changing configurations with <filename>menuconfig</filename>, copy the
4559 existing <filename>.config</filename> and rename it to something else,
4560 use <filename>menuconfig</filename> to make
4561 as many changes as you want and save them, then compare the renamed configuration
4562 file against the newly created file.
4563 You can use the resulting differences as your base to create configuration fragments
4564 to permanently save in your kernel layer.
4565 <note>
4566 Be sure to make a copy of the <filename>.config</filename> and don't just
4567 rename it.
4568 The build system needs an existing <filename>.config</filename>
4569 from which to work.
4570 </note>
4571 </para>
4572 </section>
4573
4574 <section id='creating-config-fragments'>
4575 <title>Creating Configuration Fragments</title>
4576
4577 <para>
4578 Configuration fragments are simply kernel options that appear in a file
4579 placed where the OpenEmbedded build system can find and apply them.
4580 Syntactically, the configuration statement is identical to what would appear
4581 in the <filename>.config</filename> file, which is in the
4582 <link linkend='build-directory'>Build Directory</link> in
4583 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
4584 </para>
4585
4586 <para>
4587 It is simple to create a configuration fragment.
4588 For example, issuing the following from the shell creates a configuration fragment
4589 file named <filename>my_smp.cfg</filename> that enables multi-processor support
4590 within the kernel:
4591 <literallayout class='monospaced'>
4592 $ echo "CONFIG_SMP=y" >> my_smp.cfg
4593 </literallayout>
4594 <note>
4595 All configuration files must use the <filename>.cfg</filename> extension in order
4596 for the OpenEmbedded build system to recognize them as a configuration fragment.
4597 </note>
4598 </para>
4599
4600 <para>
4601 Where do you put your configuration files?
4602 You can place these configuration files in the same area pointed to by
4603 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
4604 The OpenEmbedded build system will pick up the configuration and add it to the
4605 kernel's configuration.
4606 For example, suppose you had a set of configuration options in a file called
4607 <filename>myconfig.cfg</filename>.
4608 If you put that file inside a directory named <filename>linux-yocto</filename>
4609 that resides in the same directory as the kernel's append file and then add
4610 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
4611 those configuration options will be picked up and applied when the kernel is built.
4612 <literallayout class='monospaced'>
4613 SRC_URI += "file://myconfig.cfg"
4614 </literallayout>
4615 </para>
4616
4617 <para>
4618 As mentioned earlier, you can group related configurations into multiple files and
4619 name them all in the <filename>SRC_URI</filename> statement as well.
4620 For example, you could group separate configurations specifically for Ethernet and graphics
4621 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
4622 following in your append file:
4623 <literallayout class='monospaced'>
4624 SRC_URI += "file://myconfig.cfg \
4625 file://eth.cfg \
4626 file://gfx.cfg"
4627 </literallayout>
4628 </para>
4629 </section>
4630
4631 <section id='fine-tuning-the-kernel-configuration-file'>
4632 <title>Fine-Tuning the Kernel Configuration File</title>
4633
4634 <para>
4635 You can make sure the <filename>.config</filename> file is as lean or efficient as
4636 possible by reading the output of the kernel configuration fragment audit,
4637 noting any issues, making changes to correct the issues, and then repeating.
4638 </para>
4639
4640 <para>
4641 As part of the kernel build process, the
4642 <filename>do_kernel_configcheck</filename> task runs.
4643 This task validates the kernel configuration by checking the final
4644 <filename>.config</filename> file against the input files.
4645 During the check, the task produces warning messages for the following
4646 issues:
4647 <itemizedlist>
4648 <listitem><para>Requested options that did not make the final
4649 <filename>.config</filename> file.</para></listitem>
4650 <listitem><para>Configuration items that appear twice in the same
4651 configuration fragment.</para></listitem>
4652 <listitem><para>Configuration items tagged as "required" that were overridden.
4653 </para></listitem>
4654 <listitem><para>A board overrides a non-board specific option.</para></listitem>
4655 <listitem><para>Listed options not valid for the kernel being processed.
4656 In other words, the option does not appear anywhere.</para></listitem>
4657 </itemizedlist>
4658 <note>
4659 The <filename>do_kernel_configcheck</filename> task can
4660 also optionally report if an option is overridden during
4661 processing.
4662 </note>
4663 </para>
4664
4665 <para>
4666 For each output warning, a message points to the file
4667 that contains a list of the options and a pointer to the config
4668 fragment that defines them.
4669 Collectively, the files are the key to streamlining the configuration.
4670 </para>
4671
4672 <para>
4673 To streamline the configuration, do the following:
4674 <orderedlist>
4675 <listitem><para>Start with a full configuration that you
4676 know works - it builds and boots successfully.
4677 This configuration file will be your baseline.
4678 </para></listitem>
4679 <listitem><para>Separately run the
4680 <filename>do_configme</filename> and
4681 <filename>do_kernel_configcheck</filename> tasks.
4682 </para></listitem>
4683 <listitem><para>Take the resulting list of files from the
4684 <filename>do_kernel_configcheck</filename> task
4685 warnings and do the following:
4686 <itemizedlist>
4687 <listitem><para>
4688 Drop values that are redefined in the fragment
4689 but do not change the final
4690 <filename>.config</filename> file.
4691 </para></listitem>
4692 <listitem><para>
4693 Analyze and potentially drop values from the
4694 <filename>.config</filename> file that override
4695 required configurations.
4696 </para></listitem>
4697 <listitem><para>
4698 Analyze and potentially remove non-board
4699 specific options.
4700 </para></listitem>
4701 <listitem><para>
4702 Remove repeated and invalid options.
4703 </para></listitem>
4704 </itemizedlist></para></listitem>
4705 <listitem><para>
4706 After you have worked through the output of the kernel
4707 configuration audit, you can re-run the
4708 <filename>do_configme</filename> and
4709 <filename>do_kernel_configcheck</filename> tasks to
4710 see the results of your changes.
4711 If you have more issues, you can deal with them as
4712 described in the previous step.
4713 </para></listitem>
4714 </orderedlist>
4715 </para>
4716
4717 <para>
4718 Iteratively working through steps two through four eventually yields
4719 a minimal, streamlined configuration file.
4720 Once you have the best <filename>.config</filename>, you can build the Linux
4721 Yocto kernel.
4722 </para>
4723 </section>
4724 </section>
4725
4726 <section id="patching-the-kernel">
4727 <title>Patching the Kernel</title>
4728
4729 <para>
4730 Patching the kernel involves changing or adding configurations to an existing kernel,
4731 changing or adding recipes to the kernel that are needed to support specific hardware features,
4732 or even altering the source code itself.
4733 <note>
4734 You can use the <filename>yocto-kernel</filename> script
4735 found in the <link linkend='source-directory'>Source Directory</link>
4736 under <filename>scripts</filename> to manage kernel patches and configuration.
4737 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
4738 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
4739 more information.</note>
4740 </para>
4741
4742 <para>
4743 This example creates a simple patch by adding some QEMU emulator console
4744 output at boot time through <filename>printk</filename> statements in the kernel's
4745 <filename>calibrate.c</filename> source code file.
4746 Applying the patch and booting the modified image causes the added
4747 messages to appear on the emulator's console.
4748 </para>
4749
4750 <para>
4751 The example assumes a clean build exists for the <filename>qemux86</filename>
4752 machine in a
4753 <link linkend='source-directory'>Source Directory</link>
4754 named <filename>poky</filename>.
4755 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
4756 <filename>build</filename> and is located in <filename>poky</filename> and
4757 the kernel is based on the Linux 3.4 kernel.
4758 For general information on how to configure the most efficient build, see the
4759 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
4760 in the Yocto Project Quick Start.
4761 </para>
4762
4763 <para>
4764 Also, for more information on patching the kernel, see the
4765 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
4766 section in the Yocto Project Linux Kernel Development Manual.
4767 </para>
4768
4769 <section id='create-a-layer-for-your-changes'>
4770 <title>Create a Layer for your Changes</title>
4771
4772 <para>
4773 The first step is to create a layer so you can isolate your
4774 changes.
4775 Rather than use the <filename>yocto-layer</filename> script
4776 to create the layer, this example steps through the process
4777 by hand.
4778 If you want information on the script that creates a general
4779 layer, see the
4780 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
4781 section.
4782 </para>
4783
4784 <para>
4785 These two commands create a directory you can use for your
4786 layer:
4787 <literallayout class='monospaced'>
4788 $ cd ~/poky
4789 $ mkdir meta-mylayer
4790 </literallayout>
4791 Creating a directory that follows the Yocto Project layer naming
4792 conventions sets up the layer for your changes.
4793 The layer is where you place your configuration files, append
4794 files, and patch files.
4795 To learn more about creating a layer and filling it with the
4796 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
4797 and Creating Layers</link>" section.
4798 </para>
4799 </section>
4800
4801 <section id='finding-the-kernel-source-code'>
4802 <title>Finding the Kernel Source Code</title>
4803
4804 <para>
4805 Each time you build a kernel image, the kernel source code is fetched
4806 and unpacked into the following directory:
4807 <literallayout class='monospaced'>
4808 ${S}/linux
4809 </literallayout>
4810 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
4811 section and the
4812 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
4813 for more information about where source is kept during a build.
4814 </para>
4815
4816 <para>
4817 For this example, we are going to patch the
4818 <filename>init/calibrate.c</filename> file
4819 by adding some simple console <filename>printk</filename> statements that we can
4820 see when we boot the image using QEMU.
4821 </para>
4822 </section>
4823
4824 <section id='creating-the-patch'>
4825 <title>Creating the Patch</title>
4826
4827 <para>
4828 Two methods exist by which you can create the patch:
4829 <link linkend='using-a-git-workflow'>Git workflow</link> and
4830 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
4831 For kernel patches, the Git workflow is more appropriate.
4832 This section assumes the Git workflow and shows the steps specific to
4833 this example.
4834 <orderedlist>
4835 <listitem><para><emphasis>Change the working directory</emphasis>:
4836 Change to where the kernel source code is before making
4837 your edits to the <filename>calibrate.c</filename> file:
4838 <literallayout class='monospaced'>
4839 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
4840 </literallayout>
4841 Because you are working in an established Git repository,
4842 you must be in this directory in order to commit your changes
4843 and create the patch file.
4844 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
4845 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
4846 represent the version and revision for the
4847 <filename>linux-yocto</filename> recipe.
4848 The <filename>PV</filename> variable includes the Git meta and machine
4849 hashes, which make the directory name longer than you might
4850 expect.
4851 </note></para></listitem>
4852 <listitem><para><emphasis>Edit the source file</emphasis>:
4853 Edit the <filename>init/calibrate.c</filename> file to have the
4854 following changes:
4855 <literallayout class='monospaced'>
4856 void calibrate_delay(void)
4857 {
4858 unsigned long lpj;
4859 static bool printed;
4860 int this_cpu = smp_processor_id();
4861
4862 printk("*************************************\n");
4863 printk("* *\n");
4864 printk("* HELLO YOCTO KERNEL *\n");
4865 printk("* *\n");
4866 printk("*************************************\n");
4867
4868 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
4869 .
4870 .
4871 .
4872 </literallayout></para></listitem>
4873 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
4874 These Git commands display the modified file, stage it, and then
4875 commit the file:
4876 <literallayout class='monospaced'>
4877 $ git status
4878 $ git add init/calibrate.c
4879 $ git commit -m "calibrate: Add printk example"
4880 </literallayout></para></listitem>
4881 <listitem><para><emphasis>Generate the patch file</emphasis>:
4882 This Git command creates the a patch file named
4883 <filename>0001-calibrate-Add-printk-example.patch</filename>
4884 in the current directory.
4885 <literallayout class='monospaced'>
4886 $ git format-patch -1
4887 </literallayout>
4888 </para></listitem>
4889 </orderedlist>
4890 </para>
4891 </section>
4892
4893 <section id='set-up-your-layer-for-the-build'>
4894 <title>Set Up Your Layer for the Build</title>
4895
4896 <para>These steps get your layer set up for the build:
4897 <orderedlist>
4898 <listitem><para><emphasis>Create additional structure</emphasis>:
4899 Create the additional layer structure:
4900 <literallayout class='monospaced'>
4901 $ cd ~/poky/meta-mylayer
4902 $ mkdir conf
4903 $ mkdir recipes-kernel
4904 $ mkdir recipes-kernel/linux
4905 $ mkdir recipes-kernel/linux/linux-yocto
4906 </literallayout>
4907 The <filename>conf</filename> directory holds your configuration files, while the
4908 <filename>recipes-kernel</filename> directory holds your append file and
4909 your patch file.</para></listitem>
4910 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
4911 Move to the <filename>meta-mylayer/conf</filename> directory and create
4912 the <filename>layer.conf</filename> file as follows:
4913 <literallayout class='monospaced'>
4914 # We have a conf and classes directory, add to BBPATH
4915 BBPATH .= ":${LAYERDIR}"
4916
4917 # We have recipes-* directories, add to BBFILES
4918 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
4919 ${LAYERDIR}/recipes-*/*/*.bbappend"
4920
4921 BBFILE_COLLECTIONS += "mylayer"
4922 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
4923 BBFILE_PRIORITY_mylayer = "5"
4924 </literallayout>
4925 Notice <filename>mylayer</filename> as part of the last three
4926 statements.</para></listitem>
4927 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
4928 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
4929 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
4930 <literallayout class='monospaced'>
4931 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4932
4933 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
4934 </literallayout>
4935 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
4936 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
4937 statements enable the OpenEmbedded build system to find the patch file.
4938 For more information on using append files, see the
4939 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
4940 section.
4941 </para></listitem>
4942 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
4943 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
4944 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
4945 directory.</para></listitem>
4946 </orderedlist>
4947 </para>
4948 </section>
4949
4950 <section id='set-up-for-the-build'>
4951 <title>Set Up for the Build</title>
4952
4953 <para>
4954 Do the following to make sure the build parameters are set up for the example.
4955 Once you set up these build parameters, they do not have to change unless you
4956 change the target architecture of the machine you are building:
4957 <itemizedlist>
4958 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
4959 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4960 definition within the <filename>local.conf</filename> file in the
4961 <link linkend='build-directory'>Build Directory</link>
4962 specifies the target architecture used when building the Linux kernel.
4963 By default, <filename>MACHINE</filename> is set to
4964 <filename>qemux86</filename>, which specifies a 32-bit
4965 <trademark class='registered'>Intel</trademark> Architecture
4966 target machine suitable for the QEMU emulator.</para></listitem>
4967 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
4968 layer:</emphasis> The
4969 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
4970 variable in the
4971 <filename>bblayers.conf</filename> file found in the
4972 <filename>poky/build/conf</filename> directory needs to have the path to your local
4973 <filename>meta-mylayer</filename> layer.
4974 By default, the <filename>BBLAYERS</filename> variable contains paths to
4975 <filename>meta</filename>, <filename>meta-yocto</filename>, and
4976 <filename>meta-yocto-bsp</filename> in the
4977 <filename>poky</filename> Git repository.
4978 Add the path to your <filename>meta-mylayer</filename> location:
4979 <literallayout class='monospaced'>
4980 BBLAYERS ?= " \
4981 $HOME/poky/meta \
4982 $HOME/poky/meta-yocto \
4983 $HOME/poky/meta-yocto-bsp \
4984 $HOME/poky/meta-mylayer \
4985 "
4986
4987 BBLAYERS_NON_REMOVABLE ?= " \
4988 $HOME/poky/meta \
4989 $HOME/poky/meta-yocto \
4990 "
4991 </literallayout></para></listitem>
4992 </itemizedlist>
4993 </para>
4994 </section>
4995
4996 <section id='build-the-modified-qemu-kernel-image'>
4997 <title>Build the Modified QEMU Kernel Image</title>
4998
4999 <para>
5000 The following steps build your modified kernel image:
5001 <orderedlist>
5002 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
5003 Your environment should be set up since you previously sourced
5004 the
5005 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
5006 script.
5007 If it is not, source the script again from <filename>poky</filename>.
5008 <literallayout class='monospaced'>
5009 $ cd ~/poky
5010 $ source &OE_INIT_FILE;
5011 </literallayout>
5012 </para></listitem>
5013 <listitem><para><emphasis>Clean up</emphasis>:
5014 Be sure to clean the shared state out by using BitBake
5015 to run from within the Build Directory the
5016 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>
5017 task as follows:
5018 <literallayout class='monospaced'>
5019 $ bitbake -c cleansstate linux-yocto
5020 </literallayout></para>
5021 <para>
5022 <note>
5023 Never remove any files by hand from the
5024 <filename>tmp/deploy</filename>
5025 directory inside the
5026 <link linkend='build-directory'>Build Directory</link>.
5027 Always use the various BitBake clean tasks to
5028 clear out previous build artifacts.
5029 For information on the clean tasks, see the
5030 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>",
5031 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>",
5032 and
5033 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>"
5034 sections all in the Yocto Project Reference
5035 Manual.
5036 </note>
5037 </para></listitem>
5038 <listitem><para><emphasis>Build the image</emphasis>:
5039 Next, build the kernel image using this command:
5040 <literallayout class='monospaced'>
5041 $ bitbake -k linux-yocto
5042 </literallayout></para></listitem>
5043 </orderedlist>
5044 </para>
5045 </section>
5046
5047 <section id='boot-the-image-and-verify-your-changes'>
5048 <title>Boot the Image and Verify Your Changes</title>
5049
5050 <para>
5051 These steps boot the image and allow you to see the changes
5052 <orderedlist>
5053 <listitem><para><emphasis>Boot the image</emphasis>:
5054 Boot the modified image in the QEMU emulator
5055 using this command:
5056 <literallayout class='monospaced'>
5057 $ runqemu qemux86
5058 </literallayout></para></listitem>
5059 <listitem><para><emphasis>Verify the changes</emphasis>:
5060 Log into the machine using <filename>root</filename> with no password and then
5061 use the following shell command to scroll through the console's boot output.
5062 <literallayout class='monospaced'>
5063 # dmesg | less
5064 </literallayout>
5065 You should see the results of your <filename>printk</filename> statements
5066 as part of the output.</para></listitem>
5067 </orderedlist>
5068 </para>
5069 </section>
5070 </section>
5071
5072 <section id='making-images-more-secure'>
5073 <title>Making Images More Secure</title>
5074
5075 <para>
5076 Security is of increasing concern for embedded devices.
5077 Consider the issues and problems discussed in just this
5078 sampling of work found across the Internet:
5079 <itemizedlist>
5080 <listitem><para><emphasis>
5081 "<ulink url='https://www.schneier.com/blog/archives/2014/01/security_risks_9.html'>Security Risks of Embedded Systems</ulink>"</emphasis>
5082 by Bruce Schneier
5083 </para></listitem>
5084 <listitem><para><emphasis>
5085 "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
5086 by Carna Botnet</para></listitem>
5087 <listitem><para><emphasis>
5088 "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
5089 by Jake Edge
5090 </para></listitem>
5091 <listitem><para><emphasis>
5092 "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security
5093Gateways via their Web Interfaces</ulink>"</emphasis>
5094 by Ben Williams
5095 </para></listitem>
5096 </itemizedlist>
5097 </para>
5098
5099 <para>
5100 When securing your image is of concern, there are steps, tools,
5101 and variables that you can consider to help you reach the
5102 security goals you need for your particular device.
5103 Not all situations are identical when it comes to making an
5104 image secure.
5105 Consequently, this section provides some guidance and suggestions
5106 for consideration when you want to make your image more secure.
5107 <note>
5108 Because the security requirements and risks are
5109 different for every type of device, this section cannot
5110 provide a complete reference on securing your custom OS.
5111 It is strongly recommended that you also consult other sources
5112 of information on embedded Linux system hardening and on
5113 security.
5114 </note>
5115 </para>
5116
5117 <section id='general-considerations'>
5118 <title>General Considerations</title>
5119
5120 <para>
5121 General considerations exist that help you create more
5122 secure images.
5123 You should consider the following suggestions to help
5124 make your device more secure:
5125 <itemizedlist>
5126 <listitem><para>
5127 Scan additional code you are adding to the system
5128 (e.g. application code) by using static analysis
5129 tools.
5130 Look for buffer overflows and other potential
5131 security problems.
5132 </para></listitem>
5133 <listitem><para>
5134 Pay particular attention to the security for
5135 any web-based administration interface.
5136 </para>
5137 <para>Web interfaces typically need to perform
5138 administrative functions and tend to need to run with
5139 elevated privileges.
5140 Thus, the consequences resulting from the interface's
5141 security becoming compromised can be serious.
5142 Look for common web vulnerabilities such as
5143 cross-site-scripting (XSS), unvalidated inputs,
5144 and so forth.</para>
5145 <para>As with system passwords, the default credentials
5146 for accessing a web-based interface should not be the
5147 same across all devices.
5148 This is particularly true if the interface is enabled
5149 by default as it can be assumed that many end-users
5150 will not change the credentials.
5151 </para></listitem>
5152 <listitem><para>
5153 Ensure you can update the software on the device to
5154 mitigate vulnerabilities discovered in the future.
5155 This consideration especially applies when your
5156 device is network-enabled.
5157 </para></listitem>
5158 <listitem><para>
5159 Ensure you remove or disable debugging functionality
5160 before producing the final image.
5161 For information on how to do this, see the
5162 "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>"
5163 section.
5164 </para></listitem>
5165 <listitem><para>
5166 Ensure you have no network services listening that
5167 are not needed.
5168 </para></listitem>
5169 <listitem><para>
5170 Remove any software from the image that is not needed.
5171 </para></listitem>
5172 <listitem><para>
5173 Enable hardware support for secure boot functionality
5174 when your device supports this functionality.
5175 </para></listitem>
5176 </itemizedlist>
5177 </para>
5178 </section>
5179
5180 <section id='security-flags'>
5181 <title>Security Flags</title>
5182
5183 <para>
5184 The Yocto Project has security flags that you can enable that
5185 help make your build output more secure.
5186 The security flags are in the
5187 <filename>meta/conf/distro/include/security_flags.inc</filename>
5188 file in your
5189 <link linkend='source-directory'>Source Directory</link>
5190 (e.g. <filename>poky</filename>).
5191 <note>
5192 Depending on the recipe, certain security flags are enabled
5193 and disabled by default.
5194 </note>
5195 </para>
5196
5197 <para>
5198<!--
5199 The GCC/LD flags in <filename>security_flags.inc</filename>
5200 enable more secure code generation.
5201 By including the <filename>security_flags.inc</filename>
5202 file, you enable flags to the compiler and linker that cause
5203 them to generate more secure code.
5204 <note>
5205 The GCC/LD flags are enabled by default in the
5206 <filename>poky-lsb</filename> distribution.
5207 </note>
5208-->
5209 Use the following line in your
5210 <filename>local.conf</filename> file or in your custom
5211 distribution configuration file to enable the security
5212 compiler and linker flags for your build:
5213 <literallayout class='monospaced'>
5214 require conf/distro/include/security_flags.inc
5215 </literallayout>
5216 </para>
5217 </section>
5218
5219 <section id='considerations-specific-to-the-openembedded-build-system'>
5220 <title>Considerations Specific to the OpenEmbedded Build System</title>
5221
5222 <para>
5223 You can take some steps that are specific to the
5224 OpenEmbedded build system to make your images more secure:
5225 <itemizedlist>
5226 <listitem><para>
5227 Ensure "debug-tweaks" is not one of your selected
5228 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>.
5229 When creating a new project, the default is to provide you
5230 with an initial <filename>local.conf</filename> file that
5231 enables this feature using the
5232 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> variable with the line:
5233 <literallayout class='monospaced'>
5234 EXTRA_IMAGE_FEATURES = "debug-tweaks"
5235 </literallayout>
5236 To disable that feature, simply comment out that line in your
5237 <filename>local.conf</filename> file, or
5238 make sure <filename>IMAGE_FEATURES</filename> does not contain
5239 "debug-tweaks" before producing your final image.
5240 Among other things, leaving this in place sets the
5241 root password as blank, which makes logging in for
5242 debugging or inspection easy during
5243 development but also means anyone can easily log in
5244 during production.
5245 </para></listitem>
5246 <listitem><para>
5247 It is possible to set a root password for the image
5248 and also to set passwords for any extra users you might
5249 add (e.g. administrative or service type users).
5250 When you set up passwords for multiple images or
5251 users, you should not duplicate passwords.
5252 </para>
5253 <para>
5254 To set up passwords, use the
5255 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers</filename></ulink>
5256 class, which is the preferred method.
5257 For an example on how to set up both root and user
5258 passwords, see the
5259 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>"
5260 section.
5261 <note>
5262 When adding extra user accounts or setting a
5263 root password, be cautious about setting the
5264 same password on every device.
5265 If you do this, and the password you have set
5266 is exposed, then every device is now potentially
5267 compromised.
5268 If you need this access but want to ensure
5269 security, consider setting a different,
5270 random password for each device.
5271 Typically, you do this as a separate step after
5272 you deploy the image onto the device.
5273 </note>
5274 </para></listitem>
5275 <listitem><para>
5276 Consider enabling a Mandatory Access Control (MAC)
5277 framework such as SMACK or SELinux and tuning it
5278 appropriately for your device's usage.
5279 You can find more information in the
5280 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/'><filename>meta-selinux</filename></ulink>
5281 layer.
5282 </para></listitem>
5283 </itemizedlist>
5284 </para>
5285
5286 <para>
5287 </para>
5288 </section>
5289
5290 <section id='tools-for-hardening-your-image'>
5291 <title>Tools for Hardening Your Image</title>
5292
5293 <para>
5294 The Yocto Project provides tools for making your image
5295 more secure.
5296 You can find these tools in the
5297 <filename>meta-security</filename> layer of the
5298 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
5299 </para>
5300 </section>
5301 </section>
5302
5303 <section id='creating-your-own-distribution'>
5304 <title>Creating Your Own Distribution</title>
5305
5306 <para>
5307 When you build an image using the Yocto Project and
5308 do not alter any distribution
5309 <link linkend='metadata'>Metadata</link>, you are creating a
5310 Poky distribution.
5311 If you wish to gain more control over package alternative
5312 selections, compile-time options, and other low-level
5313 configurations, you can create your own distribution.
5314 </para>
5315
5316 <para>
5317 To create your own distribution, the basic steps consist of
5318 creating your own distribution layer, creating your own
5319 distribution configuration file, and then adding any needed
5320 code and Metadata to the layer.
5321 The following steps provide some more detail:
5322 <itemizedlist>
5323 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
5324 Create your distribution layer so that you can keep your
5325 Metadata and code for the distribution separate.
5326 It is strongly recommended that you create and use your own
5327 layer for configuration and code.
5328 Using your own layer as compared to just placing
5329 configurations in a <filename>local.conf</filename>
5330 configuration file makes it easier to reproduce the same
5331 build configuration when using multiple build machines.
5332 See the
5333 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
5334 section for information on how to quickly set up a layer.
5335 </para></listitem>
5336 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
5337 The distribution configuration file needs to be created in
5338 the <filename>conf/distro</filename> directory of your
5339 layer.
5340 You need to name it using your distribution name
5341 (e.g. <filename>mydistro.conf</filename>).
5342 <note>
5343 The
5344 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5345 variable in your
5346 <filename>local.conf</filename> file determines the
5347 name of your distribution.
5348 </note></para>
5349 <para>You can split out parts of your configuration file
5350 into include files and then "require" them from within
5351 your distribution configuration file.
5352 Be sure to place the include files in the
5353 <filename>conf/distro/include</filename> directory of
5354 your layer.
5355 A common example usage of include files would be to
5356 separate out the selection of desired version and revisions
5357 for individual recipes.
5358</para>
5359 <para>Your configuration file needs to set the following
5360 required variables:
5361 <literallayout class='monospaced'>
5362 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
5363 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
5364 </literallayout>
5365 These following variables are optional and you typically
5366 set them from the distribution configuration file:
5367 <literallayout class='monospaced'>
5368 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5369 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
5370 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
5371 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
5372 </literallayout>
5373 <tip>
5374 If you want to base your distribution configuration file
5375 on the very basic configuration from OE-Core, you
5376 can use
5377 <filename>conf/distro/defaultsetup.conf</filename> as
5378 a reference and just include variables that differ
5379 as compared to <filename>defaultsetup.conf</filename>.
5380 Alternatively, you can create a distribution
5381 configuration file from scratch using the
5382 <filename>defaultsetup.conf</filename> file
5383 or configuration files from other distributions
5384 such as Poky or Angstrom as references.
5385 </tip></para></listitem>
5386 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
5387 Be sure to define any other variables for which you want to
5388 create a default or enforce as part of the distribution
5389 configuration.
5390 You can include nearly any variable from the
5391 <filename>local.conf</filename> file.
5392 The variables you use are not limited to the list in the
5393 previous bulleted item.</para></listitem>
5394 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
5395 In your <filename>local.conf</filename> file in the
5396 <link linkend='build-directory'>Build Directory</link>,
5397 set your
5398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5399 variable to point to your distribution's configuration file.
5400 For example, if your distribution's configuration file is
5401 named <filename>mydistro.conf</filename>, then you point
5402 to it as follows:
5403 <literallayout class='monospaced'>
5404 DISTRO = "mydistro"
5405 </literallayout></para></listitem>
5406 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
5407 Use your layer to hold other information needed for the
5408 distribution:
5409 <itemizedlist>
5410 <listitem><para>Add recipes for installing
5411 distro-specific configuration files that are not
5412 already installed by another recipe.
5413 If you have distro-specific configuration files
5414 that are included by an existing recipe, you should
5415 add an append file (<filename>.bbappend</filename>)
5416 for those.
5417 For general information and recommendations
5418 on how to add recipes to your layer, see the
5419 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
5420 and
5421 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
5422 sections.</para></listitem>
5423 <listitem><para>Add any image recipes that are specific
5424 to your distribution.</para></listitem>
5425 <listitem><para>Add a <filename>psplash</filename>
5426 append file for a branded splash screen.
5427 For information on append files, see the
5428 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
5429 section.</para></listitem>
5430 <listitem><para>Add any other append files to make
5431 custom changes that are specific to individual
5432 recipes.</para></listitem>
5433 </itemizedlist></para></listitem>
5434 </itemizedlist>
5435 </para>
5436 </section>
5437
5438 <section id='creating-a-custom-template-configuration-directory'>
5439 <title>Creating a Custom Template Configuration Directory</title>
5440
5441 <para>
5442 If you are producing your own customized version
5443 of the build system for use by other users, you might
5444 want to customize the message shown by the setup script or
5445 you might want to change the template configuration files (i.e.
5446 <filename>local.conf</filename> and
5447 <filename>bblayers.conf</filename>) that are created in
5448 a new build directory.
5449 </para>
5450
5451 <para>
5452 The OpenEmbedded build system uses the environment variable
5453 <filename>TEMPLATECONF</filename> to locate the directory
5454 from which it gathers configuration information that ultimately
5455 ends up in the
5456 <link linkend='build-directory'>Build Directory's</link>
5457 <filename>conf</filename> directory.
5458 By default, <filename>TEMPLATECONF</filename> is set as
5459 follows in the <filename>poky</filename> repository:
5460 <literallayout class='monospaced'>
5461 TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf}
5462 </literallayout>
5463 This is the directory used by the build system to find templates
5464 from which to build some key configuration files.
5465 If you look at this directory, you will see the
5466 <filename>bblayers.conf.sample</filename>,
5467 <filename>local.conf.sample</filename>, and
5468 <filename>conf-notes.txt</filename> files.
5469 The build system uses these files to form the respective
5470 <filename>bblayers.conf</filename> file,
5471 <filename>local.conf</filename> file, and display the list of
5472 BitBake targets when running the setup script.
5473 </para>
5474
5475 <para>
5476 To override these default configuration files with
5477 configurations you want used within every new
5478 Build Directory, simply set the
5479 <filename>TEMPLATECONF</filename> variable to your directory.
5480 The <filename>TEMPLATECONF</filename> variable is set in the
5481 <filename>.templateconf</filename> file, which is in the
5482 top-level
5483 <link linkend='source-directory'>Source Directory</link>
5484 folder (e.g. <filename>poky</filename>).
5485 Edit the <filename>.templateconf</filename> so that it can locate
5486 your directory.
5487 </para>
5488
5489 <para>
5490 Best practices dictate that you should keep your
5491 template configuration directory in your custom distribution layer.
5492 For example, suppose you have a layer named
5493 <filename>meta-mylayer</filename> located in your home directory
5494 and you want your template configuration directory named
5495 <filename>myconf</filename>.
5496 Changing the <filename>.templateconf</filename> as follows
5497 causes the OpenEmbedded build system to look in your directory
5498 and base its configuration files on the
5499 <filename>*.sample</filename> configuration files it finds.
5500 The final configuration files (i.e.
5501 <filename>local.conf</filename> and
5502 <filename>bblayers.conf</filename> ultimately still end up in
5503 your Build Directory, but they are based on your
5504 <filename>*.sample</filename> files.
5505 <literallayout class='monospaced'>
5506 TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf}
5507 </literallayout>
5508 </para>
5509
5510 <para>
5511 Aside from the <filename>*.sample</filename> configuration files,
5512 the <filename>conf-notes.txt</filename> also resides in the
5513 default <filename>meta-yocto/conf</filename> directory.
5514 The scripts that set up the build environment
5515 (i.e.
5516 <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
5517 and
5518 <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>)
5519 use this file to display BitBake targets as part of the script
5520 output.
5521 Customizing this <filename>conf-notes.txt</filename> file is a
5522 good way to make sure your list of custom targets appears
5523 as part of the script's output.
5524 </para>
5525
5526 <para>
5527 Here is the default list of targets displayed as a result of
5528 running either of the setup scripts:
5529 <literallayout class='monospaced'>
5530 You can now run 'bitbake &lt;target&gt;'
5531
5532 Common targets are:
5533 core-image-minimal
5534 core-image-sato
5535 meta-toolchain
5536 adt-installer
5537 meta-ide-support
5538 </literallayout>
5539 </para>
5540
5541 <para>
5542 Changing the listed common targets is as easy as editing your
5543 version of <filename>conf-notes.txt</filename> in your
5544 custom template configuration directory and making sure you
5545 have <filename>TEMPLATECONF</filename> set to your directory.
5546 </para>
5547 </section>
5548
5549 <section id='building-a-tiny-system'>
5550 <title>Building a Tiny System</title>
5551
5552 <para>
5553 Very small distributions have some significant advantages such
5554 as requiring less on-die or in-package memory (cheaper), better
5555 performance through efficient cache usage, lower power requirements
5556 due to less memory, faster boot times, and reduced development
5557 overhead.
5558 Some real-world examples where a very small distribution gives
5559 you distinct advantages are digital cameras, medical devices,
5560 and small headless systems.
5561 </para>
5562
5563 <para>
5564 This section presents information that shows you how you can
5565 trim your distribution to even smaller sizes than the
5566 <filename>poky-tiny</filename> distribution, which is around
5567 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
5568 </para>
5569
5570 <section id='tiny-system-overview'>
5571 <title>Overview</title>
5572
5573 <para>
5574 The following list presents the overall steps you need to
5575 consider and perform to create distributions with smaller
5576 root filesystems, achieve faster boot times, maintain your critical
5577 functionality, and avoid initial RAM disks:
5578 <itemizedlist>
5579 <listitem><para>
5580 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
5581 </para></listitem>
5582 <listitem><para>
5583 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
5584 </para></listitem>
5585 <listitem><para>
5586 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
5587 </para></listitem>
5588 <listitem><para>
5589 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
5590 </para></listitem>
5591 <listitem><para>
5592 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
5593 </para></listitem>
5594 <listitem><para>
5595 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
5596 </para></listitem>
5597 <listitem><para>
5598 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
5599 </para></listitem>
5600 </itemizedlist>
5601 </para>
5602 </section>
5603
5604 <section id='goals-and-guiding-principles'>
5605 <title>Goals and Guiding Principles</title>
5606
5607 <para>
5608 Before you can reach your destination, you need to know
5609 where you are going.
5610 Here is an example list that you can use as a guide when
5611 creating very small distributions:
5612 <itemizedlist>
5613 <listitem><para>Determine how much space you need
5614 (e.g. a kernel that is 1 Mbyte or less and
5615 a root filesystem that is 3 Mbytes or less).
5616 </para></listitem>
5617 <listitem><para>Find the areas that are currently
5618 taking 90% of the space and concentrate on reducing
5619 those areas.
5620 </para></listitem>
5621 <listitem><para>Do not create any difficult "hacks"
5622 to achieve your goals.</para></listitem>
5623 <listitem><para>Leverage the device-specific
5624 options.</para></listitem>
5625 <listitem><para>Work in a separate layer so that you
5626 keep changes isolated.
5627 For information on how to create layers, see
5628 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
5629 </para></listitem>
5630 </itemizedlist>
5631 </para>
5632 </section>
5633
5634 <section id='understand-what-gives-your-image-size'>
5635 <title>Understand What Contributes to Your Image Size</title>
5636
5637 <para>
5638 It is easiest to have something to start with when creating
5639 your own distribution.
5640 You can use the Yocto Project out-of-the-box to create the
5641 <filename>poky-tiny</filename> distribution.
5642 Ultimately, you will want to make changes in your own
5643 distribution that are likely modeled after
5644 <filename>poky-tiny</filename>.
5645 <note>
5646 To use <filename>poky-tiny</filename> in your build,
5647 set the
5648 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5649 variable in your
5650 <filename>local.conf</filename> file to "poky-tiny"
5651 as described in the
5652 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
5653 section.
5654 </note>
5655 </para>
5656
5657 <para>
5658 Understanding some memory concepts will help you reduce the
5659 system size.
5660 Memory consists of static, dynamic, and temporary memory.
5661 Static memory is the TEXT (code), DATA (initialized data
5662 in the code), and BSS (uninitialized data) sections.
5663 Dynamic memory represents memory that is allocated at runtime:
5664 stacks, hash tables, and so forth.
5665 Temporary memory is recovered after the boot process.
5666 This memory consists of memory used for decompressing
5667 the kernel and for the <filename>__init__</filename>
5668 functions.
5669 </para>
5670
5671 <para>
5672 To help you see where you currently are with kernel and root
5673 filesystem sizes, you can use two tools found in the
5674 <link linkend='source-directory'>Source Directory</link> in
5675 the <filename>scripts/tiny/</filename> directory:
5676 <itemizedlist>
5677 <listitem><para><filename>ksize.py</filename>: Reports
5678 component sizes for the kernel build objects.
5679 </para></listitem>
5680 <listitem><para><filename>dirsize.py</filename>: Reports
5681 component sizes for the root filesystem.</para></listitem>
5682 </itemizedlist>
5683 This next tool and command help you organize configuration
5684 fragments and view file dependencies in a human-readable form:
5685 <itemizedlist>
5686 <listitem><para><filename>merge_config.sh</filename>:
5687 Helps you manage configuration files and fragments
5688 within the kernel.
5689 With this tool, you can merge individual configuration
5690 fragments together.
5691 The tool allows you to make overrides and warns you
5692 of any missing configuration options.
5693 The tool is ideal for allowing you to iterate on
5694 configurations, create minimal configurations, and
5695 create configuration files for different machines
5696 without having to duplicate your process.</para>
5697 <para>The <filename>merge_config.sh</filename> script is
5698 part of the Linux Yocto kernel Git repositories
5699 (i.e. <filename>linux-yocto-3.14</filename>,
5700 <filename>linux-yocto-3.10</filename>,
5701 <filename>linux-yocto-3.8</filename>, and so forth)
5702 in the
5703 <filename>scripts/kconfig</filename> directory.</para>
5704 <para>For more information on configuration fragments,
5705 see the
5706 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
5707 section of the Yocto Project Linux Kernel Development
5708 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
5709 section, which is in this manual.</para></listitem>
5710 <listitem><para><filename>bitbake -u depexp -g <replaceable>bitbake_target</replaceable></filename>:
5711 Using the BitBake command with these options brings up
5712 a Dependency Explorer from which you can view file
5713 dependencies.
5714 Understanding these dependencies allows you to make
5715 informed decisions when cutting out various pieces of the
5716 kernel and root filesystem.</para></listitem>
5717 </itemizedlist>
5718 </para>
5719 </section>
5720
5721 <section id='trim-the-root-filesystem'>
5722 <title>Trim the Root Filesystem</title>
5723
5724 <para>
5725 The root filesystem is made up of packages for booting,
5726 libraries, and applications.
5727 To change things, you can configure how the packaging happens,
5728 which changes the way you build them.
5729 You can also modify the filesystem itself or select a different
5730 filesystem.
5731 </para>
5732
5733 <para>
5734 First, find out what is hogging your root filesystem by running the
5735 <filename>dirsize.py</filename> script from your root directory:
5736 <literallayout class='monospaced'>
5737 $ cd <replaceable>root-directory-of-image</replaceable>
5738 $ dirsize.py 100000 > dirsize-100k.log
5739 $ cat dirsize-100k.log
5740 </literallayout>
5741 You can apply a filter to the script to ignore files under
5742 a certain size.
5743 The previous example filters out any files below 100 Kbytes.
5744 The sizes reported by the tool are uncompressed, and thus
5745 will be smaller by a relatively constant factor in a
5746 compressed root filesystem.
5747 When you examine your log file, you can focus on areas of the
5748 root filesystem that take up large amounts of memory.
5749 </para>
5750
5751 <para>
5752 You need to be sure that what you eliminate does not cripple
5753 the functionality you need.
5754 One way to see how packages relate to each other is by using
5755 the Dependency Explorer UI with the BitBake command:
5756 <literallayout class='monospaced'>
5757 $ cd <replaceable>image-directory</replaceable>
5758 $ bitbake -u depexp -g <replaceable>image</replaceable>
5759 </literallayout>
5760 Use the interface to select potential packages you wish to
5761 eliminate and see their dependency relationships.
5762 </para>
5763
5764 <para>
5765 When deciding how to reduce the size, get rid of packages that
5766 result in minimal impact on the feature set.
5767 For example, you might not need a VGA display.
5768 Or, you might be able to get by with <filename>devtmpfs</filename>
5769 and <filename>mdev</filename> instead of
5770 <filename>udev</filename>.
5771 </para>
5772
5773 <para>
5774 Use your <filename>local.conf</filename> file to make changes.
5775 For example, to eliminate <filename>udev</filename> and
5776 <filename>glib</filename>, set the following in the
5777 local configuration file:
5778 <literallayout class='monospaced'>
5779 VIRTUAL-RUNTIME_dev_manager = ""
5780 </literallayout>
5781 </para>
5782
5783 <para>
5784 Finally, you should consider exactly the type of root
5785 filesystem you need to meet your needs while also reducing
5786 its size.
5787 For example, consider <filename>cramfs</filename>,
5788 <filename>squashfs</filename>, <filename>ubifs</filename>,
5789 <filename>ext2</filename>, or an <filename>initramfs</filename>
5790 using <filename>initramfs</filename>.
5791 Be aware that <filename>ext3</filename> requires a 1 Mbyte
5792 journal.
5793 If you are okay with running read-only, you do not need this
5794 journal.
5795 </para>
5796
5797 <note>
5798 After each round of elimination, you need to rebuild your
5799 system and then use the tools to see the effects of your
5800 reductions.
5801 </note>
5802
5803
5804 </section>
5805
5806 <section id='trim-the-kernel'>
5807 <title>Trim the Kernel</title>
5808
5809 <para>
5810 The kernel is built by including policies for hardware-independent
5811 aspects.
5812 What subsystems do you enable?
5813 For what architecture are you building?
5814 Which drivers do you build by default?
5815 <note>You can modify the kernel source if you want to help
5816 with boot time.
5817 </note>
5818 </para>
5819
5820 <para>
5821 Run the <filename>ksize.py</filename> script from the top-level
5822 Linux build directory to get an idea of what is making up
5823 the kernel:
5824 <literallayout class='monospaced'>
5825 $ cd <replaceable>top-level-linux-build-directory</replaceable>
5826 $ ksize.py > ksize.log
5827 $ cat ksize.log
5828 </literallayout>
5829 When you examine the log, you will see how much space is
5830 taken up with the built-in <filename>.o</filename> files for
5831 drivers, networking, core kernel files, filesystem, sound,
5832 and so forth.
5833 The sizes reported by the tool are uncompressed, and thus
5834 will be smaller by a relatively constant factor in a compressed
5835 kernel image.
5836 Look to reduce the areas that are large and taking up around
5837 the "90% rule."
5838 </para>
5839
5840 <para>
5841 To examine, or drill down, into any particular area, use the
5842 <filename>-d</filename> option with the script:
5843 <literallayout class='monospaced'>
5844 $ ksize.py -d > ksize.log
5845 </literallayout>
5846 Using this option breaks out the individual file information
5847 for each area of the kernel (e.g. drivers, networking, and
5848 so forth).
5849 </para>
5850
5851 <para>
5852 Use your log file to see what you can eliminate from the kernel
5853 based on features you can let go.
5854 For example, if you are not going to need sound, you do not
5855 need any drivers that support sound.
5856 </para>
5857
5858 <para>
5859 After figuring out what to eliminate, you need to reconfigure
5860 the kernel to reflect those changes during the next build.
5861 You could run <filename>menuconfig</filename> and make all your
5862 changes at once.
5863 However, that makes it difficult to see the effects of your
5864 individual eliminations and also makes it difficult to replicate
5865 the changes for perhaps another target device.
5866 A better method is to start with no configurations using
5867 <filename>allnoconfig</filename>, create configuration
5868 fragments for individual changes, and then manage the
5869 fragments into a single configuration file using
5870 <filename>merge_config.sh</filename>.
5871 The tool makes it easy for you to iterate using the
5872 configuration change and build cycle.
5873 </para>
5874
5875 <para>
5876 Each time you make configuration changes, you need to rebuild
5877 the kernel and check to see what impact your changes had on
5878 the overall size.
5879 </para>
5880 </section>
5881
5882 <section id='remove-package-management-requirements'>
5883 <title>Remove Package Management Requirements</title>
5884
5885 <para>
5886 Packaging requirements add size to the image.
5887 One way to reduce the size of the image is to remove all the
5888 packaging requirements from the image.
5889 This reduction includes both removing the package manager
5890 and its unique dependencies as well as removing the package
5891 management data itself.
5892 </para>
5893
5894 <para>
5895 To eliminate all the packaging requirements for an image,
5896 be sure that "package-management" is not part of your
5897 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5898 statement for the image.
5899 When you remove this feature, you are removing the package
5900 manager as well as its dependencies from the root filesystem.
5901 </para>
5902 </section>
5903
5904 <section id='look-for-other-ways-to-minimize-size'>
5905 <title>Look for Other Ways to Minimize Size</title>
5906
5907 <para>
5908 Depending on your particular circumstances, other areas that you
5909 can trim likely exist.
5910 The key to finding these areas is through tools and methods
5911 described here combined with experimentation and iteration.
5912 Here are a couple of areas to experiment with:
5913 <itemizedlist>
5914 <listitem><para><filename>glibc</filename>:
5915 In general, follow this process:
5916 <orderedlist>
5917 <listitem><para>Remove <filename>glibc</filename>
5918 features from
5919 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5920 that you think you do not need.</para></listitem>
5921 <listitem><para>Build your distribution.
5922 </para></listitem>
5923 <listitem><para>If the build fails due to missing
5924 symbols in a package, determine if you can
5925 reconfigure the package to not need those
5926 features.
5927 For example, change the configuration to not
5928 support wide character support as is done for
5929 <filename>ncurses</filename>.
5930 Or, if support for those characters is needed,
5931 determine what <filename>glibc</filename>
5932 features provide the support and restore the
5933 configuration.
5934 </para></listitem>
5935 <listitem><para>Rebuild and repeat the process.
5936 </para></listitem>
5937 </orderedlist></para></listitem>
5938 <listitem><para><filename>busybox</filename>:
5939 For BusyBox, use a process similar as described for
5940 <filename>glibc</filename>.
5941 A difference is you will need to boot the resulting
5942 system to see if you are able to do everything you
5943 expect from the running system.
5944 You need to be sure to integrate configuration fragments
5945 into Busybox because BusyBox handles its own core
5946 features and then allows you to add configuration
5947 fragments on top.
5948 </para></listitem>
5949 </itemizedlist>
5950 </para>
5951 </section>
5952
5953 <section id='iterate-on-the-process'>
5954 <title>Iterate on the Process</title>
5955
5956 <para>
5957 If you have not reached your goals on system size, you need
5958 to iterate on the process.
5959 The process is the same.
5960 Use the tools and see just what is taking up 90% of the root
5961 filesystem and the kernel.
5962 Decide what you can eliminate without limiting your device
5963 beyond what you need.
5964 </para>
5965
5966 <para>
5967 Depending on your system, a good place to look might be
5968 Busybox, which provides a stripped down
5969 version of Unix tools in a single, executable file.
5970 You might be able to drop virtual terminal services or perhaps
5971 ipv6.
5972 </para>
5973 </section>
5974 </section>
5975
5976 <section id='working-with-packages'>
5977 <title>Working with Packages</title>
5978
5979 <para>
5980 This section describes a few tasks that involve packages:
5981 <itemizedlist>
5982 <listitem><para>
5983 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
5984 </para></listitem>
5985 <listitem><para>
5986 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
5987 </para></listitem>
5988 <listitem><para>
5989 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
5990 </para></listitem>
5991 <listitem><para>
5992 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
5993 </para></listitem>
5994 <listitem><para>
5995 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
5996 </para></listitem>
5997 <listitem><para>
5998 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
5999 </para></listitem>
6000 </itemizedlist>
6001 </para>
6002
6003 <section id='excluding-packages-from-an-image'>
6004 <title>Excluding Packages from an Image</title>
6005
6006 <para>
6007 You might find it necessary to prevent specific packages
6008 from being installed into an image.
6009 If so, you can use several variables to direct the build
6010 system to essentially ignore installing recommended packages
6011 or to not install a package at all.
6012 </para>
6013
6014 <para>
6015 The following list introduces variables you can use to
6016 prevent packages from being installed into your image.
6017 Each of these variables only works with IPK and RPM
6018 package types.
6019 Support for Debian packages does not exist.
6020 Also, you can use these variables from your
6021 <filename>local.conf</filename> file or attach them to a
6022 specific image recipe by using a recipe name override.
6023 For more detail on the variables, see the descriptions in the
6024 Yocto Project Reference Manual's glossary chapter.
6025 <itemizedlist>
6026 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
6027 Use this variable to specify "recommended-only"
6028 packages that you do not want installed.
6029 </para></listitem>
6030 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
6031 Use this variable to prevent all "recommended-only"
6032 packages from being installed.
6033 </para></listitem>
6034 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
6035 Use this variable to prevent specific packages from
6036 being installed regardless of whether they are
6037 "recommended-only" or not.
6038 You need to realize that the build process could
6039 fail with an error when you
6040 prevent the installation of a package whose presence
6041 is required by an installed package.
6042 </para></listitem>
6043 </itemizedlist>
6044 </para>
6045 </section>
6046
6047 <section id='incrementing-a-package-revision-number'>
6048 <title>Incrementing a Package Revision Number</title>
6049
6050 <para>
6051 If a committed change results in changing the package output,
6052 then the value of the
6053 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6054 variable needs to be increased (or "bumped").
6055 Increasing <filename>PR</filename> occurs one of two ways:
6056 <itemizedlist>
6057 <listitem><para>Automatically using a Package Revision
6058 Service (PR Service).</para></listitem>
6059 <listitem><para>Manually incrementing the
6060 <filename>PR</filename> variable.</para></listitem>
6061 </itemizedlist>
6062 </para>
6063
6064 <para>
6065 Given that one of the challenges any build system and its
6066 users face is how to maintain a package feed that is compatible
6067 with existing package manager applications such as
6068 RPM, APT, and OPKG, using an automated system is much
6069 preferred over a manual system.
6070 In either system, the main requirement is that version
6071 numbering increases in a linear fashion and that a number of
6072 version components exist that support that linear progression.
6073 </para>
6074
6075 <para>
6076 The following two sections provide information on the PR Service
6077 and on manual <filename>PR</filename> bumping.
6078 </para>
6079
6080 <section id='working-with-a-pr-service'>
6081 <title>Working With a PR Service</title>
6082
6083 <para>
6084 As mentioned, attempting to maintain revision numbers in the
6085 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
6086 is error prone, inaccurate, and causes problems for people
6087 submitting recipes.
6088 Conversely, the PR Service automatically generates
6089 increasing numbers, particularly the revision field,
6090 which removes the human element.
6091 <note>
6092 For additional information on using a PR Service, you
6093 can see the
6094 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
6095 wiki page.
6096 </note>
6097 </para>
6098
6099 <para>
6100 The Yocto Project uses variables in order of
6101 decreasing priority to facilitate revision numbering (i.e.
6102 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
6103 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
6104 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6105 for epoch, version, and revision, respectively).
6106 The values are highly dependent on the policies and
6107 procedures of a given distribution and package feed.
6108 </para>
6109
6110 <para>
6111 Because the OpenEmbedded build system uses
6112 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
6113 which are unique to a given build, the build system
6114 knows when to rebuild packages.
6115 All the inputs into a given task are represented by a
6116 signature, which can trigger a rebuild when different.
6117 Thus, the build system itself does not rely on the
6118 <filename>PR</filename> numbers to trigger a rebuild.
6119 The signatures, however, can be used to generate
6120 <filename>PR</filename> values.
6121 </para>
6122
6123 <para>
6124 The PR Service works with both
6125 <filename>OEBasic</filename> and
6126 <filename>OEBasicHash</filename> generators.
6127 The value of <filename>PR</filename> bumps when the
6128 checksum changes and the different generator mechanisms
6129 change signatures under different circumstances.
6130 </para>
6131
6132 <para>
6133 As implemented, the build system includes values from
6134 the PR Service into the <filename>PR</filename> field as
6135 an addition using the form "<filename>.x</filename>" so
6136 <filename>r0</filename> becomes <filename>r0.1</filename>,
6137 <filename>r0.2</filename> and so forth.
6138 This scheme allows existing <filename>PR</filename> values
6139 to be used for whatever reasons, which include manual
6140 <filename>PR</filename> bumps, should it be necessary.
6141 </para>
6142
6143 <para>
6144 By default, the PR Service is not enabled or running.
6145 Thus, the packages generated are just "self consistent".
6146 The build system adds and removes packages and
6147 there are no guarantees about upgrade paths but images
6148 will be consistent and correct with the latest changes.
6149 </para>
6150
6151 <para>
6152 The simplest form for a PR Service is for it to exist
6153 for a single host development system that builds the
6154 package feed (building system).
6155 For this scenario, you can enable a local PR Service by
6156 setting
6157 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
6158 in your <filename>local.conf</filename> file in the
6159 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
6160 <literallayout class='monospaced'>
6161 PRSERV_HOST = "localhost:0"
6162 </literallayout>
6163 Once the service is started, packages will automatically
6164 get increasing <filename>PR</filename> values and
6165 BitBake will take care of starting and stopping the server.
6166 </para>
6167
6168 <para>
6169 If you have a more complex setup where multiple host
6170 development systems work against a common, shared package
6171 feed, you have a single PR Service running and it is
6172 connected to each building system.
6173 For this scenario, you need to start the PR Service using
6174 the <filename>bitbake-prserv</filename> command:
6175 <literallayout class='monospaced'>
6176 bitbake-prserv &dash;&dash;host <replaceable>ip</replaceable> &dash;&dash;port <replaceable>port</replaceable> &dash;&dash;start
6177 </literallayout>
6178 In addition to hand-starting the service, you need to
6179 update the <filename>local.conf</filename> file of each
6180 building system as described earlier so each system
6181 points to the server and port.
6182 </para>
6183
6184 <para>
6185 It is also recommended you use build history, which adds
6186 some sanity checks to package versions, in conjunction with
6187 the server that is running the PR Service.
6188 To enable build history, add the following to each building
6189 system's <filename>local.conf</filename> file:
6190 <literallayout class='monospaced'>
6191 # It is recommended to activate "buildhistory" for testing the PR service
6192 INHERIT += "buildhistory"
6193 BUILDHISTORY_COMMIT = "1"
6194 </literallayout>
6195 For information on build history, see the
6196 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
6197 section in the Yocto Project Reference Manual.
6198 </para>
6199
6200 <note>
6201 <para>The OpenEmbedded build system does not maintain
6202 <filename>PR</filename> information as part of the
6203 shared state (sstate) packages.
6204 If you maintain an sstate feed, its expected that either
6205 all your building systems that contribute to the sstate
6206 feed use a shared PR Service, or you do not run a PR
6207 Service on any of your building systems.
6208 Having some systems use a PR Service while others do
6209 not leads to obvious problems.</para>
6210 <para>For more information on shared state, see the
6211 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
6212 section in the Yocto Project Reference Manual.</para>
6213 </note>
6214 </section>
6215
6216 <section id='manually-bumping-pr'>
6217 <title>Manually Bumping PR</title>
6218
6219 <para>
6220 The alternative to setting up a PR Service is to manually
6221 bump the
6222 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
6223 variable.
6224 </para>
6225
6226 <para>
6227 If a committed change results in changing the package output,
6228 then the value of the PR variable needs to be increased
6229 (or "bumped") as part of that commit.
6230 For new recipes you should add the <filename>PR</filename>
6231 variable and set its initial value equal to "r0", which is the default.
6232 Even though the default value is "r0", the practice of adding it to a new recipe makes
6233 it harder to forget to bump the variable when you make changes
6234 to the recipe in future.
6235 </para>
6236
6237 <para>
6238 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
6239 you can also use the
6240 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
6241 variable to ensure that
6242 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
6243 <filename>.inc</filename> file itself is changed.
6244 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
6245 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
6246 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
6247 If the <filename>.inc</filename> file is changed then its
6248 <filename>INC_PR</filename> should be incremented.
6249 </para>
6250
6251 <para>
6252 When upgrading the version of a package, assuming the
6253 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
6254 changes, the <filename>PR</filename> variable should be
6255 reset to "r0" (or "$(INC_PR).0" if you are using
6256 <filename>INC_PR</filename>).
6257 </para>
6258
6259 <para>
6260 Usually, version increases occur only to packages.
6261 However, if for some reason <filename>PV</filename> changes but does not
6262 increase, you can increase the
6263 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
6264 variable (Package Epoch).
6265 The <filename>PE</filename> variable defaults to "0".
6266 </para>
6267
6268 <para>
6269 Version numbering strives to follow the
6270 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
6271 Debian Version Field Policy Guidelines</ulink>.
6272 These guidelines define how versions are compared and what "increasing" a version means.
6273 </para>
6274 </section>
6275 </section>
6276
6277 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
6278 <title>Handling a Package Name Alias</title>
6279 <para>
6280 Sometimes a package name you are using might exist under
6281 an alias or as a similarly named package in a different
6282 distribution.
6283 The OpenEmbedded build system implements a
6284 <filename>do_distro_check</filename>
6285 task that automatically connects to major distributions
6286 and checks for these situations.
6287 If the package exists under a different name in a different
6288 distribution, you get a <filename>distro_check</filename>
6289 mismatch.
6290 You can resolve this problem by defining a per-distro recipe
6291 name alias using the
6292 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
6293 variable.
6294 </para>
6295
6296 <para>
6297 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
6298 variable:
6299 <literallayout class='monospaced'>
6300 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
6301 distro2=package_name_alias2 \
6302 distro3=package_name_alias3 \
6303 ..."
6304 </literallayout>
6305 </para>
6306
6307 <para>
6308 If you have more than one distribution alias, separate them with a space.
6309 Note that the build system currently automatically checks the
6310 Fedora, OpenSUSE, Debian, Ubuntu,
6311 and Mandriva distributions for source package recipes without having to specify them
6312 using the <filename>DISTRO_PN_ALIAS</filename> variable.
6313 For example, the following command generates a report that lists the Linux distributions
6314 that include the sources for each of the recipes.
6315 <literallayout class='monospaced'>
6316 $ bitbake world -f -c distro_check
6317 </literallayout>
6318 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
6319 file found in the
6320 <link linkend='source-directory'>Source Directory</link>.
6321 </para>
6322 </section>
6323
6324 <section id='handling-optional-module-packaging'>
6325 <title>Handling Optional Module Packaging</title>
6326
6327 <para>
6328 Many pieces of software split functionality into optional
6329 modules (or plug-ins) and the plug-ins that are built
6330 might depend on configuration options.
6331 To avoid having to duplicate the logic that determines what
6332 modules are available in your recipe or to avoid having
6333 to package each module by hand, the OpenEmbedded build system
6334 provides functionality to handle module packaging dynamically.
6335 </para>
6336
6337 <para>
6338 To handle optional module packaging, you need to do two things:
6339 <itemizedlist>
6340 <listitem><para>Ensure the module packaging is actually
6341 done.</para></listitem>
6342 <listitem><para>Ensure that any dependencies on optional
6343 modules from other recipes are satisfied by your recipe.
6344 </para></listitem>
6345 </itemizedlist>
6346 </para>
6347
6348 <section id='making-sure-the-packaging-is-done'>
6349 <title>Making Sure the Packaging is Done</title>
6350
6351 <para>
6352 To ensure the module packaging actually gets done, you use
6353 the <filename>do_split_packages</filename> function within
6354 the <filename>populate_packages</filename> Python function
6355 in your recipe.
6356 The <filename>do_split_packages</filename> function
6357 searches for a pattern of files or directories under a
6358 specified path and creates a package for each one it finds
6359 by appending to the
6360 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
6361 variable and setting the appropriate values for
6362 <filename>FILES_packagename</filename>,
6363 <filename>RDEPENDS_packagename</filename>,
6364 <filename>DESCRIPTION_packagename</filename>, and so forth.
6365 Here is an example from the <filename>lighttpd</filename>
6366 recipe:
6367 <literallayout class='monospaced'>
6368 python populate_packages_prepend () {
6369 lighttpd_libdir = d.expand('${libdir}')
6370 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
6371 'lighttpd-module-%s', 'Lighttpd module for %s',
6372 extra_depends='')
6373 }
6374 </literallayout>
6375 The previous example specifies a number of things in the
6376 call to <filename>do_split_packages</filename>.
6377 <itemizedlist>
6378 <listitem><para>A directory within the files installed
6379 by your recipe through <filename>do_install</filename>
6380 in which to search.</para></listitem>
6381 <listitem><para>A regular expression used to match module
6382 files in that directory.
6383 In the example, note the parentheses () that mark
6384 the part of the expression from which the module
6385 name should be derived.</para></listitem>
6386 <listitem><para>A pattern to use for the package names.
6387 </para></listitem>
6388 <listitem><para>A description for each package.
6389 </para></listitem>
6390 <listitem><para>An empty string for
6391 <filename>extra_depends</filename>, which disables
6392 the default dependency on the main
6393 <filename>lighttpd</filename> package.
6394 Thus, if a file in <filename>${libdir}</filename>
6395 called <filename>mod_alias.so</filename> is found,
6396 a package called <filename>lighttpd-module-alias</filename>
6397 is created for it and the
6398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
6399 is set to "Lighttpd module for alias".</para></listitem>
6400 </itemizedlist>
6401 </para>
6402
6403 <para>
6404 Often, packaging modules is as simple as the previous
6405 example.
6406 However, more advanced options exist that you can use
6407 within <filename>do_split_packages</filename> to modify its
6408 behavior.
6409 And, if you need to, you can add more logic by specifying
6410 a hook function that is called for each package.
6411 It is also perfectly acceptable to call
6412 <filename>do_split_packages</filename> multiple times if
6413 you have more than one set of modules to package.
6414 </para>
6415
6416 <para>
6417 For more examples that show how to use
6418 <filename>do_split_packages</filename>, see the
6419 <filename>connman.inc</filename> file in the
6420 <filename>meta/recipes-connectivity/connman/</filename>
6421 directory of the <filename>poky</filename>
6422 <link linkend='yocto-project-repositories'>source repository</link>.
6423 You can also find examples in
6424 <filename>meta/classes/kernel.bbclass</filename>.
6425 </para>
6426
6427 <para>
6428 Following is a reference that shows
6429 <filename>do_split_packages</filename> mandatory and
6430 optional arguments:
6431 <literallayout class='monospaced'>
6432 Mandatory arguments
6433
6434 root
6435 The path in which to search
6436 file_regex
6437 Regular expression to match searched files.
6438 Use parentheses () to mark the part of this
6439 expression that should be used to derive the
6440 module name (to be substituted where %s is
6441 used in other function arguments as noted below)
6442 output_pattern
6443 Pattern to use for the package names. Must
6444 include %s.
6445 description
6446 Description to set for each package. Must
6447 include %s.
6448
6449 Optional arguments
6450
6451 postinst
6452 Postinstall script to use for all packages
6453 (as a string)
6454 recursive
6455 True to perform a recursive search - default
6456 False
6457 hook
6458 A hook function to be called for every match.
6459 The function will be called with the following
6460 arguments (in the order listed):
6461
6462 f
6463 Full path to the file/directory match
6464 pkg
6465 The package name
6466 file_regex
6467 As above
6468 output_pattern
6469 As above
6470 modulename
6471 The module name derived using file_regex
6472
6473 extra_depends
6474 Extra runtime dependencies (RDEPENDS) to be
6475 set for all packages. The default value of None
6476 causes a dependency on the main package
6477 (${PN}) - if you do not want this, pass empty
6478 string '' for this parameter.
6479 aux_files_pattern
6480 Extra item(s) to be added to FILES for each
6481 package. Can be a single string item or a list
6482 of strings for multiple items. Must include %s.
6483 postrm
6484 postrm script to use for all packages (as a
6485 string)
6486 allow_dirs
6487 True to allow directories to be matched -
6488 default False
6489 prepend
6490 If True, prepend created packages to PACKAGES
6491 instead of the default False which appends them
6492 match_path
6493 match file_regex on the whole relative path to
6494 the root rather than just the file name
6495 aux_files_pattern_verbatim
6496 Extra item(s) to be added to FILES for each
6497 package, using the actual derived module name
6498 rather than converting it to something legal
6499 for a package name. Can be a single string item
6500 or a list of strings for multiple items. Must
6501 include %s.
6502 allow_links
6503 True to allow symlinks to be matched - default
6504 False
6505 summary
6506 Summary to set for each package. Must include %s;
6507 defaults to description if not set.
6508 </literallayout>
6509 </para>
6510 </section>
6511
6512 <section id='satisfying-dependencies'>
6513 <title>Satisfying Dependencies</title>
6514
6515 <para>
6516 The second part for handling optional module packaging
6517 is to ensure that any dependencies on optional modules
6518 from other recipes are satisfied by your recipe.
6519 You can be sure these dependencies are satisfied by
6520 using the
6521 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
6522 Here is an example that continues with the
6523 <filename>lighttpd</filename> recipe shown earlier:
6524 <literallayout class='monospaced'>
6525 PACKAGES_DYNAMIC = "lighttpd-module-.*"
6526 </literallayout>
6527 The name specified in the regular expression can of
6528 course be anything.
6529 In this example, it is <filename>lighttpd-module-</filename>
6530 and is specified as the prefix to ensure that any
6531 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
6532 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
6533 on a package name starting with the prefix are satisfied
6534 during build time.
6535 If you are using <filename>do_split_packages</filename>
6536 as described in the previous section, the value you put in
6537 <filename>PACKAGES_DYNAMIC</filename> should correspond to
6538 the name pattern specified in the call to
6539 <filename>do_split_packages</filename>.
6540 </para>
6541 </section>
6542 </section>
6543
6544 <section id='using-runtime-package-management'>
6545 <title>Using Runtime Package Management</title>
6546
6547 <para>
6548 During a build, BitBake always transforms a recipe into one or
6549 more packages.
6550 For example, BitBake takes the <filename>bash</filename> recipe
6551 and currently produces the <filename>bash-dbg</filename>,
6552 <filename>bash-staticdev</filename>,
6553 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
6554 <filename>bash-locale</filename>, and
6555 <filename>bash</filename> packages.
6556 Not all generated packages are included in an image.
6557 </para>
6558
6559 <para>
6560 In several situations, you might need to update, add, remove,
6561 or query the packages on a target device at runtime
6562 (i.e. without having to generate a new image).
6563 Examples of such situations include:
6564 <itemizedlist>
6565 <listitem><para>
6566 You want to provide in-the-field updates to deployed
6567 devices (e.g. security updates).
6568 </para></listitem>
6569 <listitem><para>
6570 You want to have a fast turn-around development cycle
6571 for one or more applications that run on your device.
6572 </para></listitem>
6573 <listitem><para>
6574 You want to temporarily install the "debug" packages
6575 of various applications on your device so that
6576 debugging can be greatly improved by allowing
6577 access to symbols and source debugging.
6578 </para></listitem>
6579 <listitem><para>
6580 You want to deploy a more minimal package selection of
6581 your device but allow in-the-field updates to add a
6582 larger selection for customization.
6583 </para></listitem>
6584 </itemizedlist>
6585 </para>
6586
6587 <para>
6588 In all these situations, you have something similar to a more
6589 traditional Linux distribution in that in-field devices
6590 are able to receive pre-compiled packages from a server for
6591 installation or update.
6592 Being able to install these packages on a running,
6593 in-field device is what is termed "runtime package
6594 management".
6595 </para>
6596
6597 <para>
6598 In order to use runtime package management, you
6599 need a host/server machine that serves up the pre-compiled
6600 packages plus the required metadata.
6601 You also need package manipulation tools on the target.
6602 The build machine is a likely candidate to act as the server.
6603 However, that machine does not necessarily have to be the
6604 package server.
6605 The build machine could push its artifacts to another machine
6606 that acts as the server (e.g. Internet-facing).
6607 </para>
6608
6609 <para>
6610 A simple build that targets just one device produces
6611 more than one package database.
6612 In other words, the packages produced by a build are separated
6613 out into a couple of different package groupings based on
6614 criteria such as the target's CPU architecture, the target
6615 board, or the C library used on the target.
6616 For example, a build targeting the <filename>qemuarm</filename>
6617 device produces the following three package databases:
6618 <filename>all</filename>, <filename>armv5te</filename>, and
6619 <filename>qemuarm</filename>.
6620 If you wanted your <filename>qemuarm</filename> device to be
6621 aware of all the packages that were available to it,
6622 you would need to point it to each of these databases
6623 individually.
6624 In a similar way, a traditional Linux distribution usually is
6625 configured to be aware of a number of software repositories
6626 from which it retrieves packages.
6627 </para>
6628
6629 <para>
6630 Using runtime package management is completely optional and
6631 not required for a successful build or deployment in any
6632 way.
6633 But if you want to make use of runtime package management,
6634 you need to do a couple things above and beyond the basics.
6635 The remainder of this section describes what you need to do.
6636 </para>
6637
6638 <section id='runtime-package-management-build'>
6639 <title>Build Considerations</title>
6640
6641 <para>
6642 This section describes build considerations that you need
6643 to be aware of in order to provide support for runtime
6644 package management.
6645 </para>
6646
6647 <para>
6648 When BitBake generates packages it needs to know
6649 what format or formats to use.
6650 In your configuration, you use the
6651 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
6652 variable to specify the format.
6653 <note>
6654 You can choose to have more than one format but you must
6655 provide at least one.
6656 </note>
6657 </para>
6658
6659 <para>
6660 If you would like your image to start off with a basic
6661 package database of the packages in your current build
6662 as well as have the relevant tools available on the
6663 target for runtime package management, you can include
6664 "package-management" in the
6665 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6666 variable.
6667 Including "package-management" in this
6668 configuration variable ensures that when the image
6669 is assembled for your target, the image includes
6670 the currently-known package databases as well as
6671 the target-specific tools required for runtime
6672 package management to be performed on the target.
6673 However, this is not strictly necessary.
6674 You could start your image off without any databases
6675 but only include the required on-target package
6676 tool(s).
6677 As an example, you could include "opkg" in your
6678 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
6679 variable if you are using the IPK package format.
6680 You can then initialize your target's package database(s)
6681 later once your image is up and running.
6682 </para>
6683
6684 <para>
6685 Whenever you perform any sort of build step that can
6686 potentially generate a package or modify an existing
6687 package, it is always a good idea to re-generate the
6688 package index with:
6689 <literallayout class='monospaced'>
6690 $ bitbake package-index
6691 </literallayout>
6692 Realize that it is not sufficient to simply do the
6693 following:
6694 <literallayout class='monospaced'>
6695 $ bitbake <replaceable>some-package</replaceable> package-index
6696 </literallayout>
6697 This is because BitBake does not properly schedule the
6698 <filename>package-index</filename> target fully after any
6699 other target has completed.
6700 Thus, be sure to run the package update step separately.
6701 </para>
6702
6703 <para>
6704 As described below in the
6705 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
6706 section, if you are using IPK as your package format, you
6707 can make use of the
6708 <filename>distro-feed-configs</filename> recipe provided
6709 by <filename>meta-oe</filename> in order to configure your
6710 target to use your IPK databases.
6711 </para>
6712
6713 <para>
6714 When your build is complete, your packages reside in the
6715 <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
6716 directory.
6717 For example, if <filename>${TMPDIR}</filename>
6718 is <filename>tmp</filename> and your selected package type
6719 is IPK, then your IPK packages are available in
6720 <filename>tmp/deploy/ipk</filename>.
6721 </para>
6722 </section>
6723
6724 <section id='runtime-package-management-server'>
6725 <title>Host or Server Machine Setup</title>
6726
6727 <para>
6728 Typically, packages are served from a server using
6729 HTTP.
6730 However, other protocols are possible.
6731 If you want to use HTTP, then setup and configure a
6732 web server, such as Apache 2 or lighttpd, on the machine
6733 serving the packages.
6734 </para>
6735
6736 <para>
6737 As previously mentioned, the build machine can act as the
6738 package server.
6739 In the following sections that describe server machine
6740 setups, the build machine is assumed to also be the server.
6741 </para>
6742
6743 <section id='package-server-apache'>
6744 <title>Serving Packages via Apache 2</title>
6745
6746 <para>
6747 This example assumes you are using the Apache 2
6748 server:
6749 <orderedlist>
6750 <listitem><para>
6751 Add the directory to your Apache
6752 configuration, which you can find at
6753 <filename>/etc/httpd/conf/httpd.conf</filename>.
6754 Use commands similar to these on the
6755 development system.
6756 These example commands assume a top-level
6757 <link linkend='source-directory'>Source Directory</link>
6758 named <filename>poky</filename> in your home
6759 directory.
6760 The example also assumes an RPM package type.
6761 If you are using a different package type, such
6762 as IPK, use "ipk" in the pathnames:
6763 <literallayout class='monospaced'>
6764 &lt;VirtualHost *:80&gt;
6765 ....
6766 Alias /rpm ~/poky/build/tmp/deploy/rpm
6767 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
6768 Options +Indexes
6769 &lt;/Directory&gt;
6770 &lt;/VirtualHost&gt;
6771 </literallayout></para></listitem>
6772 <listitem><para>
6773 Reload the Apache configuration as described
6774 in this step.
6775 For all commands, be sure you have root
6776 privileges.
6777 </para>
6778
6779 <para>
6780 If your development system is using Fedora or
6781 CentOS, use the following:
6782 <literallayout class='monospaced'>
6783 # service httpd reload
6784 </literallayout>
6785 For Ubuntu and Debian, use the following:
6786 <literallayout class='monospaced'>
6787 # /etc/init.d/apache2 reload
6788 </literallayout>
6789 For OpenSUSE, use the following:
6790 <literallayout class='monospaced'>
6791 # /etc/init.d/apache2 reload
6792 </literallayout></para></listitem>
6793 <listitem><para>
6794 If you are using Security-Enhanced Linux
6795 (SELinux), you need to label the files as
6796 being accessible through Apache.
6797 Use the following command from the development
6798 host.
6799 This example assumes RPM package types:
6800 <literallayout class='monospaced'>
6801 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
6802 </literallayout></para></listitem>
6803 </orderedlist>
6804 </para>
6805 </section>
6806
6807 <section id='package-server-lighttpd'>
6808 <title>Serving Packages via lighttpd</title>
6809
6810 <para>
6811 If you are using lighttpd, all you need
6812 to do is to provide a link from your
6813 <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
6814 directory to lighttpd's document-root.
6815 You can determine the specifics of your lighttpd
6816 installation by looking through its configuration file,
6817 which is usually found at:
6818 <filename>/etc/lighttpd/lighttpd.conf</filename>.
6819 </para>
6820
6821 <para>
6822 For example, if you are using IPK, lighttpd's
6823 document-root is set to
6824 <filename>/var/www/lighttpd</filename>, and you had
6825 packages for a target named "BOARD",
6826 then you might create a link from your build location
6827 to lighttpd's document-root as follows:
6828 <literallayout class='monospaced'>
6829 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
6830 </literallayout>
6831 </para>
6832
6833 <para>
6834 At this point, you need to start the lighttpd server.
6835 The method used to start the server varies by
6836 distribution.
6837 However, one basic method that starts it by hand is:
6838 <literallayout class='monospaced'>
6839 # lighttpd -f /etc/lighttpd/lighttpd.conf
6840 </literallayout>
6841 </para>
6842 </section>
6843 </section>
6844
6845 <section id='runtime-package-management-target'>
6846 <title>Target Setup</title>
6847
6848 <para>
6849 Setting up the target differs depending on the
6850 package management system.
6851 This section provides information for RPM and IPK.
6852 </para>
6853
6854 <section id='runtime-package-management-target-rpm'>
6855 <title>Using RPM</title>
6856
6857 <para>
6858 The application for performing runtime package
6859 management of RPM packages on the target is called
6860 <filename>smart</filename>.
6861 </para>
6862
6863 <para>
6864 On the target machine, you need to inform
6865 <filename>smart</filename> of every package database
6866 you want to use.
6867 As an example, suppose your target device can use the
6868 following three package databases from a server named
6869 <filename>server.name</filename>:
6870 <filename>all</filename>, <filename>i586</filename>,
6871 and <filename>qemux86</filename>.
6872 Given this example, issue the following commands on the
6873 target:
6874 <literallayout class='monospaced'>
6875 # smart channel &dash;&dash;add all type=rpm-md baseurl=http://server.name/rpm/all
6876 # smart channel &dash;&dash;add i585 type=rpm-md baseurl=http://server.name/rpm/i586
6877 # smart channel &dash;&dash;add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
6878 </literallayout>
6879 Also from the target machine, fetch the repository
6880 information using this command:
6881 <literallayout class='monospaced'>
6882 # smart update
6883 </literallayout>
6884 You can now use the <filename>smart query</filename>
6885 and <filename>smart install</filename> commands to
6886 find and install packages from the repositories.
6887 </para>
6888 </section>
6889
6890 <section id='runtime-package-management-target-ipk'>
6891 <title>Using IPK</title>
6892
6893 <para>
6894 The application for performing runtime package
6895 management of IPK packages on the target is called
6896 <filename>opkg</filename>.
6897 </para>
6898
6899 <para>
6900 In order to inform <filename>opkg</filename> of the
6901 package databases you want to use, simply create one
6902 or more <filename>*.conf</filename> files in the
6903 <filename>/etc/opkg</filename> directory on the target.
6904 The <filename>opkg</filename> application uses them
6905 to find its available package databases.
6906 As an example, suppose you configured your HTTP server
6907 on your machine named
6908 <filename>www.mysite.com</filename> to serve files
6909 from a <filename>BOARD-dir</filename> directory under
6910 its document-root.
6911 In this case, you might create a configuration
6912 file on the target called
6913 <filename>/etc/opkg/base-feeds.conf</filename> that
6914 contains:
6915 <literallayout class='monospaced'>
6916 src/gz all http://www.mysite.com/BOARD-dir/all
6917 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
6918 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
6919 </literallayout>
6920 </para>
6921
6922 <para>
6923 As a way of making it easier to generate and make
6924 these IPK configuration files available on your
6925 target, simply define
6926 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
6927 to point to your server and the location within the
6928 document-root which contains the databases.
6929 For example: if you are serving your packages over
6930 HTTP, your server's IP address is 192.168.7.1, and
6931 your databases are located in a directory called
6932 <filename>BOARD-dir</filename> underneath your HTTP
6933 server's document-root, you need to set
6934 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
6935 <filename>http://192.168.7.1/BOARD-dir</filename> and
6936 a set of configuration files will be generated for you
6937 in your target to work with this feed.
6938 </para>
6939
6940 <para>
6941 On the target machine, fetch (or refresh) the
6942 repository information using this command:
6943 <literallayout class='monospaced'>
6944 # opkg update
6945 </literallayout>
6946 You can now use the <filename>opkg list</filename> and
6947 <filename>opkg install</filename> commands to find and
6948 install packages from the repositories.
6949 </para>
6950 </section>
6951 </section>
6952 </section>
6953
6954 <section id='testing-packages-with-ptest'>
6955 <title>Testing Packages With ptest</title>
6956
6957 <para>
6958 A Package Test (ptest) runs tests against packages built
6959 by the OpenEmbedded build system on the target machine.
6960 A ptest contains at least two items: the actual test, and
6961 a shell script (<filename>run-ptest</filename>) that starts
6962 the test.
6963 The shell script that starts the test must not contain
6964 the actual test - the script only starts the test.
6965 On the other hand, the test can be anything from a simple
6966 shell script that runs a binary and checks the output to
6967 an elaborate system of test binaries and data files.
6968 </para>
6969
6970 <para>
6971 The test generates output in the format used by
6972 Automake:
6973 <literallayout class='monospaced'>
6974 <replaceable>result</replaceable>: <replaceable>testname</replaceable>
6975 </literallayout>
6976 where the result can be <filename>PASS</filename>,
6977 <filename>FAIL</filename>, or <filename>SKIP</filename>,
6978 and the testname can be any identifying string.
6979 </para>
6980
6981 <para>
6982 For a list of Yocto Project recipes that are already
6983 enabled with ptest, see the
6984 <ulink url='https://wiki.yoctoproject.org/wiki/Ptest'>Ptest</ulink>
6985 wiki page.
6986 <note>
6987 A recipe is "ptest-enabled" if it inherits the
6988 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
6989 class.
6990 </note>
6991 </para>
6992
6993 <section id='adding-ptest-to-your-build'>
6994 <title>Adding ptest to Your Build</title>
6995
6996 <para>
6997 To add package testing to your build, add the
6998 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
6999 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
7000 variables to your <filename>local.conf</filename> file,
7001 which is found in the
7002 <link linkend='build-directory'>Build Directory</link>:
7003 <literallayout class='monospaced'>
7004 DISTRO_FEATURES_append = " ptest"
7005 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
7006 </literallayout>
7007 Once your build is complete, the ptest files are installed
7008 into the
7009 <filename>/usr/lib/<replaceable>package</replaceable>/ptest</filename>
7010 directory within the image, where
7011 <filename><replaceable>package</replaceable></filename>
7012 is the name of the package.
7013 </para>
7014 </section>
7015
7016 <section id='running-ptest'>
7017 <title>Running ptest</title>
7018
7019 <para>
7020 The <filename>ptest-runner</filename> package installs a
7021 shell script that loops through all installed ptest test
7022 suites and runs them in sequence.
7023 Consequently, you might want to add this package to
7024 your image.
7025 </para>
7026 </section>
7027
7028 <section id='getting-your-package-ready'>
7029 <title>Getting Your Package Ready</title>
7030
7031 <para>
7032 In order to enable a recipe to run installed ptests
7033 on target hardware,
7034 you need to prepare the recipes that build the packages
7035 you want to test.
7036 Here is what you have to do for each recipe:
7037 <itemizedlist>
7038 <listitem><para><emphasis>Be sure the recipe
7039 inherits the
7040 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
7041 class:</emphasis>
7042 Include the following line in each recipe:
7043 <literallayout class='monospaced'>
7044 inherit ptest
7045 </literallayout>
7046 </para></listitem>
7047 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
7048 This script starts your test.
7049 Locate the script where you will refer to it
7050 using
7051 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
7052 Here is an example that starts a test for
7053 <filename>dbus</filename>:
7054 <literallayout class='monospaced'>
7055 #!/bin/sh
7056 cd test
7057 make -k runtest-TESTS
7058 </literallayout>
7059 </para></listitem>
7060 <listitem><para><emphasis>Ensure dependencies are
7061 met:</emphasis>
7062 If the test adds build or runtime dependencies
7063 that normally do not exist for the package
7064 (such as requiring "make" to run the test suite),
7065 use the
7066 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
7067 and
7068 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
7069 variables in your recipe in order for the package
7070 to meet the dependencies.
7071 Here is an example where the package has a runtime
7072 dependency on "make":
7073 <literallayout class='monospaced'>
7074 RDEPENDS_${PN}-ptest += "make"
7075 </literallayout>
7076 </para></listitem>
7077 <listitem><para><emphasis>Add a function to build the
7078 test suite:</emphasis>
7079 Not many packages support cross-compilation of
7080 their test suites.
7081 Consequently, you usually need to add a
7082 cross-compilation function to the package.
7083 </para>
7084 <para>Many packages based on Automake compile and
7085 run the test suite by using a single command
7086 such as <filename>make check</filename>.
7087 However, the native <filename>make check</filename>
7088 builds and runs on the same computer, while
7089 cross-compiling requires that the package is built
7090 on the host but executed on the target.
7091 The built version of Automake that ships with the
7092 Yocto Project includes a patch that separates
7093 building and execution.
7094 Consequently, packages that use the unaltered,
7095 patched version of <filename>make check</filename>
7096 automatically cross-compiles.</para>
7097 <para>Regardless, you still must add a
7098 <filename>do_compile_ptest</filename> function to
7099 build the test suite.
7100 Add a function similar to the following to your
7101 recipe:
7102 <literallayout class='monospaced'>
7103 do_compile_ptest() {
7104 oe_runmake buildtest-TESTS
7105 }
7106 </literallayout>
7107 </para></listitem>
7108 <listitem><para><emphasis>Ensure special configurations
7109 are set:</emphasis>
7110 If the package requires special configurations
7111 prior to compiling the test code, you must
7112 insert a <filename>do_configure_ptest</filename>
7113 function into the recipe.
7114 </para></listitem>
7115 <listitem><para><emphasis>Install the test
7116 suite:</emphasis>
7117 The <filename>ptest</filename> class
7118 automatically copies the file
7119 <filename>run-ptest</filename> to the target and
7120 then runs make <filename>install-ptest</filename>
7121 to run the tests.
7122 If this is not enough, you need to create a
7123 <filename>do_install_ptest</filename> function and
7124 make sure it gets called after the
7125 "make install-ptest" completes.
7126 </para></listitem>
7127 </itemizedlist>
7128 </para>
7129 </section>
7130 </section>
7131 </section>
7132
7133 <section id='working-with-source-files'>
7134 <title>Working with Source Files</title>
7135
7136 <para>
7137 The OpenEmbedded build system works with source files located
7138 through the
7139 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7140 variable.
7141 When you build something using BitBake, a big part of the operation
7142 is locating and downloading all the source tarballs.
7143 For images, downloading all the source for various packages can
7144 take a significant amount of time.
7145 </para>
7146
7147 <para>
7148 This section presents information for working with source
7149 files that can lead to more efficient use of resources and
7150 time.
7151 </para>
7152
7153 <section id='setting-up-effective-mirrors'>
7154 <title>Setting up Effective Mirrors</title>
7155
7156 <para>
7157 As mentioned, a good deal that goes into a Yocto Project
7158 build is simply downloading all of the source tarballs.
7159 Maybe you have been working with another build system
7160 (OpenEmbedded or Angstrom) for which you have built up a
7161 sizable directory of source tarballs.
7162 Or, perhaps someone else has such a directory for which you
7163 have read access.
7164 If so, you can save time by adding statements to your
7165 configuration file so that the build process checks local
7166 directories first for existing tarballs before checking the
7167 Internet.
7168 </para>
7169
7170 <para>
7171 Here is an efficient way to set it up in your
7172 <filename>local.conf</filename> file:
7173 <literallayout class='monospaced'>
7174 SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/"
7175 INHERIT += "own-mirrors"
7176 BB_GENERATE_MIRROR_TARBALLS = "1"
7177 # BB_NO_NETWORK = "1"
7178 </literallayout>
7179 </para>
7180
7181 <para>
7182 In the previous example, the
7183 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
7184 variable causes the OpenEmbedded build system to generate
7185 tarballs of the Git repositories and store them in the
7186 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
7187 directory.
7188 Due to performance reasons, generating and storing these
7189 tarballs is not the build system's default behavior.
7190 </para>
7191
7192 <para>
7193 You can also use the
7194 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
7195 variable.
7196 For an example, see the variable's glossary entry in the
7197 Yocto Project Reference Manual.
7198 </para>
7199 </section>
7200
7201 <section id='getting-source-files-and-suppressing-the-build'>
7202 <title>Getting Source Files and Suppressing the Build</title>
7203
7204 <para>
7205 Another technique you can use to ready yourself for a
7206 successive string of build operations, is to pre-fetch
7207 all the source files without actually starting a build.
7208 This technique lets you work through any download issues
7209 and ultimately gathers all the source files into your
7210 download directory
7211 <ulink url='&YOCTO_DOCS_REF_URL;#structure-build-downloads'><filename>build/downloads</filename></ulink>,
7212 which is located with
7213 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>.
7214 </para>
7215
7216 <para>
7217 Use the following BitBake command form to fetch all the
7218 necessary sources without starting the build:
7219 <literallayout class='monospaced'>
7220 $ bitbake -c fetchall <replaceable>target</replaceable>
7221 </literallayout>
7222 This variation of the BitBake command guarantees that you
7223 have all the sources for that BitBake target should you
7224 disconnect from the Internet and want to do the build
7225 later offline.
7226 </para>
7227 </section>
7228 </section>
7229
7230 <section id="building-software-from-an-external-source">
7231 <title>Building Software from an External Source</title>
7232
7233 <para>
7234 By default, the OpenEmbedded build system uses the
7235 <link linkend='build-directory'>Build Directory</link> when
7236 building source code.
7237 The build process involves fetching the source files, unpacking
7238 them, and then patching them if necessary before the build takes
7239 place.
7240 </para>
7241
7242 <para>
7243 Situations exist where you might want to build software from source
7244 files that are external to and thus outside of the
7245 OpenEmbedded build system.
7246 For example, suppose you have a project that includes a new BSP with
7247 a heavily customized kernel.
7248 And, you want to minimize exposing the build system to the
7249 development team so that they can focus on their project and
7250 maintain everyone's workflow as much as possible.
7251 In this case, you want a kernel source directory on the development
7252 machine where the development occurs.
7253 You want the recipe's
7254 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7255 variable to point to the external directory and use it as is, not
7256 copy it.
7257 </para>
7258
7259 <para>
7260 To build from software that comes from an external source, all you
7261 need to do is inherit the
7262 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
7263 class and then set the
7264 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
7265 variable to point to your external source code.
7266 Here are the statements to put in your
7267 <filename>local.conf</filename> file:
7268 <literallayout class='monospaced'>
7269 INHERIT += "externalsrc"
7270 EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
7271 </literallayout>
7272 </para>
7273
7274 <para>
7275 This next example shows how to accomplish the same thing by setting
7276 <filename>EXTERNALSRC</filename> in the recipe itself or in the
7277 recipe's append file:
7278 <literallayout class='monospaced'>
7279 EXTERNALSRC = "<replaceable>path</replaceable>"
7280 EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
7281 </literallayout>
7282 <note>
7283 In order for these settings to take effect, you must globally
7284 or locally inherit the
7285 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
7286 class.
7287 </note>
7288 </para>
7289
7290 <para>
7291 By default, <filename>externalsrc.bbclass</filename> builds
7292 the source code in a directory separate from the external source
7293 directory as specified by
7294 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
7295 If you need to have the source built in the same directory in
7296 which it resides, or some other nominated directory, you can set
7297 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
7298 to point to that directory:
7299 <literallayout class='monospaced'>
7300 EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
7301 </literallayout>
7302 </para>
7303 </section>
7304
7305 <section id="selecting-an-initialization-manager">
7306 <title>Selecting an Initialization Manager</title>
7307
7308 <para>
7309 By default, the Yocto Project uses SysVinit as the initialization
7310 manager.
7311 However, support also exists for systemd,
7312 which is a full replacement for init with
7313 parallel starting of services, reduced shell overhead and other
7314 features that are used by many distributions.
7315 </para>
7316
7317 <para>
7318 If you want to use SysVinit, you do
7319 not have to do anything.
7320 But, if you want to use systemd, you must
7321 take some steps as described in the following sections.
7322 </para>
7323
7324 <section id='using-systemd-exclusively'>
7325 <title>Using systemd Exclusively</title>
7326
7327 <para>
7328 Set the these variables in your distribution configuration
7329 file as follows:
7330 <literallayout class='monospaced'>
7331 DISTRO_FEATURES_append = " systemd"
7332 VIRTUAL-RUNTIME_init_manager = "systemd"
7333 </literallayout>
7334 You can also prevent the SysVinit
7335 distribution feature from
7336 being automatically enabled as follows:
7337 <literallayout class='monospaced'>
7338 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
7339 </literallayout>
7340 Doing so removes any redundant SysVinit scripts.
7341 </para>
7342
7343 <para>
7344 To remove initscripts from your image altogether,
7345 set this variable also:
7346 <literallayout class='monospaced'>
7347 VIRTUAL-RUNTIME_initscripts = ""
7348 </literallayout>
7349 </para>
7350
7351 <para>
7352 For information on the backfill variable, see
7353 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
7354 </para>
7355 </section>
7356
7357 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
7358 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
7359
7360 <para>
7361 Set these variables in your distribution configuration
7362 file as follows:
7363 <literallayout class='monospaced'>
7364 DISTRO_FEATURES_append = " systemd"
7365 VIRTUAL-RUNTIME_init_manager = "systemd"
7366 </literallayout>
7367 Doing so causes your main image to use the
7368 <filename>packagegroup-core-boot.bb</filename> recipe and
7369 systemd.
7370 The rescue/minimal image cannot use this package group.
7371 However, it can install SysVinit
7372 and the appropriate packages will have support for both
7373 systemd and SysVinit.
7374 </para>
7375 </section>
7376 </section>
7377
7378 <section id="platdev-appdev-srcrev">
7379 <title>Using an External SCM</title>
7380
7381 <para>
7382 If you're working on a recipe that pulls from an external Source
7383 Code Manager (SCM), it is possible to have the OpenEmbedded build
7384 system notice new recipe changes added to the SCM and then build
7385 the resulting packages that depend on the new recipes by using
7386 the latest versions.
7387 This only works for SCMs from which it is possible to get a
7388 sensible revision number for changes.
7389 Currently, you can do this with Apache Subversion (SVN), Git, and
7390 Bazaar (BZR) repositories.
7391 </para>
7392
7393 <para>
7394 To enable this behavior, the
7395 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
7396 of the recipe needs to reference
7397 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
7398 Here is an example:
7399 <literallayout class='monospaced'>
7400 PV = "1.2.3+git${SRCPV}
7401 </literallayout>
7402 Then, you can add the following to your
7403 <filename>local.conf</filename>:
7404 <literallayout class='monospaced'>
7405 SRCREV_pn-<replaceable>PN</replaceable> = "${AUTOREV}"
7406 </literallayout>
7407 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
7408 is the name of the recipe for which you want to enable automatic source
7409 revision updating.
7410 </para>
7411
7412 <para>
7413 If you do not want to update your local configuration file, you can
7414 add the following directly to the recipe to finish enabling
7415 the feature:
7416 <literallayout class='monospaced'>
7417 SRCREV = "${AUTOREV}"
7418 </literallayout>
7419 </para>
7420
7421 <para>
7422 The Yocto Project provides a distribution named
7423 <filename>poky-bleeding</filename>, whose configuration
7424 file contains the line:
7425 <literallayout class='monospaced'>
7426 require conf/distro/include/poky-floating-revisions.inc
7427 </literallayout>
7428 This line pulls in the listed include file that contains
7429 numerous lines of exactly that form:
7430 <literallayout class='monospaced'>
7431 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
7432 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
7433 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
7434 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
7435 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
7436 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
7437 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
7438 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
7439 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
7440 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
7441 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
7442 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
7443 SRCREV_pn-screenshot ?= "${AUTOREV}"
7444 SRCREV_pn-libfakekey ?= "${AUTOREV}"
7445 SRCREV_pn-oprofileui ?= "${AUTOREV}"
7446 .
7447 .
7448 .
7449 </literallayout>
7450 These lines allow you to experiment with building a
7451 distribution that tracks the latest development source
7452 for numerous packages.
7453 <note><title>Caution</title>
7454 The <filename>poky-bleeding</filename> distribution
7455 is not tested on a regular basis.
7456 Keep this in mind if you use it.
7457 </note>
7458 </para>
7459 </section>
7460
7461 <section id='creating-a-read-only-root-filesystem'>
7462 <title>Creating a Read-Only Root Filesystem</title>
7463
7464 <para>
7465 Suppose, for security reasons, you need to disable
7466 your target device's root filesystem's write permissions
7467 (i.e. you need a read-only root filesystem).
7468 Or, perhaps you are running the device's operating system
7469 from a read-only storage device.
7470 For either case, you can customize your image for
7471 that behavior.
7472 </para>
7473
7474 <note>
7475 Supporting a read-only root filesystem requires that the system and
7476 applications do not try to write to the root filesystem.
7477 You must configure all parts of the target system to write
7478 elsewhere, or to gracefully fail in the event of attempting to
7479 write to the root filesystem.
7480 </note>
7481
7482 <section id='creating-the-root-filesystem'>
7483 <title>Creating the Root Filesystem</title>
7484
7485 <para>
7486 To create the read-only root filesystem, simply add the
7487 "read-only-rootfs" feature to your image.
7488 Using either of the following statements in your
7489 image recipe or from within the
7490 <filename>local.conf</filename> file found in the
7491 <link linkend='build-directory'>Build Directory</link>
7492 causes the build system to create a read-only root filesystem:
7493 <literallayout class='monospaced'>
7494 IMAGE_FEATURES = "read-only-rootfs"
7495 </literallayout>
7496 or
7497 <literallayout class='monospaced'>
7498 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
7499 </literallayout>
7500 </para>
7501
7502 <para>
7503 For more information on how to use these variables, see the
7504 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
7505 section.
7506 For information on the variables, see
7507 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
7508 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
7509 </para>
7510 </section>
7511
7512 <section id='post-installation-scripts'>
7513 <title>Post-Installation Scripts</title>
7514
7515 <para>
7516 It is very important that you make sure all
7517 post-Installation (<filename>pkg_postinst</filename>) scripts
7518 for packages that are installed into the image can be run
7519 at the time when the root filesystem is created during the
7520 build on the host system.
7521 These scripts cannot attempt to run during first-boot on the
7522 target device.
7523 With the "read-only-rootfs" feature enabled,
7524 the build system checks during root filesystem creation to make
7525 sure all post-installation scripts succeed.
7526 If any of these scripts still need to be run after the root
7527 filesystem is created, the build immediately fails.
7528 These build-time checks ensure that the build fails
7529 rather than the target device fails later during its
7530 initial boot operation.
7531 </para>
7532
7533 <para>
7534 Most of the common post-installation scripts generated by the
7535 build system for the out-of-the-box Yocto Project are engineered
7536 so that they can run during root filesystem creation
7537 (e.g. post-installation scripts for caching fonts).
7538 However, if you create and add custom scripts, you need
7539 to be sure they can be run during this file system creation.
7540 </para>
7541
7542 <para>
7543 Here are some common problems that prevent
7544 post-installation scripts from running during root filesystem
7545 creation:
7546 <itemizedlist>
7547 <listitem><para>
7548 <emphasis>Not using $D in front of absolute
7549 paths:</emphasis>
7550 The build system defines
7551 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
7552 when the root filesystem is created.
7553 Furthermore, <filename>$D</filename> is blank when the
7554 script is run on the target device.
7555 This implies two purposes for <filename>$D</filename>:
7556 ensuring paths are valid in both the host and target
7557 environments, and checking to determine which
7558 environment is being used as a method for taking
7559 appropriate actions.
7560 </para></listitem>
7561 <listitem><para>
7562 <emphasis>Attempting to run processes that are
7563 specific to or dependent on the target
7564 architecture:</emphasis>
7565 You can work around these attempts by using native
7566 tools to accomplish the same tasks, or
7567 by alternatively running the processes under QEMU,
7568 which has the <filename>qemu_run_binary</filename>
7569 function.
7570 For more information, see the
7571 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
7572 class.</para></listitem>
7573 </itemizedlist>
7574 </para>
7575 </section>
7576
7577 <section id='areas-with-write-access'>
7578 <title>Areas With Write Access</title>
7579
7580 <para>
7581 With the "read-only-rootfs" feature enabled,
7582 any attempt by the target to write to the root filesystem at
7583 runtime fails.
7584 Consequently, you must make sure that you configure processes
7585 and applications that attempt these types of writes do so
7586 to directories with write access (e.g.
7587 <filename>/tmp</filename> or <filename>/var/run</filename>).
7588 </para>
7589 </section>
7590 </section>
7591
7592 <section id="performing-automated-runtime-testing">
7593 <title>Performing Automated Runtime Testing</title>
7594
7595 <para>
7596 The OpenEmbedded build system makes available a series of automated
7597 tests for images to verify runtime functionality.
7598 You can run these tests on either QEMU or actual target hardware.
7599 Tests are written in Python making use of the
7600 <filename>unittest</filename> module, and the majority of them
7601 run commands on the target system over SSH.
7602 This section describes how you set up the environment to use these
7603 tests, run available tests, and write and add your own tests.
7604 </para>
7605
7606 <section id='enabling-tests'>
7607 <title>Enabling Tests</title>
7608
7609 <para>
7610 Depending on whether you are planning to run tests using
7611 QEMU or on the hardware, you have to take
7612 different steps to enable the tests.
7613 See the following subsections for information on how to
7614 enable both types of tests.
7615 </para>
7616
7617 <section id='qemu-image-enabling-tests'>
7618 <title>Enabling Runtime Tests on QEMU</title>
7619
7620 <para>
7621 In order to run tests, you need to do the following:
7622 <itemizedlist>
7623 <listitem><para><emphasis>Set up to avoid interaction
7624 with <filename>sudo</filename> for networking:</emphasis>
7625 To accomplish this, you must do one of the
7626 following:
7627 <itemizedlist>
7628 <listitem><para>Add
7629 <filename>NOPASSWD</filename> for your user
7630 in <filename>/etc/sudoers</filename> either for
7631 all commands or just for
7632 <filename>runqemu-ifup</filename>.
7633 You must provide the full path as that can
7634 change if you are using multiple clones of the
7635 source repository.
7636 <note>
7637 On some distributions, you also need to
7638 comment out "Defaults requiretty" in
7639 <filename>/etc/sudoers</filename>.
7640 </note></para></listitem>
7641 <listitem><para>Manually configure a tap interface
7642 for your system.</para></listitem>
7643 <listitem><para>Run as root the script in
7644 <filename>scripts/runqemu-gen-tapdevs</filename>,
7645 which should generate a list of tap devices.
7646 This is the option typically chosen for
7647 Autobuilder-type environments.
7648 </para></listitem>
7649 </itemizedlist></para></listitem>
7650 <listitem><para><emphasis>Set the
7651 <filename>DISPLAY</filename> variable:</emphasis>
7652 You need to set this variable so that you have an X
7653 server available (e.g. start
7654 <filename>vncserver</filename> for a headless machine).
7655 </para></listitem>
7656 <listitem><para><emphasis>Be sure your host's firewall
7657 accepts incoming connections from
7658 192.168.7.0/24:</emphasis>
7659 Some of the tests (in particular smart tests) start an
7660 HTTP server on a random high number port, which is
7661 used to serve files to the target.
7662 The smart module serves
7663 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
7664 smart channel commands. That means your host's firewall
7665 must accept incoming connections from 192.168.7.0/24,
7666 which is the default IP range used for tap devices
7667 by <filename>runqemu</filename>.</para></listitem>
7668 </itemizedlist>
7669 </para>
7670
7671 <para>
7672 Once you start running the tests, the following happens:
7673 <orderedlist>
7674 <listitem><para>A copy of the root filesystem is written
7675 to <filename>${WORKDIR}/testimage</filename>.
7676 </para></listitem>
7677 <listitem><para>The image is booted under QEMU using the
7678 standard <filename>runqemu</filename> script.
7679 </para></listitem>
7680 <listitem><para>A default timeout of 500 seconds occurs
7681 to allow for the boot process to reach the login prompt.
7682 You can change the timeout period by setting
7683 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
7684 in the <filename>local.conf</filename> file.
7685 </para></listitem>
7686 <listitem><para>Once the boot process is reached and the
7687 login prompt appears, the tests run.
7688 The full boot log is written to
7689 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
7690 </para></listitem>
7691 <listitem><para>Each test module loads in the order found
7692 in <filename>TEST_SUITES</filename>.
7693 You can find the full output of the commands run over
7694 SSH in
7695 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
7696 </para></listitem>
7697 <listitem><para>If no failures occur, the task running the
7698 tests ends successfully.
7699 You can find the output from the
7700 <filename>unittest</filename> in the task log at
7701 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
7702 </para></listitem>
7703 </orderedlist>
7704 </para>
7705 </section>
7706
7707 <section id='hardware-image-enabling-tests'>
7708 <title>Enabling Runtime Tests on Hardware</title>
7709
7710 <para>
7711 The OpenEmbedded build system can run tests on real
7712 hardware, and for certain devices it can also deploy
7713 the image to be tested onto the device beforehand.
7714 </para>
7715
7716 <para>
7717 For automated deployment, a "master image" is installed
7718 onto the hardware once as part of setup.
7719 Then, each time tests are to be run, the following
7720 occurs:
7721 <orderedlist>
7722 <listitem><para>The master image is booted into and
7723 used to write the image to be tested to
7724 a second partition.
7725 </para></listitem>
7726 <listitem><para>The device is then rebooted using an
7727 external script that you need to provide.
7728 </para></listitem>
7729 <listitem><para>The device boots into the image to be
7730 tested.
7731 </para></listitem>
7732 </orderedlist>
7733 </para>
7734
7735 <para>
7736 When running tests (independent of whether the image
7737 has been deployed automatically or not), the device is
7738 expected to be connected to a network on a
7739 pre-determined IP address.
7740 You can either use static IP addresses written into
7741 the image, or set the image to use DHCP and have your
7742 DHCP server on the test network assign a known IP address
7743 based on the MAC address of the device.
7744 </para>
7745
7746 <para>
7747 In order to run tests on hardware, you need to set
7748 <filename>TEST_TARGET</filename> to an appropriate value.
7749 For QEMU, you do not have to change anything, the default
7750 value is "QemuTarget".
7751 For running tests on hardware, the following options exist:
7752 <itemizedlist>
7753 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
7754 Choose "SimpleRemoteTarget" if you are going to
7755 run tests on a target system that is already
7756 running the image to be tested and is available
7757 on the network.
7758 You can use "SimpleRemoteTarget" in conjunction
7759 with either real hardware or an image running
7760 within a separately started QEMU or any
7761 other virtual machine manager.
7762 </para></listitem>
7763 <listitem><para><emphasis>"GummibootTarget":</emphasis>
7764 Choose "GummibootTarget" if your hardware is
7765 an EFI-based machine with
7766 <filename>gummiboot</filename> as bootloader and
7767 <filename>core-image-testmaster</filename>
7768 (or something similar) is installed.
7769 Also, your hardware under test must be in a
7770 DHCP-enabled network that gives it the same IP
7771 address for each reboot.</para>
7772 <para>If you choose "GummibootTarget", there are
7773 additional requirements and considerations.
7774 See the
7775 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
7776 section, which follows, for more information.
7777 </para></listitem>
7778 <listitem><para><emphasis>"BeagleBoneTarget":</emphasis>
7779 Choose "BeagleBoneTarget" if you are deploying
7780 images and running tests on the BeagleBone
7781 "Black" or original "White" hardware.
7782 For information on how to use these tests, see the
7783 comments at the top of the BeagleBoneTarget
7784 <filename>meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py</filename>
7785 file.
7786 </para></listitem>
7787 <listitem><para><emphasis>"EdgeRouterTarget":</emphasis>
7788 Choose "EdgeRouterTarget" is you are deploying
7789 images and running tests on the Ubiquiti Networks
7790 EdgeRouter Lite.
7791 For information on how to use these tests, see the
7792 comments at the top of the EdgeRouterTarget
7793 <filename>meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py</filename>
7794 file.
7795 </para></listitem>
7796 <listitem><para><emphasis>"GrubTarget":</emphasis>
7797 Choose the "supports deploying images and running
7798 tests on any generic PC that boots using GRUB.
7799 For information on how to use these tests, see the
7800 comments at the top of the GrubTarget
7801 <filename>meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py</filename>
7802 file.
7803 </para></listitem>
7804 <listitem><para><emphasis>"<replaceable>your-target</replaceable>":</emphasis>
7805 Create your own custom target if you want to run
7806 tests when you are deploying images and running
7807 tests on a custom machine within your BSP layer.
7808 To do this, you need to add a Python unit that
7809 defines the target class under
7810 <filename>lib/oeqa/controllers/</filename> within
7811 your layer.
7812 You must also provide an empty
7813 <filename>__init__.py</filename>.
7814 For examples, see files in
7815 <filename>meta-yocto-bsp/lib/oeqa/controllers/</filename>.
7816 </para></listitem>
7817 </itemizedlist>
7818 </para>
7819 </section>
7820
7821 <section id='selecting-gummiboottarget'>
7822 <title>Selecting GummibootTarget</title>
7823
7824 <para>
7825 If you did not set <filename>TEST_TARGET</filename> to
7826 "GummibootTarget", then you do not need any information
7827 in this section.
7828 You can skip down to the
7829 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
7830 section.
7831 </para>
7832
7833 <para>
7834 If you did set <filename>TEST_TARGET</filename> to
7835 "GummibootTarget", you also need to perform a one-time
7836 setup of your master image by doing the following:
7837 <orderedlist>
7838 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
7839 Be sure that <filename>EFI_PROVIDER</filename>
7840 is as follows:
7841 <literallayout class='monospaced'>
7842 EFI_PROVIDER = "gummiboot"
7843 </literallayout>
7844 </para></listitem>
7845 <listitem><para><emphasis>Build the master image:</emphasis>
7846 Build the <filename>core-image-testmaster</filename>
7847 image.
7848 The <filename>core-image-testmaster</filename>
7849 recipe is provided as an example for a
7850 "master" image and you can customize the image
7851 recipe as you would any other recipe.
7852 </para>
7853 <para>Here are the image recipe requirements:
7854 <itemizedlist>
7855 <listitem><para>Inherits
7856 <filename>core-image</filename>
7857 so that kernel modules are installed.
7858 </para></listitem>
7859 <listitem><para>Installs normal linux utilities
7860 not busybox ones (e.g.
7861 <filename>bash</filename>,
7862 <filename>coreutils</filename>,
7863 <filename>tar</filename>,
7864 <filename>gzip</filename>, and
7865 <filename>kmod</filename>).
7866 </para></listitem>
7867 <listitem><para>Uses a custom
7868 Initial RAM Disk (initramfs) image with a
7869 custom installer.
7870 A normal image that you can install usually
7871 creates a single rootfs partition.
7872 This image uses another installer that
7873 creates a specific partition layout.
7874 Not all Board Support Packages (BSPs)
7875 can use an installer.
7876 For such cases, you need to manually create
7877 the following partition layout on the
7878 target:
7879 <itemizedlist>
7880 <listitem><para>First partition mounted
7881 under <filename>/boot</filename>,
7882 labeled "boot".
7883 </para></listitem>
7884 <listitem><para>The main rootfs
7885 partition where this image gets
7886 installed, which is mounted under
7887 <filename>/</filename>.
7888 </para></listitem>
7889 <listitem><para>Another partition
7890 labeled "testrootfs" where test
7891 images get deployed.
7892 </para></listitem>
7893 </itemizedlist>
7894 </para></listitem>
7895 </itemizedlist>
7896 </para></listitem>
7897 <listitem><para><emphasis>Install image:</emphasis>
7898 Install the image that you just built on the target
7899 system.
7900 </para></listitem>
7901 </orderedlist>
7902 </para>
7903
7904 <para>
7905 The final thing you need to do when setting
7906 <filename>TEST_TARGET</filename> to "GummibootTarget" is
7907 to set up the test image:
7908 <orderedlist>
7909 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
7910 Make sure you have the following statements in
7911 your <filename>local.conf</filename> file:
7912 <literallayout class='monospaced'>
7913 IMAGE_FSTYPES += "tar.gz"
7914 INHERIT += "testimage"
7915 TEST_TARGET = "GummibootTarget"
7916 TEST_TARGET_IP = "192.168.2.3"
7917 </literallayout>
7918 </para></listitem>
7919 <listitem><para><emphasis>Build your test image:</emphasis>
7920 Use BitBake to build the image:
7921 <literallayout class='monospaced'>
7922 $ bitbake core-image-sato
7923 </literallayout>
7924 </para></listitem>
7925 </orderedlist>
7926 </para>
7927 </section>
7928
7929 <section id='power-control'>
7930 <title>Power Control</title>
7931
7932 <para>
7933 For most hardware targets other than SimpleRemoteTarget,
7934 you can control power:
7935 <itemizedlist>
7936 <listitem><para>
7937 You can use
7938 <filename>TEST_POWERCONTROL_CMD</filename>
7939 together with
7940 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
7941 as a command that runs on the host and does power
7942 cycling.
7943 The test code passes one argument to that command:
7944 off, on or cycle (off then on).
7945 Here is an example that could appear in your
7946 <filename>local.conf</filename> file:
7947 <literallayout class='monospaced'>
7948 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
7949 </literallayout>
7950 In this example, the expect script does the
7951 following:
7952 <literallayout class='monospaced'>
7953 ssh test@10.11.12.1 "pyctl nuc1 <replaceable>arg</replaceable>"
7954 </literallayout>
7955 It then runs a Python script that controls power
7956 for a label called <filename>nuc1</filename>.
7957 <note>
7958 You need to customize
7959 <filename>TEST_POWERCONTROL_CMD</filename>
7960 and
7961 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
7962 for your own setup.
7963 The one requirement is that it accepts
7964 "on", "off", and "cycle" as the last argument.
7965 </note>
7966 </para></listitem>
7967 <listitem><para>
7968 When no command is defined, it connects to the
7969 device over SSH and uses the classic reboot command
7970 to reboot the device.
7971 Classic reboot is fine as long as the machine
7972 actually reboots (i.e. the SSH test has not
7973 failed).
7974 It is useful for scenarios where you have a simple
7975 setup, typically with a single board, and where
7976 some manual interaction is okay from time to time.
7977 </para></listitem>
7978 </itemizedlist>
7979 If you have no hardware to automatically perform power
7980 control but still wish to experiment with automated
7981 hardware testing, you can use the dialog-power-control
7982 script that shows a dialog prompting you to perform the
7983 required power action.
7984 This script requires either KDialog or Zenity to be
7985 installed.
7986 To use this script, set the
7987 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
7988 variable as follows:
7989 <literallayout class='monospaced'>
7990 TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control"
7991 </literallayout>
7992 </para>
7993 </section>
7994
7995 <section id='serial-console-connection'>
7996 <title>Serial Console Connection</title>
7997
7998 <para>
7999 For test target classes requiring a serial console
8000 to interact with the bootloader (e.g. BeagleBoneTarget,
8001 EdgeRouterTarget, and GrubTarget), you need to
8002 specify a command to use to connect to the serial console
8003 of the target machine by using the
8004 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
8005 variable and optionally the
8006 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink>
8007 variable.
8008 </para>
8009
8010 <para>
8011 These cases could be a serial terminal program if the
8012 machine is connected to a local serial port, or a
8013 <filename>telnet</filename> or
8014 <filename>ssh</filename> command connecting to a remote
8015 console server.
8016 Regardless of the case, the command simply needs to
8017 connect to the serial console and forward that connection
8018 to standard input and output as any normal terminal
8019 program does.
8020 For example, to use the picocom terminal program on
8021 serial device <filename>/dev/ttyUSB0</filename>
8022 at 115200bps, you would set the variable as follows:
8023 <literallayout class='monospaced'>
8024 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
8025 </literallayout>
8026 For local devices where the serial port device disappears
8027 when the device reboots, an additional "serdevtry" wrapper
8028 script is provided.
8029 To use this wrapper, simply prefix the terminal command
8030 with
8031 <filename>${COREBASE}/scripts/contrib/serdevtry</filename>:
8032 <literallayout class='monospaced'>
8033 TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b
8034115200 /dev/ttyUSB0"
8035 </literallayout>
8036 </para>
8037 </section>
8038 </section>
8039
8040 <section id="qemu-image-running-tests">
8041 <title>Running Tests</title>
8042
8043 <para>
8044 You can start the tests automatically or manually:
8045 <itemizedlist>
8046 <listitem><para><emphasis>Automatically running tests:</emphasis>
8047 To run the tests automatically after the
8048 OpenEmbedded build system successfully creates an image,
8049 first set the
8050 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
8051 variable to "1" in your <filename>local.conf</filename>
8052 file in the
8053 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
8054 <literallayout class='monospaced'>
8055 TEST_IMAGE = "1"
8056 </literallayout>
8057 Next, build your image.
8058 If the image successfully builds, the tests will be
8059 run:
8060 <literallayout class='monospaced'>
8061 bitbake core-image-sato
8062 </literallayout></para></listitem>
8063 <listitem><para><emphasis>Manually running tests:</emphasis>
8064 To manually run the tests, first globally inherit the
8065 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
8066 class by editing your <filename>local.conf</filename>
8067 file:
8068 <literallayout class='monospaced'>
8069 INHERIT += "testimage"
8070 </literallayout>
8071 Next, use BitBake to run the tests:
8072 <literallayout class='monospaced'>
8073 bitbake -c testimage <replaceable>image</replaceable>
8074 </literallayout></para></listitem>
8075 </itemizedlist>
8076 </para>
8077
8078 <para>
8079 All test files reside in
8080 <filename>meta/lib/oeqa/runtime</filename> in the
8081 <link linkend='source-directory'>Source Directory</link>.
8082 A test name maps directly to a Python module.
8083 Each test module may contain a number of individual tests.
8084 Tests are usually grouped together by the area
8085 tested (e.g tests for systemd reside in
8086 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
8087 </para>
8088
8089 <para>
8090 You can add tests to any layer provided you place them in the
8091 proper area and you extend
8092 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
8093 in the <filename>local.conf</filename> file as normal.
8094 Be sure that tests reside in
8095 <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>.
8096 <note>
8097 Be sure that module names do not collide with module names
8098 used in the default set of test modules in
8099 <filename>meta/lib/oeqa/runtime</filename>.
8100 </note>
8101 </para>
8102
8103 <para>
8104 You can change the set of tests run by appending or overriding
8105 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
8106 variable in <filename>local.conf</filename>.
8107 Each name in <filename>TEST_SUITES</filename> represents a
8108 required test for the image.
8109 Test modules named within <filename>TEST_SUITES</filename>
8110 cannot be skipped even if a test is not suitable for an image
8111 (e.g. running the RPM tests on an image without
8112 <filename>rpm</filename>).
8113 Appending "auto" to <filename>TEST_SUITES</filename> causes the
8114 build system to try to run all tests that are suitable for the
8115 image (i.e. each test module may elect to skip itself).
8116 </para>
8117
8118 <para>
8119 The order you list tests in <filename>TEST_SUITES</filename>
8120 is important and influences test dependencies.
8121 Consequently, tests that depend on other tests should be added
8122 after the test on which they depend.
8123 For example, since the <filename>ssh</filename> test
8124 depends on the
8125 <filename>ping</filename> test, "ssh" needs to come after
8126 "ping" in the list.
8127 The test class provides no re-ordering or dependency handling.
8128 <note>
8129 Each module can have multiple classes with multiple test
8130 methods.
8131 And, Python <filename>unittest</filename> rules apply.
8132 </note>
8133 </para>
8134
8135 <para>
8136 Here are some things to keep in mind when running tests:
8137 <itemizedlist>
8138 <listitem><para>The default tests for the image are defined
8139 as:
8140 <literallayout class='monospaced'>
8141 DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
8142 </literallayout></para></listitem>
8143 <listitem><para>Add your own test to the list of the
8144 by using the following:
8145 <literallayout class='monospaced'>
8146 TEST_SUITES_append = " mytest"
8147 </literallayout></para></listitem>
8148 <listitem><para>Run a specific list of tests as follows:
8149 <literallayout class='monospaced'>
8150 TEST_SUITES = "test1 test2 test3"
8151 </literallayout>
8152 Remember, order is important.
8153 Be sure to place a test that is dependent on another test
8154 later in the order.</para></listitem>
8155 </itemizedlist>
8156 </para>
8157 </section>
8158
8159 <section id="exporting-tests">
8160 <title>Exporting Tests</title>
8161
8162 <para>
8163 You can export tests so that they can run independently of
8164 the build system.
8165 Exporting tests is required if you want to be able to hand
8166 the test execution off to a scheduler.
8167 You can only export tests that are defined in
8168 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
8169 </para>
8170
8171 <para>
8172 If your image is already built, make sure the following are set
8173 in your <filename>local.conf</filename> file.
8174 Be sure to provide the IP address you need:
8175 <literallayout class='monospaced'>
8176 TEST_EXPORT_ONLY = "1"
8177 TEST_TARGET = "simpleremote"
8178 TEST_TARGET_IP = "192.168.7.2"
8179 TEST_SERVER_IP = "192.168.7.1"
8180 </literallayout>
8181 You can then export the tests with the following:
8182 <literallayout class='monospaced'>
8183 $ bitbake core-image-sato -c testimage
8184 </literallayout>
8185 Exporting the tests places them in the
8186 <link linkend='build-directory'>Build Directory</link> in
8187 <filename>tmp/testimage/core-image-sato</filename>, which
8188 is controlled by the
8189 <filename>TEST_EXPORT_DIR</filename> variable.
8190 </para>
8191
8192 <para>
8193 You can now run the tests outside of the build environment:
8194 <literallayout class='monospaced'>
8195 $ cd tmp/testimage/core-image-sato
8196 $ ./runexported.py testdata.json
8197 </literallayout>
8198 <note>
8199 This "export" feature does not deploy or boot the target
8200 image.
8201 Your target (be it a Qemu or hardware one)
8202 has to already be up and running when you call
8203 <filename>runexported.py</filename>
8204 </note>
8205 </para>
8206
8207 <para>
8208 The exported data (i.e. <filename>testdata.json</filename>)
8209 contains paths to the Build Directory.
8210 Thus, the contents of the directory can be moved
8211 to another machine as long as you update some paths in the
8212 JSON.
8213 Usually, you only care about the
8214 <filename>${DEPLOY_DIR}/rpm</filename> directory
8215 (assuming the RPM and Smart tests are enabled).
8216 Consequently, running the tests on other machine
8217 means that you have to move the contents and call
8218 <filename>runexported.py</filename> with
8219 "&dash;&dash;deploy-dir <replaceable>path</replaceable>" as
8220 follows:
8221 <literallayout class='monospaced'>
8222 ./runexported.py &dash;&dash;deploy-dir /new/path/on/this/machine testdata.json
8223 </literallayout>
8224 <filename>runexported.py</filename> accepts other arguments
8225 as well as described using <filename>&dash;&dash;help</filename>.
8226 </para>
8227 </section>
8228
8229 <section id="qemu-image-writing-new-tests">
8230 <title>Writing New Tests</title>
8231
8232 <para>
8233 As mentioned previously, all new test files need to be in the
8234 proper place for the build system to find them.
8235 New tests for additional functionality outside of the core
8236 should be added to the layer that adds the functionality, in
8237 <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>
8238 (as long as
8239 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
8240 is extended in the layer's
8241 <filename>layer.conf</filename> file as normal).
8242 Just remember that filenames need to map directly to test
8243 (module) names and that you do not use module names that
8244 collide with existing core tests.
8245 </para>
8246
8247 <para>
8248 To create a new test, start by copying an existing module
8249 (e.g. <filename>syslog.py</filename> or
8250 <filename>gcc.py</filename> are good ones to use).
8251 Test modules can use code from
8252 <filename>meta/lib/oeqa/utils</filename>, which are helper
8253 classes.
8254 </para>
8255
8256 <note>
8257 Structure shell commands such that you rely on them and they
8258 return a single code for success.
8259 Be aware that sometimes you will need to parse the output.
8260 See the <filename>df.py</filename> and
8261 <filename>date.py</filename> modules for examples.
8262 </note>
8263
8264 <para>
8265 You will notice that all test classes inherit
8266 <filename>oeRuntimeTest</filename>, which is found in
8267 <filename>meta/lib/oetest.py</filename>.
8268 This base class offers some helper attributes, which are
8269 described in the following sections:
8270 </para>
8271
8272 <section id='qemu-image-writing-tests-class-methods'>
8273 <title>Class Methods</title>
8274
8275 <para>
8276 Class methods are as follows:
8277 <itemizedlist>
8278 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
8279 Returns "True" if <filename>pkg</filename> is in the
8280 installed package list of the image, which is based
8281 on the manifest file that is generated during the
8282 <filename>do_rootfs</filename> task.
8283 </para></listitem>
8284 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
8285 Returns "True" if the feature is in
8286 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
8287 or
8288 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
8289 </para></listitem>
8290 </itemizedlist>
8291 </para>
8292 </section>
8293
8294 <section id='qemu-image-writing-tests-class-attributes'>
8295 <title>Class Attributes</title>
8296
8297 <para>
8298 Class attributes are as follows:
8299 <itemizedlist>
8300 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
8301 Equals "ps -ef" if <filename>procps</filename> is
8302 installed in the image.
8303 Otherwise, <filename>pscmd</filename> equals
8304 "ps" (busybox).
8305 </para></listitem>
8306 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
8307 The called text context, which gives access to the
8308 following attributes:
8309 <itemizedlist>
8310 <listitem><para><emphasis><filename>d</filename>:</emphasis>
8311 The BitBake datastore, which allows you to
8312 use stuff such as
8313 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
8314 </para></listitem>
8315 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
8316 Used internally.
8317 The tests do not need these.
8318 </para></listitem>
8319 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
8320 The absolute path to
8321 <filename>meta/lib/oeqa/runtime/files</filename>,
8322 which contains helper files for tests meant
8323 for copying on the target such as small
8324 files written in C for compilation.
8325 </para></listitem>
8326 <listitem><para><emphasis><filename>target</filename>:</emphasis>
8327 The target controller object used to deploy
8328 and start an image on a particular target
8329 (e.g. QemuTarget, SimpleRemote, and
8330 GummibootTarget).
8331 Tests usually use the following:
8332 <itemizedlist>
8333 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
8334 The target's IP address.
8335 </para></listitem>
8336 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
8337 The host's IP address, which is
8338 usually used by the "smart" test
8339 suite.
8340 </para></listitem>
8341 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
8342 The single, most used method.
8343 This command is a wrapper for:
8344 <filename>ssh root@host "cmd"</filename>.
8345 The command returns a tuple:
8346 (status, output), which are what
8347 their names imply - the return code
8348 of "cmd" and whatever output
8349 it produces.
8350 The optional timeout argument
8351 represents the number of seconds the
8352 test should wait for "cmd" to
8353 return.
8354 If the argument is "None", the
8355 test uses the default instance's
8356 timeout period, which is 300
8357 seconds.
8358 If the argument is "0", the test
8359 runs until the command returns.
8360 </para></listitem>
8361 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
8362 <filename>scp localpath root@ip:remotepath</filename>.
8363 </para></listitem>
8364 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
8365 <filename>scp root@host:remotepath localpath</filename>.
8366 </para></listitem>
8367 </itemizedlist></para></listitem>
8368 </itemizedlist></para></listitem>
8369 </itemizedlist>
8370 </para>
8371 </section>
8372
8373 <section id='qemu-image-writing-tests-instance-attributes'>
8374 <title>Instance Attributes</title>
8375
8376 <para>
8377 A single instance attribute exists, which is
8378 <filename>target</filename>.
8379 The <filename>target</filename> instance attribute is
8380 identical to the class attribute of the same name, which
8381 is described in the previous section.
8382 This attribute exists as both an instance and class
8383 attribute so tests can use
8384 <filename>self.target.run(cmd)</filename> in instance
8385 methods instead of
8386 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
8387 </para>
8388 </section>
8389 </section>
8390 </section>
8391
8392 <section id="platdev-gdb-remotedebug">
8393 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
8394
8395 <para>
8396 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
8397 It also allows you to perform post-mortem style analysis of program crashes.
8398 GDB is available as a package within the Yocto Project and is
8399 installed in SDK images by default.
8400 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
8401 in the Yocto Project Reference Manual for a description of these images.
8402 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
8403 </para>
8404
8405 <tip>
8406 For best results, install debug (<filename>-dbg</filename>) packages
8407 for the applications you are going to debug.
8408 Doing so makes extra debug symbols available that give you more
8409 meaningful output.
8410 </tip>
8411
8412 <para>
8413 Sometimes, due to memory or disk space constraints, it is not possible
8414 to use GDB directly on the remote target to debug applications.
8415 These constraints arise because GDB needs to load the debugging information and the
8416 binaries of the process being debugged.
8417 Additionally, GDB needs to perform many computations to locate information such as function
8418 names, variable names and values, stack traces and so forth - even before starting the
8419 debugging process.
8420 These extra computations place more load on the target system and can alter the
8421 characteristics of the program being debugged.
8422 </para>
8423
8424 <para>
8425 To help get past the previously mentioned constraints, you can use Gdbserver.
8426 Gdbserver runs on the remote target and does not load any debugging information
8427 from the debugged process.
8428 Instead, a GDB instance processes the debugging information that is run on a
8429 remote computer - the host GDB.
8430 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
8431 program, as well as read or write memory regions of that debugged program.
8432 All the debugging information loaded and processed as well
8433 as all the heavy debugging is done by the host GDB.
8434 Offloading these processes gives the Gdbserver running on the target a chance to remain
8435 small and fast.
8436 <note>
8437 By default, source files are part of the
8438 <filename>*-dbg</filename> packages in order to enable GDB
8439 to show source lines in its output.
8440 You can save further space on the target by setting the
8441 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink>
8442 variable to "debug-without-src" so that these packages do not
8443 include the source files.
8444 </note>
8445 </para>
8446
8447 <para>
8448 Because the host GDB is responsible for loading the debugging information and
8449 for doing the necessary processing to make actual debugging happen,
8450 you have to make sure the host can access the unstripped binaries complete
8451 with their debugging information and also be sure the target is compiled with no optimizations.
8452 The host GDB must also have local access to all the libraries used by the
8453 debugged program.
8454 Because Gdbserver does not need any local debugging information, the binaries on
8455 the remote target can remain stripped.
8456 However, the binaries must also be compiled without optimization
8457 so they match the host's binaries.
8458 </para>
8459
8460 <para>
8461 To remain consistent with GDB documentation and terminology, the binary being debugged
8462 on the remote target machine is referred to as the "inferior" binary.
8463 For documentation on GDB see the
8464 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
8465 </para>
8466
8467 <para>
8468 The remainder of this section describes the steps you need to take
8469 to debug using the GNU project debugger.
8470 </para>
8471
8472 <section id='platdev-gdb-remotedebug-setup'>
8473 <title>Set Up the Cross-Development Debugging Environment</title>
8474
8475 <para>
8476 Before you can initiate a remote debugging session, you need
8477 to be sure you have set up the cross-development environment,
8478 toolchain, and sysroot.
8479 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
8480 chapter of the Yocto Project Application Developer's Guide
8481 describes this process.
8482 Be sure you have read that chapter and have set up
8483 your environment.
8484 </para>
8485 </section>
8486
8487 <section id="platdev-gdb-remotedebug-launch-gdbserver">
8488 <title>Launch Gdbserver on the Target</title>
8489
8490 <para>
8491 Make sure Gdbserver is installed on the target.
8492 If it is not, install the package
8493 <filename>gdbserver</filename>, which needs the
8494 <filename>libthread-db1</filename> package.
8495 </para>
8496
8497 <para>
8498 Here is an example, that when entered from the host,
8499 connects to the target and launches Gdbserver in order to
8500 "debug" a binary named <filename>helloworld</filename>:
8501 <literallayout class='monospaced'>
8502 $ gdbserver localhost:2345 /usr/bin/helloworld
8503 </literallayout>
8504 Gdbserver should now be listening on port 2345 for debugging
8505 commands coming from a remote GDB process that is running on
8506 the host computer.
8507 Communication between Gdbserver and the host GDB are done
8508 using TCP.
8509 To use other communication protocols, please refer to the
8510 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
8511 </para>
8512 </section>
8513
8514 <section id="platdev-gdb-remotedebug-launch-gdb">
8515 <title>Launch GDB on the Host Computer</title>
8516
8517 <para>
8518 Running GDB on the host computer takes a number of stages, which
8519 this section describes.
8520 </para>
8521
8522 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
8523 <title>Build the Cross-GDB Package</title>
8524 <para>
8525 A suitable GDB cross-binary is required that runs on your
8526 host computer but also knows about the the ABI of the
8527 remote target.
8528 You can get this binary from the
8529 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
8530 Here is an example where the toolchain has been installed
8531 in the default directory
8532 <filename>/opt/poky/&DISTRO;</filename>:
8533 <literallayout class='monospaced'>
8534 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
8535 </literallayout>
8536 where <filename>arm</filename> is the target architecture
8537 and <filename>linux-gnueabi</filename> is the target ABI.
8538 </para>
8539
8540 <para>
8541 Alternatively, you can use BitBake to build the
8542 <filename>gdb-cross</filename> binary.
8543 Here is an example:
8544 <literallayout class='monospaced'>
8545 $ bitbake gdb-cross
8546 </literallayout>
8547 Once the binary is built, you can find it here:
8548 <literallayout class='monospaced'>
8549 tmp/sysroots/<replaceable>host-arch</replaceable>/usr/bin/<replaceable>target-platform</replaceable>/<replaceable>target-abi</replaceable>-gdb
8550 </literallayout>
8551 </para>
8552 </section>
8553
8554 <section id='create-the-gdb-initialization-file'>
8555 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
8556
8557 <para>
8558 Aside from the GDB cross-binary, you also need a GDB
8559 initialization file in the same top directory in which
8560 your binary resides.
8561 When you start GDB on your host development system, GDB
8562 finds this initialization file and executes all the
8563 commands within.
8564 For information on the <filename>.gdbinit</filename>, see
8565 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
8566 which is maintained by
8567 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
8568 </para>
8569
8570 <para>
8571 You need to add a statement in the
8572 <filename>~/.gdbinit</filename> file that points to your
8573 root filesystem.
8574 Here is an example that points to the root filesystem for
8575 an ARM-based target device:
8576 <literallayout class='monospaced'>
8577 set sysroot ~/sysroot_arm
8578 </literallayout>
8579 </para>
8580 </section>
8581
8582 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
8583 <title>Launch the Host GDB</title>
8584
8585 <para>
8586 Before launching the host GDB, you need to be sure
8587 you have sourced the cross-debugging environment script,
8588 which if you installed the root filesystem in the default
8589 location is at <filename>/opt/poky/&DISTRO;</filename>
8590 and begins with the string "environment-setup".
8591 For more information, see the
8592 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
8593 section in the Yocto Project Application Developer's
8594 Guide.
8595 </para>
8596
8597 <para>
8598 Finally, switch to the directory where the binary resides
8599 and run the <filename>cross-gdb</filename> binary.
8600 Provide the binary file you are going to debug.
8601 For example, the following command continues with the
8602 example used in the previous section by loading
8603 the <filename>helloworld</filename> binary as well as the
8604 debugging information:
8605 <literallayout class='monospaced'>
8606 $ arm-poky-linux-gnuabi-gdb helloworld
8607 </literallayout>
8608 The commands in your <filename>.gdbinit</filename> execute
8609 and the GDB prompt appears.
8610 </para>
8611 </section>
8612 </section>
8613
8614 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
8615 <title>Connect to the Remote GDB Server</title>
8616
8617 <para>
8618 From the target, you need to connect to the remote GDB
8619 server that is running on the host.
8620 You need to specify the remote host and port.
8621 Here is the command continuing with the example:
8622 <literallayout class='monospaced'>
8623 target remote 192.168.7.2:2345
8624 </literallayout>
8625 </para>
8626 </section>
8627
8628 <section id="platdev-gdb-remotedebug-launch-gdb-using">
8629 <title>Use the Debugger</title>
8630
8631 <para>
8632 You can now proceed with debugging as normal - as if you were debugging
8633 on the local machine.
8634 For example, to instruct GDB to break in the "main" function and then
8635 continue with execution of the inferior binary use the following commands
8636 from within GDB:
8637 <literallayout class='monospaced'>
8638 (gdb) break main
8639 (gdb) continue
8640 </literallayout>
8641 </para>
8642
8643 <para>
8644 For more information about using GDB, see the project's online documentation at
8645 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
8646 </para>
8647 </section>
8648 </section>
8649
8650 <section id='debugging-parallel-make-races'>
8651 <title>Debugging Parallel Make Races</title>
8652
8653 <para>
8654 A parallel <filename>make</filename> race occurs when the build
8655 consists of several parts that are run simultaneously and
8656 a situation occurs when the output or result of one
8657 part is not ready for use with a different part of the build that
8658 depends on that output.
8659 Parallel make races are annoying and can sometimes be difficult
8660 to reproduce and fix.
8661 However, some simple tips and tricks exist that can help
8662 you debug and fix them.
8663 This section presents a real-world example of an error encountered
8664 on the Yocto Project autobuilder and the process used to fix it.
8665 </para>
8666
8667 <section id='the-failure'>
8668 <title>The Failure</title>
8669
8670 <para>
8671 For this example, assume that you are building an image that
8672 depends on the "neard" package.
8673 And, during the build, BitBake runs into problems and
8674 creates the following output.
8675 <note>
8676 This example log file has longer lines artificially
8677 broken to make the listing easier to read.
8678 </note>
8679 If you examine the output or the log file, you see the
8680 failure during <filename>make</filename>:
8681 <literallayout class='monospaced'>
8682 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
8683 | DEBUG: Executing shell function do_compile
8684 | NOTE: make -j 16
8685 | make &dash;&dash;no-print-directory all-am
8686 | /bin/mkdir -p include/near
8687 | /bin/mkdir -p include/near
8688 | /bin/mkdir -p include/near
8689 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8690 0.14-r0/neard-0.14/include/types.h include/near/types.h
8691 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8692 0.14-r0/neard-0.14/include/log.h include/near/log.h
8693 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8694 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h
8695 | /bin/mkdir -p include/near
8696 | /bin/mkdir -p include/near
8697 | /bin/mkdir -p include/near
8698 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8699 0.14-r0/neard-0.14/include/tag.h include/near/tag.h
8700 | /bin/mkdir -p include/near
8701 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8702 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h
8703 | /bin/mkdir -p include/near
8704 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8705 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h
8706 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8707 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h
8708 | /bin/mkdir -p include/near
8709 | /bin/mkdir -p include/near
8710 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8711 0.14-r0/neard-0.14/include/setting.h include/near/setting.h
8712 | /bin/mkdir -p include/near
8713 | /bin/mkdir -p include/near
8714 | /bin/mkdir -p include/near
8715 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8716 0.14-r0/neard-0.14/include/device.h include/near/device.h
8717 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8718 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h
8719 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8720 0.14-r0/neard-0.14/include/snep.h include/near/snep.h
8721 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8722 0.14-r0/neard-0.14/include/version.h include/near/version.h
8723 | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/
8724 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h
8725 | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h
8726 | i586-poky-linux-gcc -m32 -march=i586 &dash;&dash;sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/
8727 build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/
8728 yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0
8729 -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/
8730 lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/
8731 tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/
8732 nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/
8733 yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3
8734 -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\"
8735 -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c
8736 -o tools/snep-send.o tools/snep-send.c
8737 | In file included from tools/snep-send.c:16:0:
8738 | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
8739 | #include &lt;near/dbus.h&gt;
8740 | ^
8741 | compilation terminated.
8742 | make[1]: *** [tools/snep-send.o] Error 1
8743 | make[1]: *** Waiting for unfinished jobs....
8744 | make: *** [all] Error 2
8745 | ERROR: oe_runmake failed
8746 </literallayout>
8747 </para>
8748 </section>
8749
8750 <section id='reproducing-the-error'>
8751 <title>Reproducing the Error</title>
8752
8753 <para>
8754 Because race conditions are intermittent, they do not
8755 manifest themselves every time you do the build.
8756 In fact, most times the build will complete without problems
8757 even though the potential race condition exists.
8758 Thus, once the error surfaces, you need a way to reproduce it.
8759 </para>
8760
8761 <para>
8762 In this example, compiling the "neard" package is causing the
8763 problem.
8764 So the first thing to do is build "neard" locally.
8765 Before you start the build, set the
8766 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
8767 variable in your <filename>local.conf</filename> file to
8768 a high number (e.g. "-j 20").
8769 Using a high value for <filename>PARALLEL_MAKE</filename>
8770 increases the chances of the race condition showing up:
8771 <literallayout class='monospaced'>
8772 $ bitbake neard
8773 </literallayout>
8774 </para>
8775
8776 <para>
8777 Once the local build for "neard" completes, start a
8778 <filename>devshell</filename> build:
8779 <literallayout class='monospaced'>
8780 $ bitbake neard -c devshell
8781 </literallayout>
8782 For information on how to use a
8783 <filename>devshell</filename>, see the
8784 "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
8785 section.
8786 </para>
8787
8788 <para>
8789 In the <filename>devshell</filename>, do the following:
8790 <literallayout class='monospaced'>
8791 $ make clean
8792 $ make tools/snep-send.o
8793 </literallayout>
8794 The <filename>devshell</filename> commands cause the failure
8795 to clearly be visible.
8796 In this case, a missing dependency exists for the "neard"
8797 Makefile target.
8798 Here is some abbreviated, sample output with the
8799 missing dependency clearly visible at the end:
8800 <literallayout class='monospaced'>
8801 i586-poky-linux-gcc -m32 -march=i586 &dash;&dash;sysroot=/home/scott-lenovo/......
8802 .
8803 .
8804 .
8805 tools/snep-send.c
8806 In file included from tools/snep-send.c:16:0:
8807 tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory
8808 #include &lt;near/dbus.h&gt;
8809 ^
8810 compilation terminated.
8811 make: *** [tools/snep-send.o] Error 1
8812 $
8813 </literallayout>
8814 </para>
8815 </section>
8816
8817 <section id='creating-a-patch-for-the-fix'>
8818 <title>Creating a Patch for the Fix</title>
8819
8820 <para>
8821 Because there is a missing dependency for the Makefile
8822 target, you need to patch the
8823 <filename>Makefile.am</filename> file, which is generated
8824 from <filename>Makefile.in</filename>.
8825 You can use Quilt to create the patch:
8826 <literallayout class='monospaced'>
8827 $ quilt new parallelmake.patch
8828 Patch patches/parallelmake.patch is now on top
8829 $ quilt add Makefile.am
8830 File Makefile.am added to patch patches/parallelmake.patch
8831 </literallayout>
8832 For more information on using Quilt, see the
8833 "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>"
8834 section.
8835 </para>
8836
8837 <para>
8838 At this point you need to make the edits to
8839 <filename>Makefile.am</filename> to add the missing
8840 dependency.
8841 For our example, you have to add the following line
8842 to the file:
8843 <literallayout class='monospaced'>
8844 tools/snep-send.$(OBJEXT): include/near/dbus.h
8845 </literallayout>
8846 </para>
8847
8848 <para>
8849 Once you have edited the file, use the
8850 <filename>refresh</filename> command to create the patch:
8851 <literallayout class='monospaced'>
8852 $ quilt refresh
8853 Refreshed patch patches/parallelmake.patch
8854 </literallayout>
8855 Once the patch file exists, you need to add it back to the
8856 originating recipe folder.
8857 Here is an example assuming a top-level
8858 <link linkend='source-directory'>Source Directory</link>
8859 named <filename>poky</filename>:
8860 <literallayout class='monospaced'>
8861 $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
8862 </literallayout>
8863 The final thing you need to do to implement the fix in the
8864 build is to update the "neard" recipe (i.e.
8865 <filename>neard-0.14.bb</filename>) so that the
8866 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
8867 statement includes the patch file.
8868 The recipe file is in the folder above the patch.
8869 Here is what the edited <filename>SRC_URI</filename>
8870 statement would look like:
8871 <literallayout class='monospaced'>
8872 SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
8873 file://neard.in \
8874 file://neard.service.in \
8875 file://parallelmake.patch \
8876 "
8877 </literallayout>
8878 </para>
8879
8880 <para>
8881 With the patch complete and moved to the correct folder and
8882 the <filename>SRC_URI</filename> statement updated, you can
8883 exit the <filename>devshell</filename>:
8884 <literallayout class='monospaced'>
8885 $ exit
8886 </literallayout>
8887 </para>
8888 </section>
8889
8890 <section id='testing-the-build'>
8891 <title>Testing the Build</title>
8892
8893 <para>
8894 With everything in place, you can get back to trying the
8895 build again locally:
8896 <literallayout class='monospaced'>
8897 $ bitbake neard
8898 </literallayout>
8899 This build should succeed.
8900 </para>
8901
8902 <para>
8903 Now you can open up a <filename>devshell</filename> again
8904 and repeat the clean and make operations as follows:
8905 <literallayout class='monospaced'>
8906 $ bitbake neard -c devshell
8907 $ make clean
8908 $ make tools/snep-send.o
8909 </literallayout>
8910 The build should work without issue.
8911 </para>
8912
8913 <para>
8914 As with all solved problems, if they originated upstream, you
8915 need to submit the fix for the recipe in OE-Core and upstream
8916 so that the problem is taken care of at its source.
8917 See the
8918 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
8919 section for more information.
8920 </para>
8921 </section>
8922 </section>
8923
8924 <section id="examining-builds-using-toaster">
8925 <title>Examining Builds Using the Toaster API</title>
8926
8927 <para>
8928 Toaster is an Application Programming Interface (API) and
8929 web-based interface to the OpenEmbedded build system, which uses
8930 BitBake.
8931 Both interfaces are based on a Representational State Transfer
8932 (REST) API that queries for and returns build information using
8933 <filename>GET</filename> and <filename>JSON</filename>.
8934 These types of search operations retrieve sets of objects from
8935 a datastore used to collect build information.
8936 The results contain all the data for the objects being returned.
8937 You can order the results of the search by key and the search
8938 parameters are consistent for all object types.
8939 </para>
8940
8941 <para>
8942 Using the interfaces you can do the following:
8943 <itemizedlist>
8944 <listitem><para>See information about the tasks executed
8945 and reused during the build.</para></listitem>
8946 <listitem><para>See what is built (recipes and
8947 packages) and what packages were installed into the final
8948 image.</para></listitem>
8949 <listitem><para>See performance-related information such
8950 as build time, CPU usage, and disk I/O.</para></listitem>
8951 <listitem><para>Examine error, warning and trace messages
8952 to aid in debugging.</para></listitem>
8953 </itemizedlist>
8954 </para>
8955
8956 <note>
8957 <para>This release of Toaster provides you with information
8958 about a BitBake run.
8959 The tool does not allow you to configure and launch a build.
8960 However, future development includes plans to integrate the
8961 configuration and build launching capabilities of
8962 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
8963 </para>
8964 <para>For more information on using Hob to build an image,
8965 see the
8966 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
8967 section.</para>
8968 </note>
8969
8970 <para>
8971 The remainder of this section describes what you need to have in
8972 place to use Toaster, how to start it, use it, and stop it.
8973 For additional information on installing and running Toaster, see the
8974 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
8975 section of the "Toaster" wiki page.
8976 For complete information on the API and its search operation
8977 URI, parameters, and responses, see the
8978 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
8979 Wiki page.
8980 </para>
8981
8982 <section id='starting-toaster'>
8983 <title>Starting Toaster</title>
8984
8985 <para>
8986 Getting set up to use and start Toaster is simple.
8987 First, be sure you have met the following requirements:
8988 <itemizedlist>
8989 <listitem><para>You have set up your
8990 <link linkend='source-directory'>Source Directory</link>
8991 by cloning the upstream <filename>poky</filename>
8992 repository.
8993 See the
8994 <link linkend='local-yp-release'>Yocto Project Release</link>
8995 item for information on how to set up the Source
8996 Directory.</para></listitem>
8997 <listitem><para>Be sure your build machine has
8998 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
8999 version 1.5 installed.</para></listitem>
9000 <listitem><para>Make sure that port 8000 and 8200 are
9001 free (i.e. they have no servers on them).
9002 </para></listitem>
9003 </itemizedlist>
9004 </para>
9005
9006 <para>
9007 Once you have met the requirements, follow these steps to
9008 start Toaster running in the background of your shell:
9009 <orderedlist>
9010 <listitem><para><emphasis>Set up your build environment:</emphasis>
9011 Source a build environment script (i.e.
9012 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
9013 or
9014 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
9015 </para></listitem>
9016 <listitem><para><emphasis>Start Toaster:</emphasis>
9017 Start the Toaster service using this
9018 command from within your
9019 <link linkend='build-directory'>Build Directory</link>:
9020 <literallayout class='monospaced'>
9021 $ source toaster start
9022 </literallayout></para></listitem>
9023 <note>
9024 The Toaster must be started and running in order
9025 for it to collect data.
9026 </note>
9027 </orderedlist>
9028 </para>
9029
9030 <para>
9031 When Toaster starts, it creates some additional files in your
9032 Build Directory.
9033 Deleting these files will cause you to lose data or interrupt
9034 Toaster:
9035 <itemizedlist>
9036 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
9037 Toaster's database file.</para></listitem>
9038 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
9039 The log file of the web server.</para></listitem>
9040 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
9041 The log file of the user interface component.
9042 </para></listitem>
9043 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
9044 The PID of the web server.</para></listitem>
9045 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
9046 The PID of the DSI data bridge.</para></listitem>
9047 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
9048 The BitBake server's log file.</para></listitem>
9049 </itemizedlist>
9050 </para>
9051 </section>
9052
9053 <section id='using-toaster'>
9054 <title>Using Toaster</title>
9055
9056 <para>
9057 Once Toaster is running, it logs information for any BitBake
9058 run from your Build Directory.
9059 This logging is automatic.
9060 All you need to do is access and use the information.
9061 </para>
9062
9063 <para>
9064 You access the information one of two ways:
9065 <itemizedlist>
9066 <listitem><para>Open a Browser and enter
9067 <filename>http://localhost:8000</filename>
9068 for the URL.
9069 </para></listitem>
9070 <listitem><para>Use the <filename>xdg-open</filename>
9071 tool from the shell and pass it the same URL.
9072 </para></listitem>
9073 </itemizedlist>
9074 Either method opens the home page for the Toaster interface.
9075 </para>
9076
9077 <note><title>Notes</title>
9078 <itemizedlist>
9079 <listitem><para>
9080 For information on how to delete information from the
9081 Toaster database, see the
9082 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
9083 wiki page.
9084 </para></listitem>
9085 <listitem><para>
9086 For information on how to set up an instance of Toaster
9087 on a remote host, see the
9088 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink>
9089 wiki page.
9090 </para></listitem>
9091 </itemizedlist>
9092 </note>
9093 </section>
9094
9095 <section id='examining-toaster-data'>
9096 <title>Examining Toaster Data</title>
9097
9098 <para>
9099 The Toaster database is persistent regardless of whether you
9100 start or stop the service.
9101 </para>
9102
9103 <para>
9104 Toaster's interface shows you a list of builds
9105 (successful and unsuccessful) for which it has data.
9106 You can click on any build to see related information.
9107 This information includes configuration details, information
9108 about tasks, all recipes and packages built and their
9109 dependencies, packages and their directory structure as
9110 installed in your final image,
9111 execution time, CPU usage and disk I/O per task.
9112 </para>
9113
9114 <para>
9115 For details on the interface, see the
9116 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
9117 </para>
9118 </section>
9119
9120 <section id='stopping-toaster'>
9121 <title>Stopping Toaster</title>
9122
9123 <para>
9124 Stop the Toaster service with the following command
9125 from with the
9126 <link linkend='build-directory'>Build Directory</link>:
9127 <literallayout class='monospaced'>
9128 $ source toaster stop
9129 </literallayout>
9130 The service stops but the Toaster database remains persistent.
9131 </para>
9132 </section>
9133 </section>
9134
9135 <section id="platdev-oprofile">
9136 <title>Profiling with OProfile</title>
9137
9138 <para>
9139 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
9140 statistical profiler well suited for finding performance
9141 bottlenecks in both user-space software and in the kernel.
9142 This profiler provides answers to questions like "Which functions does my application spend
9143 the most time in when doing X?"
9144 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
9145 applications on target hardware straight forward.
9146 <note>
9147 For more information on how to set up and run OProfile, see the
9148 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
9149 section in the Yocto Project Profiling and Tracing Manual.
9150 </note>
9151 </para>
9152
9153 <para>
9154 To use OProfile, you need an image that has OProfile installed.
9155 The easiest way to do this is with "tools-profile" in the
9156 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
9157 You also need debugging symbols to be available on the system where the analysis
9158 takes place.
9159 You can gain access to the symbols by using "dbg-pkgs" in the
9160 <filename>IMAGE_FEATURES</filename> variable or by
9161 installing the appropriate debug (<filename>-dbg</filename>)
9162 packages.
9163 </para>
9164
9165 <para>
9166 For successful call graph analysis, the binaries must preserve the frame
9167 pointer register and should also be compiled with the
9168 <filename>-fno-omit-framepointer</filename> flag.
9169 You can achieve this by setting the
9170 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
9171 variable with the following options:
9172 <literallayout class='monospaced'>
9173 -fexpensive-optimizations
9174 -fno-omit-framepointer
9175 -frename-registers
9176 -O2
9177 </literallayout>
9178 You can also achieve it by setting the
9179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
9180 variable to "1" in the <filename>local.conf</filename> configuration file.
9181 If you use the <filename>DEBUG_BUILD</filename> variable,
9182 you also add extra debugging information that can make the debug
9183 packages large.
9184 </para>
9185
9186 <section id="platdev-oprofile-target">
9187 <title>Profiling on the Target</title>
9188
9189 <para>
9190 Using OProfile, you can perform all the profiling work on the target device.
9191 A simple OProfile session might look like the following:
9192 </para>
9193
9194 <para>
9195 <literallayout class='monospaced'>
9196 # opcontrol &dash;&dash;reset
9197 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
9198 .
9199 .
9200 [do whatever is being profiled]
9201 .
9202 .
9203 # opcontrol &dash;&dash;stop
9204 $ opreport -cl
9205 </literallayout>
9206 </para>
9207
9208 <para>
9209 In this example, the <filename>reset</filename> command clears any previously profiled data.
9210 The next command starts OProfile.
9211 The options used when starting the profiler separate dynamic library data
9212 within applications, disable kernel profiling, and enable callgraphing up to
9213 five levels deep.
9214 <note>
9215 To profile the kernel, you would specify the
9216 <filename>&dash;&dash;vmlinux=/path/to/vmlinux</filename> option.
9217 The <filename>vmlinux</filename> file is usually in the source directory in the
9218 <filename>/boot/</filename> directory and must match the running kernel.
9219 </note>
9220 </para>
9221
9222 <para>
9223 After you perform your profiling tasks, the next command stops the profiler.
9224 After that, you can view results with the <filename>opreport</filename> command with options
9225 to see the separate library symbols and callgraph information.
9226 </para>
9227
9228 <para>
9229 Callgraphing logs information about time spent in functions and about a function's
9230 calling function (parent) and called functions (children).
9231 The higher the callgraphing depth, the more accurate the results.
9232 However, higher depths also increase the logging overhead.
9233 Consequently, you should take care when setting the callgraphing depth.
9234 <note>
9235 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
9236 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
9237 with <filename>gcc</filename>.
9238 </note>
9239 </para>
9240
9241 <para>
9242 For more information on using OProfile, see the OProfile
9243 online documentation at
9244 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
9245 </para>
9246 </section>
9247
9248 <section id="platdev-oprofile-oprofileui">
9249 <title>Using OProfileUI</title>
9250
9251 <para>
9252 A graphical user interface for OProfile is also available.
9253 You can download and build this interface from the Yocto Project at
9254 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
9255 If the "tools-profile" image feature is selected, all necessary binaries
9256 are installed onto the target device for OProfileUI interaction.
9257 For a list of image features that ship with the Yocto Project,
9258 see the
9259 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
9260 section in the Yocto Project Reference Manual.
9261 </para>
9262
9263 <para>
9264 Even though the source directory usually includes all needed patches on the target device, you
9265 might find you need other OProfile patches for recent OProfileUI features.
9266 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
9267 OProfileUI README</ulink> for the most recent information.
9268 </para>
9269
9270 <section id="platdev-oprofile-oprofileui-online">
9271 <title>Online Mode</title>
9272
9273 <para>
9274 Using OProfile in online mode assumes a working network connection with the target
9275 hardware.
9276 With this connection, you just need to run "oprofile-server" on the device.
9277 By default, OProfile listens on port 4224.
9278 <note>
9279 You can change the port using the <filename>&dash;&dash;port</filename> command-line
9280 option.
9281 </note>
9282 </para>
9283
9284 <para>
9285 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
9286 straight forward.
9287 You access key functionality through the buttons on the toolbar, which
9288 are duplicated in the menus.
9289 Here are the buttons:
9290 <itemizedlist>
9291 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
9292 You can also supply the IP address or hostname.</para></listitem>
9293 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
9294 </para></listitem>
9295 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
9296 </para></listitem>
9297 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
9298 downloads the data to the local host.
9299 Stopping the profiler generates the profile and displays it in the viewer.
9300 </para></listitem>
9301 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
9302 target and generates the profile, which appears in the viewer.</para></listitem>
9303 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
9304 Resetting the data removes sample information collected from previous
9305 sampling runs.
9306 Be sure you reset the data if you do not want to include old sample information.
9307 </para></listitem>
9308 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
9309 target to another directory for later examination.</para></listitem>
9310 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
9311 </para></listitem>
9312 </itemizedlist>
9313 </para>
9314
9315 <para>
9316 The client downloads the complete profile archive from
9317 the target to the host for processing.
9318 This archive is a directory that contains the sample data, the object files,
9319 and the debug information for the object files.
9320 The archive is then converted using the <filename>oparchconv</filename> script, which is
9321 included in this distribution.
9322 The script uses <filename>opimport</filename> to convert the archive from
9323 the target to something that can be processed on the host.
9324 </para>
9325
9326 <para>
9327 Downloaded archives reside in the
9328 <link linkend='build-directory'>Build Directory</link> in
9329 <filename>tmp</filename> and are cleared up when they are no longer in use.
9330 </para>
9331
9332 <para>
9333 If you wish to perform kernel profiling, you need to be sure
9334 a <filename>vmlinux</filename> file that matches the running kernel is available.
9335 In the source directory, that file is usually located in
9336 <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where
9337 <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel.
9338 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
9339 packages for each kernel it builds.
9340 Thus, it should just be a question of making sure a matching package is
9341 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
9342 The files are automatically installed into development and profiling images
9343 alongside OProfile.
9344 A configuration option exists within the OProfileUI settings page that you can use to
9345 enter the location of the <filename>vmlinux</filename> file.
9346 </para>
9347
9348 <para>
9349 Waiting for debug symbols to transfer from the device can be slow, and it
9350 is not always necessary to actually have them on the device for OProfile use.
9351 All that is needed is a copy of the filesystem with the debug symbols present
9352 on the viewer system.
9353 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
9354 section covers how to create such a directory within
9355 the source directory and how to use the OProfileUI Settings
9356 Dialog to specify the location.
9357 If you specify the directory, it will be used when the file checksums
9358 match those on the system you are profiling.
9359 </para>
9360 </section>
9361
9362 <section id="platdev-oprofile-oprofileui-offline">
9363 <title>Offline Mode</title>
9364
9365 <para>
9366 If network access to the target is unavailable, you can generate
9367 an archive for processing in <filename>oprofile-viewer</filename> as follows:
9368 <literallayout class='monospaced'>
9369 # opcontrol &dash;&dash;reset
9370 # opcontrol &dash;&dash;start &dash;&dash;separate=lib &dash;&dash;no-vmlinux -c 5
9371 .
9372 .
9373 [do whatever is being profiled]
9374 .
9375 .
9376 # opcontrol &dash;&dash;stop
9377 # oparchive -o my_archive
9378 </literallayout>
9379 </para>
9380
9381 <para>
9382 In the above example, <filename>my_archive</filename> is the name of the
9383 archive directory where you would like the profile archive to be kept.
9384 After the directory is created, you can copy it to another host and load it
9385 using <filename>oprofile-viewer</filename> open functionality.
9386 If necessary, the archive is converted.
9387 </para>
9388 </section>
9389 </section>
9390 </section>
9391
9392 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
9393 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
9394
9395 <para>
9396 One of the concerns for a development organization using open source
9397 software is how to maintain compliance with various open source
9398 licensing during the lifecycle of the product.
9399 While this section does not provide legal advice or
9400 comprehensively cover all scenarios, it does
9401 present methods that you can use to
9402 assist you in meeting the compliance requirements during a software
9403 release.
9404 </para>
9405
9406 <para>
9407 With hundreds of different open source licenses that the Yocto
9408 Project tracks, it is difficult to know the requirements of each
9409 and every license.
9410 However, the requirements of the major FLOSS licenses can begin
9411 to be covered by
9412 assuming that three main areas of concern exist:
9413 <itemizedlist>
9414 <listitem><para>Source code must be provided.</para></listitem>
9415 <listitem><para>License text for the software must be
9416 provided.</para></listitem>
9417 <listitem><para>Compilation scripts and modifications to the
9418 source code must be provided.
9419 </para></listitem>
9420 </itemizedlist>
9421 There are other requirements beyond the scope of these
9422 three and the methods described in this section
9423 (e.g. the mechanism through which source code is distributed).
9424 </para>
9425
9426 <para>
9427 As different organizations have different methods of complying with
9428 open source licensing, this section is not meant to imply that
9429 there is only one single way to meet your compliance obligations,
9430 but rather to describe one method of achieving compliance.
9431 The remainder of this section describes methods supported to meet the
9432 previously mentioned three requirements.
9433 Once you take steps to meet these requirements,
9434 and prior to releasing images, sources, and the build system,
9435 you should audit all artifacts to ensure completeness.
9436 <note>
9437 The Yocto Project generates a license manifest during
9438 image creation that is located
9439 in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
9440 to assist with any audits.
9441 </note>
9442 </para>
9443
9444 <section id='providing-the-source-code'>
9445 <title>Providing the Source Code</title>
9446
9447 <para>
9448 Compliance activities should begin before you generate the
9449 final image.
9450 The first thing you should look at is the requirement that
9451 tops the list for most compliance groups - providing
9452 the source.
9453 The Yocto Project has a few ways of meeting this
9454 requirement.
9455 </para>
9456
9457 <para>
9458 One of the easiest ways to meet this requirement is
9459 to provide the entire
9460 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
9461 used by the build.
9462 This method, however, has a few issues.
9463 The most obvious is the size of the directory since it includes
9464 all sources used in the build and not just the source used in
9465 the released image.
9466 It will include toolchain source, and other artifacts, which
9467 you would not generally release.
9468 However, the more serious issue for most companies is accidental
9469 release of proprietary software.
9470 The Yocto Project provides an
9471 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
9472 class to help avoid some of these concerns.
9473 </para>
9474
9475 <para>
9476 Before you employ <filename>DL_DIR</filename> or the
9477 archiver class, you need to decide how you choose to
9478 provide source.
9479 The source archiver class can generate tarballs and SRPMs
9480 and can create them with various levels of compliance in mind.
9481 </para>
9482
9483 <para>
9484 One way of doing this (but certainly not the only way) is to
9485 release just the source as a tarball.
9486 You can do this by adding the following to the
9487 <filename>local.conf</filename> file found in the
9488 <link linkend='build-directory'>Build Directory</link>:
9489 <literallayout class='monospaced'>
9490 INHERIT += "archiver"
9491 ARCHIVER_MODE[src] = "original"
9492 </literallayout>
9493 During the creation of your image, the source from all
9494 recipes that deploy packages to the image is placed within
9495 subdirectories of
9496 <filename>DEPLOY_DIR/sources</filename> based on the
9497 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
9498 for each recipe.
9499 Releasing the entire directory enables you to comply with
9500 requirements concerning providing the unmodified source.
9501 It is important to note that the size of the directory can
9502 get large.
9503 </para>
9504
9505 <para>
9506 A way to help mitigate the size issue is to only release
9507 tarballs for licenses that require the release of
9508 source.
9509 Let us assume you are only concerned with GPL code as
9510 identified with the following:
9511 <literallayout class='monospaced'>
9512 $ cd poky/build/tmp/deploy/sources
9513 $ mkdir ~/gpl_source_release
9514 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
9515 </literallayout>
9516 At this point, you could create a tarball from the
9517 <filename>gpl_source_release</filename> directory and
9518 provide that to the end user.
9519 This method would be a step toward achieving compliance
9520 with section 3a of GPLv2 and with section 6 of GPLv3.
9521 </para>
9522 </section>
9523
9524 <section id='providing-license-text'>
9525 <title>Providing License Text</title>
9526
9527 <para>
9528 One requirement that is often overlooked is inclusion
9529 of license text.
9530 This requirement also needs to be dealt with prior to
9531 generating the final image.
9532 Some licenses require the license text to accompany
9533 the binary.
9534 You can achieve this by adding the following to your
9535 <filename>local.conf</filename> file:
9536 <literallayout class='monospaced'>
9537 COPY_LIC_MANIFEST = "1"
9538 COPY_LIC_DIRS = "1"
9539 </literallayout>
9540 Adding these statements to the configuration file ensures
9541 that the licenses collected during package generation
9542 are included on your image.
9543 As the source archiver has already archived the original
9544 unmodified source that contains the license files,
9545 you would have already met the requirements for inclusion
9546 of the license information with source as defined by the GPL
9547 and other open source licenses.
9548 </para>
9549 </section>
9550
9551 <section id='providing-compilation-scripts-and-source-code-modifications'>
9552 <title>Providing Compilation Scripts and Source Code Modifications</title>
9553
9554 <para>
9555 At this point, we have addressed all we need to address
9556 prior to generating the image.
9557 The next two requirements are addressed during the final
9558 packaging of the release.
9559 </para>
9560
9561 <para>
9562 By releasing the version of the OpenEmbedded build system
9563 and the layers used during the build, you will be providing both
9564 compilation scripts and the source code modifications in one
9565 step.
9566 </para>
9567
9568 <para>
9569 If the deployment team has a
9570 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
9571 and a distro layer, and those those layers are used to patch,
9572 compile, package, or modify (in any way) any open source
9573 software included in your released images, you
9574 might be required to to release those layers under section 3 of
9575 GPLv2 or section 1 of GPLv3.
9576 One way of doing that is with a clean
9577 checkout of the version of the Yocto Project and layers used
9578 during your build.
9579 Here is an example:
9580 <literallayout class='monospaced'>
9581 # We built using the &DISTRO_NAME; branch of the poky repo
9582 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
9583 $ cd poky
9584 # We built using the release_branch for our layers
9585 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
9586 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
9587 # clean up the .git repos
9588 $ find . -name ".git" -type d -exec rm -rf {} \;
9589 </literallayout>
9590 One thing a development organization might want to consider
9591 for end-user convenience is to modify
9592 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
9593 ensure that when the end user utilizes the released build
9594 system to build an image, the development organization's
9595 layers are included in the <filename>bblayers.conf</filename>
9596 file automatically:
9597 <literallayout class='monospaced'>
9598 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
9599 # changes incompatibly
9600 LCONF_VERSION = "6"
9601
9602 BBPATH = "${TOPDIR}"
9603 BBFILES ?= ""
9604
9605 BBLAYERS ?= " \
9606 ##OEROOT##/meta \
9607 ##OEROOT##/meta-yocto \
9608 ##OEROOT##/meta-yocto-bsp \
9609 ##OEROOT##/meta-mylayer \
9610 "
9611
9612 BBLAYERS_NON_REMOVABLE ?= " \
9613 ##OEROOT##/meta \
9614 ##OEROOT##/meta-yocto \
9615 "
9616 </literallayout>
9617 Creating and providing an archive of the
9618 <link linkend='metadata'>Metadata</link> layers
9619 (recipes, configuration files, and so forth)
9620 enables you to meet your
9621 requirements to include the scripts to control compilation
9622 as well as any modifications to the original source.
9623 </para>
9624 </section>
9625 </section>
9626
9627 <section id='using-the-error-reporting-tool'>
9628 <title>Using the Error Reporting Tool</title>
9629
9630 <para>
9631 The error reporting tool allows you to
9632 submit errors encountered during builds to a central database.
9633 Outside of the build environment, you can use a web interface to
9634 browse errors, view statistics, and query for errors.
9635 The tool works using a client-server system where the client
9636 portion is integrated with the installed Yocto Project
9637 <link linkend='source-directory'>Source Directory</link>
9638 (e.g. <filename>poky</filename>).
9639 The server receives the information collected and saves it in a
9640 database.
9641 </para>
9642
9643 <para>
9644 A live instance of the error reporting server exists at
9645 <ulink url='http://errors.yoctoproject.org'></ulink>.
9646 This server exists so that when you want to get help with
9647 build failures, you can submit all of the information on the
9648 failure easily and then point to the URL in your bug report
9649 or send an email to the mailing list.
9650 <note>
9651 If you send error reports to this server, the reports become
9652 publicly visible.
9653 </note>
9654 </para>
9655
9656 <section id='enabling-and-using-the-tool'>
9657 <title>Enabling and Using the Tool</title>
9658
9659 <para>
9660 By default, the error reporting tool is disabled.
9661 You can enable it by inheriting the
9662 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
9663 class by adding the following statement to the end of
9664 your <filename>local.conf</filename> file in your
9665 <link linkend='build-directory'>Build Directory</link>.
9666 <literallayout class='monospaced'>
9667 INHERIT += "report-error"
9668 </literallayout>
9669 </para>
9670
9671 <para>
9672 By default, the error reporting feature stores information in
9673 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
9674 However, you can specify a directory to use by adding the following
9675 to your <filename>local.conf</filename> file:
9676 <literallayout class='monospaced'>
9677 ERR_REPORT_DIR = "path"
9678 </literallayout>
9679 Enabling error reporting causes the build process to collect
9680 the errors and store them in a file as previously described.
9681 When the build system encounters an error, it includes a command
9682 as part of the console output.
9683 You can run the command to send the error file to the server.
9684 For example, the following command sends the errors to an upstream
9685 server:
9686 <literallayout class='monospaced'>
9687 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
9688 </literallayout>
9689 In the above example, the <filename>server</filename> parameter is
9690 optional.
9691 By default, the errors are sent to a database used by the entire
9692 community.
9693 If you specify a particular server, you can send them to a different
9694 database.
9695 </para>
9696
9697 <para>
9698 When sending the error file, you receive a link that corresponds
9699 to your entry in the database.
9700 For example, here is a typical link:
9701 <literallayout class='monospaced'>
9702 http://localhost:8000/Errors/Search/1/158
9703 </literallayout>
9704 Following the link takes you to a web interface where you can
9705 browse, query the errors, and view statistics.
9706 </para>
9707 </section>
9708
9709 <section id='disabling-the-tool'>
9710 <title>Disabling the Tool</title>
9711
9712 <para>
9713 To disable the error reporting feature, simply remove or comment
9714 out the following statement from the end of your
9715 <filename>local.conf</filename> file in your
9716 <link linkend='build-directory'>Build Directory</link>.
9717 <literallayout class='monospaced'>
9718 INHERIT += "report-error"
9719 </literallayout>
9720 </para>
9721 </section>
9722
9723 <section id='setting-up-your-own-error-reporting-server'>
9724 <title>Setting Up Your Own Error Reporting Server</title>
9725
9726 <para>
9727 If you want to set up your own error reporting server, you
9728 can obtain the code from the Git repository at
9729 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
9730 Instructions on how to set it up are in the README document.
9731 </para>
9732 </section>
9733 </section>
9734</chapter>
9735
9736<!--
9737vim: expandtab tw=80 ts=4
9738-->
diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl
new file mode 100644
index 0000000000..5dd425c810
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-customization.xsl
@@ -0,0 +1,19 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
5
6 <xsl:include href="../template/permalinks.xsl"/>
7 <xsl:include href="../template/section.title.xsl"/>
8 <xsl:include href="../template/component.title.xsl"/>
9 <xsl:include href="../template/division.title.xsl"/>
10 <xsl:include href="../template/formal.object.heading.xsl"/>
11
12 <xsl:param name="html.stylesheet" select="'dev-style.css'" />
13 <xsl:param name="chapter.autolabel" select="1" />
14 <xsl:param name="appendix.autolabel" select="A" />
15 <xsl:param name="section.autolabel" select="1" />
16 <xsl:param name="section.label.includes.component.label" select="1" />
17 <xsl:param name="generate.id.attributes" select="1" />
18
19</xsl:stylesheet>
diff --git a/documentation/dev-manual/dev-manual-eclipse-customization.xsl b/documentation/dev-manual/dev-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..8ac4c18f25
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
1<?xml version='1.0'?>
2<xsl:stylesheet
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 xmlns="http://www.w3.org/1999/xhtml"
5 xmlns:fo="http://www.w3.org/1999/XSL/Format"
6 version="1.0">
7
8 <xsl:import
9 href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
10
11 <xsl:param name="chunker.output.indent" select="'yes'"/>
12 <xsl:param name="chunk.quietly" select="1"/>
13 <xsl:param name="chunk.first.sections" select="1"/>
14 <xsl:param name="chunk.section.depth" select="10"/>
15 <xsl:param name="use.id.as.filename" select="1"/>
16 <xsl:param name="ulink.target" select="'_self'" />
17 <xsl:param name="base.dir" select="'html/dev-manual/'"/>
18 <xsl:param name="html.stylesheet" select="'../book.css'"/>
19 <xsl:param name="eclipse.manifest" select="0"/>
20 <xsl:param name="create.plugin.xml" select="0"/>
21 <xsl:param name="suppress.navigation" select="1"/>
22 <xsl:param name="generate.index" select="0"/>
23 <xsl:param name="chapter.autolabel" select="1" />
24 <xsl:param name="appendix.autolabel" select="1" />
25 <xsl:param name="section.autolabel" select="1" />
26 <xsl:param name="section.label.includes.component.label" select="1" />
27</xsl:stylesheet>
diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml
new file mode 100644
index 0000000000..21fba29670
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -0,0 +1,240 @@
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='dev-manual-intro'>
6
7<title>The Yocto Project Development Manual</title>
8 <section id='intro'>
9 <title>Introduction</title>
10
11 <para>
12 Welcome to the Yocto Project Development Manual!
13 This manual provides information on how to use the Yocto Project to
14 develop embedded Linux images and user-space applications that
15 run on targeted devices.
16 The manual provides an overview of image, kernel, and
17 user-space application development using the Yocto Project.
18 Because much of the information in this manual is general, it
19 contains many references to other sources where you can find more
20 detail.
21 For example, you can find detailed information on Git, repositories,
22 and open source in general in many places on the Internet.
23 Another example specific to the Yocto Project is how to quickly
24 set up your host development system and build an image, which you
25 find in the
26 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
27 </para>
28
29 <para>
30 The Yocto Project Development Manual does, however, provide
31 guidance and examples on how to change the kernel source code,
32 reconfigure the kernel, and develop an application using the
33 popular <trademark class='trade'>Eclipse</trademark> IDE.
34 </para>
35
36 <note>
37 By default, using the Yocto Project creates a Poky distribution.
38 However, you can create your own distribution by providing key
39 <link linkend='metadata'>Metadata</link>.
40 A good example is Angstrom, which has had a distribution
41 based on the Yocto Project since its inception.
42 Other examples include commercial distributions like
43 <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
44 <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
45 <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
46 and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
47 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
48 section for more information.
49 </note>
50 </section>
51
52 <section id='what-this-manual-provides'>
53 <title>What This Manual Provides</title>
54
55 <para>
56 The following list describes what you can get from this manual:
57 <itemizedlist>
58 <listitem><para>Information that lets you get set
59 up to develop using the Yocto Project.</para></listitem>
60 <listitem><para>Information to help developers who are new to
61 the open source environment and to the distributed revision
62 control system Git, which the Yocto Project uses.
63 </para></listitem>
64 <listitem><para>An understanding of common end-to-end
65 development models and tasks.</para></listitem>
66 <listitem><para>Information about common development tasks
67 generally used during image development for
68 embedded devices.
69 </para></listitem>
70 <listitem><para>Information on using the Yocto Project
71 integration of the QuickEMUlator (QEMU), which lets you
72 simulate running on hardware an image you have built using
73 the OpenEmbedded build system.
74 </para></listitem>
75 <listitem><para>Many references to other sources of related
76 information.</para></listitem>
77 </itemizedlist>
78 </para>
79 </section>
80
81 <section id='what-this-manual-does-not-provide'>
82 <title>What this Manual Does Not Provide</title>
83
84 <para>
85 This manual will not give you the following:
86 <itemizedlist>
87 <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto
88 Project documentation:</emphasis>
89 For example, the Yocto Project Application Developer's Guide contains detailed
90 instructions on how to run the
91 <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>ADT Installer</ulink>,
92 which is used to set up a cross-development environment.</para></listitem>
93 <listitem><para><emphasis>Reference material:</emphasis>
94 This type of material resides in an appropriate reference manual.
95 For example, system variables are documented in the
96 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
97 <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis>
98 For example, exhaustive information on how to use Git is covered better through the
99 Internet than in this manual.</para></listitem>
100 </itemizedlist>
101 </para>
102 </section>
103
104 <section id='other-information'>
105 <title>Other Information</title>
106
107 <para>
108 Because this manual presents overview information for many different
109 topics, supplemental information is recommended for full
110 comprehension.
111 The following list presents other sources of information you might find helpful:
112 <itemizedlist>
113 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
114 </emphasis> The home page for the Yocto Project provides lots of information on the project
115 as well as links to software and documentation.
116 </para></listitem>
117 <listitem><para><emphasis>
118 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis>
119 This short document lets you get started
120 with the Yocto Project and quickly begin building an image.
121 </para></listitem>
122 <listitem><para><emphasis>
123 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis>
124 This manual is a reference
125 guide to the OpenEmbedded build system, which is based on BitBake.
126 The build system is sometimes referred to as "Poky".
127 </para></listitem>
128 <listitem><para><emphasis>
129 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
130 This guide provides information that lets you get going with the Application
131 Development Toolkit (ADT) and stand-alone cross-development toolchains to
132 develop projects using the Yocto Project.
133 </para></listitem>
134 <listitem><para><emphasis>
135 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
136 This guide defines the structure for BSP components.
137 Having a commonly understood structure encourages standardization.
138 </para></listitem>
139 <listitem><para><emphasis>
140 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:</emphasis>
141 This manual describes how to work with Linux Yocto kernels as well as provides a bit
142 of conceptual information on the construction of the Yocto Linux kernel tree.
143 </para></listitem>
144 <listitem><para><emphasis>
145 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:</emphasis>
146 This manual presents a set of common and generally useful tracing and
147 profiling schemes along with their applications (as appropriate) to each tool.
148 </para></listitem>
149 <listitem><para><emphasis>
150 <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
151 Eclipse IDE Yocto Plug-in</ulink>:</emphasis>
152 A step-by-step instructional video that
153 demonstrates how an application developer uses Yocto Plug-in features within
154 the Eclipse IDE.
155 </para></listitem>
156 <listitem><para><emphasis>
157 <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
158 A list of commonly asked questions and their answers.
159 </para></listitem>
160 <listitem><para><emphasis>
161 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:</emphasis>
162 Features, updates and known issues for the current
163 release of the Yocto Project.
164 </para></listitem>
165 <listitem><para><emphasis>
166 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>:</emphasis>
167 A graphical user interface for BitBake.
168 Hob's primary goal is to enable a user to perform common tasks more easily.
169 </para></listitem>
170 <listitem><para><emphasis>
171 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/toaster'>Toaster</ulink>:</emphasis>
172 An Application Programming Interface (API) and web-based
173 interface to the OpenEmbedded build system, which uses
174 BitBake, that reports build information.
175 </para></listitem>
176 <listitem><para><emphasis>
177 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/build-appliance'>Build Appliance</ulink>:</emphasis>
178 A virtual machine that
179 enables you to build and boot a custom embedded Linux image
180 with the Yocto Project using a non-Linux development system.
181 </para></listitem>
182 <listitem><para><emphasis>
183 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
184 The bug tracking application the Yocto Project uses.
185 If you find problems with the Yocto Project, you should report them using this
186 application.
187 </para></listitem>
188 <listitem><para><emphasis>Yocto Project Mailing Lists:</emphasis>
189 To subscribe to the Yocto Project mailing
190 lists, click on the following URLs and follow the instructions:
191 <itemizedlist>
192 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink>
193 for a Yocto Project Discussions mailing list.
194 </para></listitem>
195 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink>
196 for a Yocto Project Discussions mailing list about the
197 OpenEmbedded build system (Poky).
198 </para></listitem>
199 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
200 for a mailing list to receive official Yocto Project announcements
201 as well as Yocto Project milestones.
202 </para></listitem>
203 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink>
204 for a listing of all public mailing lists on
205 <filename>lists.yoctoproject.org</filename>.
206 </para></listitem>
207 </itemizedlist></para></listitem>
208 <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
209 Two IRC channels on freenode are available
210 for Yocto Project and Poky discussions: <filename>#yocto</filename> and
211 <filename>#poky</filename>, respectively.
212 </para></listitem>
213 <listitem><para><emphasis>
214 <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
215 The build system used by the Yocto Project.
216 This project is the upstream, generic, embedded distribution
217 from which the Yocto Project derives its build system (Poky)
218 and to which it contributes.
219 </para></listitem>
220 <listitem><para><emphasis>
221 <ulink url='http://www.openembedded.org/wiki/BitBake'>BitBake</ulink>:</emphasis>
222 The tool used by the OpenEmbedded build system
223 to process project metadata.
224 </para></listitem>
225 <listitem><para><emphasis>
226 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual:</ulink></emphasis>
227 A comprehensive guide to the BitBake tool.
228 If you want information on BitBake, see this manual.
229 </para></listitem>
230 <listitem><para><emphasis>
231 <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:</emphasis>
232 An open-source machine emulator and virtualizer.
233 </para></listitem>
234 </itemizedlist>
235 </para>
236 </section>
237</chapter>
238<!--
239vim: expandtab tw=80 ts=4
240-->
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
new file mode 100644
index 0000000000..43c31b8405
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -0,0 +1,2112 @@
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='dev-manual-model'>
6
7<title>Common Development Models</title>
8
9<para>
10 Many development models exist for which you can use the Yocto Project.
11 This chapter overviews simple methods that use tools provided by the
12 Yocto Project:
13 <itemizedlist>
14 <listitem><para><emphasis>System Development:</emphasis>
15 System Development covers Board Support Package (BSP) development and kernel
16 modification or configuration.
17 For an example on how to create a BSP, see the
18 "<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>"
19 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
20 For more complete information on how to work with the kernel, see the
21 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
22 </para></listitem>
23 <listitem><para><emphasis>User Application Development:</emphasis>
24 User Application Development covers development of applications that you intend
25 to run on target hardware.
26 For information on how to set up your host development system for user-space
27 application development, see the
28 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
29 For a simple example of user-space application development using the
30 <trademark class='trade'>Eclipse</trademark> IDE, see the
31 "<link linkend='application-development-workflow'>Application
32 Development Workflow</link>" section.
33 </para></listitem>
34 <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
35 Direct modification of temporary source code is a convenient development model
36 to quickly iterate and develop towards a solution.
37 Once you implement the solution, you should of course take steps to
38 get the changes upstream and applied in the affected recipes.</para></listitem>
39 <listitem><para><emphasis>Image Development using Hob:</emphasis>
40 You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build
41 custom operating system images within the build environment.
42 Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
43 <listitem><para><emphasis>Using a Development Shell:</emphasis>
44 You can use a <filename>devshell</filename> to efficiently debug commands or simply
45 edit packages.
46 Working inside a development shell is a quick way to set up the OpenEmbedded build
47 environment to work on parts of a project.</para></listitem>
48 </itemizedlist>
49</para>
50
51<section id='system-development-model'>
52 <title>System Development Workflow</title>
53
54 <para>
55 System development involves modification or creation of an image that you want to run on
56 a specific hardware target.
57 Usually, when you want to create an image that runs on embedded hardware, the image does
58 not require the same number of features that a full-fledged Linux distribution provides.
59 Thus, you can create a much smaller image that is designed to use only the
60 features for your particular hardware.
61 </para>
62
63 <para>
64 To help you understand how system development works in the Yocto Project, this section
65 covers two types of image development: BSP creation and kernel modification or
66 configuration.
67 </para>
68
69 <section id='developing-a-board-support-package-bsp'>
70 <title>Developing a Board Support Package (BSP)</title>
71
72 <para>
73 A BSP is a collection of recipes that, when applied during a build, results in
74 an image that you can run on a particular board.
75 Thus, the package when compiled into the new image, supports the operation of the board.
76 </para>
77
78 <note>
79 For a brief list of terms used when describing the development process in the Yocto Project,
80 see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
81 </note>
82
83 <para>
84 The remainder of this section presents the basic
85 steps used to create a BSP using the Yocto Project's
86 <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>.
87 Although not required for BSP creation, the
88 <filename>meta-intel</filename> repository, which contains
89 many BSPs supported by the Yocto Project, is part of the example.
90 </para>
91
92 <para>
93 For an example that shows how to create a new layer using the tools, see the
94 "<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>"
95 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
96 </para>
97
98 <para>
99 The following illustration and list summarize the BSP creation general workflow.
100 </para>
101
102 <para>
103 <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
104 </para>
105
106 <para>
107 <orderedlist>
108 <listitem><para><emphasis>Set up your host development system to support
109 development using the Yocto Project</emphasis>: See the
110 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
111 and the
112 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
113 in the Yocto Project Quick Start for requirements.</para></listitem>
114 <listitem><para><emphasis>Establish a local copy of the project files on your
115 system</emphasis>: You need this <link linkend='source-directory'>Source
116 Directory</link> available on your host system.
117 Having these files on your system gives you access to the build
118 process and to the tools you need.
119 For information on how to set up the Source Directory,
120 see the
121 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
122 <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
123 repository on your system</emphasis>: Having local copies
124 of these supported BSP layers on your system gives you
125 access to layers you might be able to build on or modify
126 to create your BSP.
127 For information on how to get these files, see the
128 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
129 <listitem><para><emphasis>Create your own BSP layer using the
130 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
131 Layers are ideal for
132 isolating and storing work for a given piece of hardware.
133 A layer is really just a location or area in which you place
134 the recipes and configurations for your BSP.
135 In fact, a BSP is, in itself, a special type of layer.
136 The simplest way to create a new BSP layer that is compliant with the
137 Yocto Project is to use the <filename>yocto-bsp</filename> script.
138 For information about that script, see the
139 "<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>"
140 section in the Yocto Project Board Support (BSP) Developer's Guide.
141 </para>
142 <para>
143 Another example that illustrates a layer is an application.
144 Suppose you are creating an application that has library or other dependencies in
145 order for it to compile and run.
146 The layer, in this case, would be where all the recipes that define those dependencies
147 are kept.
148 The key point for a layer is that it is an isolated area that contains
149 all the relevant information for the project that the OpenEmbedded build
150 system knows about.
151 For more information on layers, see the
152 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
153 section.
154 For more information on BSP layers, see the
155 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the
156 Yocto Project Board Support Package (BSP) Developer's Guide.</para>
157 <note>Five BSPs exist that are part of the
158 Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>,
159 <filename>beaglebone</filename> (ARM),
160 <filename>mpc8315e</filename> (PowerPC),
161 and <filename>edgerouter</filename> (MIPS).
162 The recipes and configurations for these five BSPs are located and dispersed
163 within the <link linkend='source-directory'>Source Directory</link>.
164 On the other hand, the <filename>meta-intel</filename> layer
165 contains BSP layers for many supported BSPs (e.g.
166 Crystal Forest, Emenlow, Fish River Island 2, Haswell,
167 Jasper Forest, and so forth).
168 Aside from the BSPs in the <filename>meta-intel</filename>
169 layer, the
170 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
171 contain additional BSP layers such as
172 <filename>meta-minnow</filename> and
173 <filename>meta-raspberrypi</filename>.</note>
174 <para>When you set up a layer for a new BSP, you should follow a standard layout.
175 This layout is described in the
176 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
177 section of the Board Support Package (BSP) Development Guide.
178 In the standard layout, you will notice a suggested structure for recipes and
179 configuration information.
180 You can see the standard layout for a BSP by examining
181 any supported BSP found in the <filename>meta-intel</filename> layer inside
182 the Source Directory.</para></listitem>
183 <listitem><para><emphasis>Make configuration changes to your new BSP
184 layer</emphasis>: The standard BSP layer structure organizes the files you need
185 to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
186 directories within the BSP layer.
187 Configuration changes identify where your new layer is on the local system
188 and identify which kernel you are going to use.
189 When you run the <filename>yocto-bsp</filename> script, you are able to interactively
190 configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
191 </para></listitem>
192 <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
193 changes include altering recipes (<filename>.bb</filename> files), removing
194 recipes you do not use, and adding new recipes or append files
195 (<filename>.bbappend</filename>) that you need to support your hardware.
196 </para></listitem>
197 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
198 changes to your BSP layer, there remains a few things
199 you need to do for the OpenEmbedded build system in order for it to create your image.
200 You need to get the build environment ready by sourcing an environment setup script
201 (i.e. <filename>oe-init-build-env</filename> or
202 <filename>oe-init-build-env-memres</filename>)
203 and you need to be sure two key configuration files are configured appropriately:
204 the <filename>conf/local.conf</filename> and the
205 <filename>conf/bblayers.conf</filename> file.
206 You must make the OpenEmbedded build system aware of your new layer.
207 See the
208 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
209 for information on how to let the build system know about your new layer.</para>
210 <para>The entire process for building an image is overviewed in the section
211 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
212 of the Yocto Project Quick Start.
213 You might want to reference this information.</para></listitem>
214 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
215 uses the BitBake tool to build images based on the type of image you want to create.
216 You can find more information about BitBake in the
217 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
218 </para>
219 <para>The build process supports several types of images to satisfy different needs.
220 See the
221 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
222 in the Yocto Project Reference Manual for information on
223 supported images.</para></listitem>
224 </orderedlist>
225 </para>
226
227 <para>
228 You can view a video presentation on "Building Custom Embedded Images with Yocto"
229 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
230 After going to the page, just search for "Embedded".
231 You can also find supplemental information in the
232 <ulink url='&YOCTO_DOCS_BSP_URL;'>
233 Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
234 Finally, there is a wiki page write up of the example also located
235 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
236 here</ulink> that you might find helpful.
237 </para>
238 </section>
239
240 <section id='modifying-the-kernel'>
241 <title><anchor id='kernel-spot' />Modifying the Kernel</title>
242
243 <para>
244 Kernel modification involves changing the Yocto Project kernel, which could involve changing
245 configuration options as well as adding new kernel recipes.
246 Configuration changes can be added in the form of configuration fragments, while recipe
247 modification comes through the kernel's <filename>recipes-kernel</filename> area
248 in a kernel layer you create.
249 </para>
250
251 <para>
252 The remainder of this section presents a high-level overview of the Yocto Project
253 kernel architecture and the steps to modify the kernel.
254 You can reference the
255 "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
256 for an example that changes the source code of the kernel.
257 For information on how to configure the kernel, see the
258 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
259 For more information on the kernel and on modifying the kernel, see the
260 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
261 </para>
262
263 <section id='kernel-overview'>
264 <title>Kernel Overview</title>
265
266 <para>
267 Traditionally, when one thinks of a patched kernel, they think of a base kernel
268 source tree and a fixed structure that contains kernel patches.
269 The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
270 generator.
271 By the end of this section, this analogy will become clearer.
272 </para>
273
274 <para>
275 You can find a web interface to the Yocto Project kernel source repositories at
276 <ulink url='&YOCTO_GIT_URL;'></ulink>.
277 If you look at the interface, you will see to the left a grouping of
278 Git repositories titled "Yocto Linux Kernel."
279 Within this group, you will find several kernels supported by
280 the Yocto Project:
281 <itemizedlist>
282 <listitem><para><emphasis>
283 <filename>linux-yocto-3.8</filename></emphasis> - The
284 stable Yocto Project kernel to use with the Yocto
285 Project Release 1.4. This kernel is based on the
286 Linux 3.8 released kernel.
287 </para></listitem>
288 <listitem><para><emphasis>
289 <filename>linux-yocto-3.10</filename></emphasis> - The
290 stable Yocto Project kernel to use with the Yocto
291 Project Release 1.5.
292 This kernel is based on the Linux 3.10 released kernel.
293 </para></listitem>
294 <listitem><para><emphasis>
295 <filename>linux-yocto-3.14</filename></emphasis> - The
296 stable Yocto Project kernel to use with the Yocto
297 Project Releases 1.6 and 1.7.
298 This kernel is based on the Linux 3.14 released kernel.
299 </para></listitem>
300 <listitem><para><emphasis>
301 <filename>linux-yocto-3.17</filename></emphasis> - An
302 additional Yocto Project kernel used with the Yocto
303 Project Release 1.7.
304 This kernel is based on the Linux 3.17 released kernel.
305 </para></listitem>
306 <listitem><para><emphasis>
307 <filename>linux-yocto-dev</filename></emphasis> - A
308 development kernel based on the latest upstream release
309 candidate available.
310 </para></listitem>
311 </itemizedlist>
312 </para>
313
314 <para>
315 The kernels are maintained using the Git revision control system
316 that structures them using the familiar "tree", "branch", and "leaf" scheme.
317 Branches represent diversions from general code to more specific code, while leaves
318 represent the end-points for a complete and unique kernel whose source files,
319 when gathered from the root of the tree to the leaf, accumulate to create the files
320 necessary for a specific piece of hardware and its features.
321 The following figure displays this concept:
322 <para>
323 <imagedata fileref="figures/kernel-overview-1.png"
324 width="6in" depth="6in" align="center" scale="100" />
325 </para>
326
327 <para>
328 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
329 where a supported base kernel is modified from the Linux kernel.
330 For example, this could be the branch point for the <filename>linux-yocto-3.4</filename>
331 kernel.
332 Thus, everything further to the right in the structure is based on the
333 <filename>linux-yocto-3.4</filename> kernel.
334 Branch points to the right in the figure represent where the
335 <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware
336 or types of kernels, such as real-time kernels.
337 Each leaf thus represents the end-point for a kernel designed to run on a specific
338 targeted device.
339 </para>
340
341 <para>
342 The overall result is a Git-maintained repository from which all the supported
343 kernel types can be derived for all the supported devices.
344 A big advantage to this scheme is the sharing of common features by keeping them in
345 "larger" branches within the tree.
346 This practice eliminates redundant storage of similar features shared among kernels.
347 </para>
348
349 <note>
350 Keep in mind the figure does not take into account all the supported Yocto
351 Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
352 Also keep in mind that this structure represents the Yocto Project source repositories
353 that are either pulled from during the build or established on the host development system
354 prior to the build by either cloning a particular kernel's Git repository or by
355 downloading and unpacking a tarball.
356 </note>
357
358 <para>
359 Upstream storage of all the available kernel source code is one thing, while
360 representing and using the code on your host development system is another.
361 Conceptually, you can think of the kernel source repositories as all the
362 source files necessary for all the supported kernels.
363 As a developer, you are just interested in the source files for the kernel on
364 which you are working.
365 And, furthermore, you need them available on your host system.
366 </para>
367
368 <para>
369 Kernel source code is available on your host system a couple of different
370 ways.
371 If you are working in the kernel all the time, you probably would want
372 to set up your own local Git repository of the kernel tree.
373 If you just need to make some patches to the kernel, you can access
374 temporary kernel source files that were extracted and used
375 during a build.
376 We will just talk about working with the temporary source code.
377 For more information on how to get kernel source code onto your
378 host system, see the
379 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
380 bulleted item earlier in the manual.
381 </para>
382
383 <para>
384 What happens during the build?
385 When you build the kernel on your development system, all files needed for the build
386 are taken from the source repositories pointed to by the
387 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
388 and gathered in a temporary work area
389 where they are subsequently used to create the unique kernel.
390 Thus, in a sense, the process constructs a local source tree specific to your
391 kernel to generate the new kernel image - a source generator if you will.
392 </para>
393 The following figure shows the temporary file structure
394 created on your host system when the build occurs.
395 This
396 <link linkend='build-directory'>Build Directory</link> contains all the
397 source files used during the build.
398 </para>
399
400 <para>
401 <imagedata fileref="figures/kernel-overview-2-generic.png"
402 width="6in" depth="5in" align="center" scale="100" />
403 </para>
404
405 <para>
406 Again, for additional information on the Yocto Project kernel's
407 architecture and its branching strategy, see the
408 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
409 You can also reference the
410 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
411 section for a detailed example that modifies the kernel.
412 </para>
413 </section>
414
415 <section id='kernel-modification-workflow'>
416 <title>Kernel Modification Workflow</title>
417
418 <para>
419 This illustration and the following list summarizes the kernel modification general workflow.
420 </para>
421
422 <para>
423 <imagedata fileref="figures/kernel-dev-flow.png"
424 width="6in" depth="5in" align="center" scalefit="1" />
425 </para>
426
427 <para>
428 <orderedlist>
429 <listitem><para><emphasis>Set up your host development system to support
430 development using the Yocto Project</emphasis>: See
431 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
432 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
433 in the Yocto Project Quick Start for requirements.</para></listitem>
434 <listitem><para><emphasis>Establish a local copy of project files on your
435 system</emphasis>: Having the <link linkend='source-directory'>Source
436 Directory</link> on your system gives you access to the build process and tools
437 you need.
438 For information on how to get these files, see the bulleted item
439 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
440 </para></listitem>
441 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
442 Temporary kernel source files are kept in the
443 <link linkend='build-directory'>Build Directory</link>
444 created by the
445 OpenEmbedded build system when you run BitBake.
446 If you have never built the kernel in which you are
447 interested, you need to run an initial build to
448 establish local kernel source files.</para>
449 <para>If you are building an image for the first time, you need to get the build
450 environment ready by sourcing an environment setup script
451 (i.e. <filename>oe-init-build-env</filename> or
452 <filename>oe-init-build-env-memres</filename>).
453 You also need to be sure two key configuration files
454 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
455 are configured appropriately.</para>
456 <para>The entire process for building an image is overviewed in the
457 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
458 section of the Yocto Project Quick Start.
459 You might want to reference this information.
460 You can find more information on BitBake in the
461 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
462 </para>
463 <para>The build process supports several types of images to satisfy different needs.
464 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
465 the Yocto Project Reference Manual for information on supported images.
466 </para></listitem>
467 <listitem><para><emphasis>Make changes to the kernel source code if
468 applicable</emphasis>: Modifying the kernel does not always mean directly
469 changing source files.
470 However, if you have to do this, you make the changes to the files in the
471 Build Directory.</para></listitem>
472 <listitem><para><emphasis>Make kernel configuration changes
473 if applicable</emphasis>:
474 If your situation calls for changing the kernel's configuration, you can
475 use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
476 to enable and disable kernel configurations.
477 Using the script lets you interactively set up kernel configurations.
478 Using <filename>menuconfig</filename> allows you to interactively develop and test the
479 configuration changes you are making to the kernel.
480 When saved, changes using <filename>menuconfig</filename> update the kernel's
481 <filename>.config</filename> file.
482 Try to resist the temptation of directly editing the <filename>.config</filename>
483 file found in the Build Directory at
484 <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
485 Doing so, can produce unexpected results when the OpenEmbedded build system
486 regenerates the configuration file.</para>
487 <para>Once you are satisfied with the configuration changes made using
488 <filename>menuconfig</filename>, you can directly compare the
489 <filename>.config</filename> file against a saved original and gather those
490 changes into a config fragment to be referenced from within the kernel's
491 <filename>.bbappend</filename> file.</para></listitem>
492 <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
493 Rebuilding the kernel image applies your changes.</para></listitem>
494 </orderedlist>
495 </para>
496 </section>
497 </section>
498</section>
499
500<section id='application-development-workflow'>
501 <title>Application Development Workflow</title>
502
503 <para>
504 Application development involves creating an application that you want
505 to run on your target hardware, which is running a kernel image created using the
506 OpenEmbedded build system.
507 The Yocto Project provides an
508 <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink>
509 and stand-alone
510 <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink>
511 that facilitate quick development and integration of your application into its runtime environment.
512 Using the ADT and toolchains, you can compile and link your application.
513 You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
514 If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE,
515 you can use an Eclipse Yocto Plug-in to
516 allow you to develop, deploy, and test your application all from within Eclipse.
517 </para>
518
519 <para>
520 While we strongly suggest using the ADT to develop your application, this option might not
521 be best for you.
522 If this is the case, you can still use pieces of the Yocto Project for your development process.
523 However, because the process can vary greatly, this manual does not provide detail on the process.
524 </para>
525
526 <section id='workflow-using-the-adt-and-eclipse'>
527 <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
528
529 <para>
530 To help you understand how application development works using the ADT, this section
531 provides an overview of the general development process and a detailed example of the process
532 as it is used from within the Eclipse IDE.
533 </para>
534
535 <para>
536 The following illustration and list summarize the application development general workflow.
537 </para>
538
539 <para>
540 <imagedata fileref="figures/app-dev-flow.png"
541 width="7in" depth="8in" align="center" scale="100" />
542 </para>
543
544 <para>
545 <orderedlist>
546 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
547 See
548 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
549 and
550 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
551 in the Yocto Project Reference Manual for requirements.
552 In particular, be sure your host system has the
553 <filename>xterm</filename> package installed.
554 </para></listitem>
555 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
556 You must have a target kernel image that has been built using the OpenEmbedded
557 build system.</para>
558 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
559 architecture and where you are going to run the image while you develop your application
560 (QEMU or real hardware), the area from which you get the image differs.
561 <itemizedlist>
562 <listitem><para>Download the image from
563 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
564 if your target architecture is supported and you are going to develop
565 and test your application on actual hardware.</para></listitem>
566 <listitem><para>Download the image from
567 <ulink url='&YOCTO_QEMU_DL_URL;'>
568 <filename>machines/qemu</filename></ulink> if your target architecture is supported
569 and you are going to develop and test your application using the QEMU
570 emulator.</para></listitem>
571 <listitem><para>Build your image if you cannot find a pre-built image that matches
572 your target architecture.
573 If your target architecture is similar to a supported architecture, you can
574 modify the kernel image before you build it.
575 See the
576 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
577 section for an example.</para></listitem>
578 </itemizedlist></para>
579 <para>For information on pre-built kernel image naming schemes for images
580 that can run on the QEMU emulator, see the
581 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
582 section in the Yocto Project Quick Start.</para></listitem>
583 <listitem><para><emphasis>Install the ADT</emphasis>:
584 The ADT provides a target-specific cross-development toolchain, the root filesystem,
585 the QEMU emulator, and other tools that can help you develop your application.
586 While it is possible to get these pieces separately, the ADT Installer provides an
587 easy, inclusive method.
588 You can get these pieces by running an ADT installer script, which is configurable.
589 For information on how to install the ADT, see the
590 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
591 section
592 in the Yocto Project Application Developer's Guide.</para></listitem>
593 <listitem><para><emphasis>If applicable, secure the target root filesystem
594 and the Cross-development toolchain</emphasis>:
595 If you choose not to install the ADT using the ADT Installer,
596 you need to find and download the appropriate root filesystem and
597 the cross-development toolchain.</para>
598 <para>You can find the tarballs for the root filesystem in the same area used
599 for the kernel image.
600 Depending on the type of image you are running, the root filesystem you need differs.
601 For example, if you are developing an application that runs on an image that
602 supports Sato, you need to get a root filesystem that supports Sato.</para>
603 <para>You can find the cross-development toolchains at
604 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
605 Be sure to get the correct toolchain for your development host and your
606 target architecture.
607 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
608 section in the Yocto Project Application Developer's Guide for information
609 and the
610 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
611 in the Yocto Project Quick Start for information on finding and installing
612 the correct toolchain based on your host development system and your target
613 architecture.
614 </para></listitem>
615 <listitem><para><emphasis>Create and build your application</emphasis>:
616 At this point, you need to have source files for your application.
617 Once you have the files, you can use the Eclipse IDE to import them and build the
618 project.
619 If you are not using Eclipse, you need to use the cross-development tools you have
620 installed to create the image.</para></listitem>
621 <listitem><para><emphasis>Deploy the image with the application</emphasis>:
622 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
623 QEMU through the project's preferences.
624 If you are not using the Eclipse IDE, then you need to deploy the application
625 to the hardware using other methods.
626 Or, if you are using QEMU, you need to use that tool and
627 load your image in for testing.
628 See the
629 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
630 chapter for information on using QEMU.
631 </para></listitem>
632 <listitem><para><emphasis>Test and debug the application</emphasis>:
633 Once your application is deployed, you need to test it.
634 Within the Eclipse IDE, you can use the debugging environment along with the
635 set of user-space tools installed along with the ADT to debug your application.
636 Of course, the same user-space tools are available separately if you choose
637 not to use the Eclipse IDE.</para></listitem>
638 </orderedlist>
639 </para>
640 </section>
641
642 <section id='adt-eclipse'>
643 <title>Working Within Eclipse</title>
644
645 <para>
646 The Eclipse IDE is a popular development environment and it fully
647 supports development using the Yocto Project.
648 <note>
649 This release of the Yocto Project supports both the Kepler
650 and Juno versions of the Eclipse IDE.
651 Thus, the following information provides setup information for
652 both versions.
653 </note>
654 </para>
655
656 <para>
657 When you install and configure the Eclipse Yocto Project Plug-in
658 into the Eclipse IDE, you maximize your Yocto Project experience.
659 Installing and configuring the Plug-in results in an environment
660 that has extensions specifically designed to let you more easily
661 develop software.
662 These extensions allow for cross-compilation, deployment, and
663 execution of your output into a QEMU emulation session as well as
664 actual target hardware.
665 You can also perform cross-debugging and profiling.
666 The environment also supports a suite of tools that allows you
667 to perform remote profiling, tracing, collection of power data,
668 collection of latency data, and collection of performance data.
669 </para>
670
671 <para>
672 This section describes how to install and configure the Eclipse IDE
673 Yocto Plug-in and how to use it to develop your application.
674 </para>
675
676 <section id='setting-up-the-eclipse-ide'>
677 <title>Setting Up the Eclipse IDE</title>
678
679 <para>
680 To develop within the Eclipse IDE, you need to do the following:
681 <orderedlist>
682 <listitem><para>Install the optimal version of the Eclipse
683 IDE.</para></listitem>
684 <listitem><para>Configure the Eclipse IDE.
685 </para></listitem>
686 <listitem><para>Install the Eclipse Yocto Plug-in.
687 </para></listitem>
688 <listitem><para>Configure the Eclipse Yocto Plug-in.
689 </para></listitem>
690 </orderedlist>
691 <note>
692 Do not install Eclipse from your distribution's package
693 repository.
694 Be sure to install Eclipse from the official Eclipse
695 download site as directed in the next section.
696 </note>
697 </para>
698
699 <section id='installing-eclipse-ide'>
700 <title>Installing the Eclipse IDE</title>
701
702 <para>
703 It is recommended that you have the Kepler 4.3.2 version of
704 the Eclipse IDE installed on your development system.
705 However, if you currently have the Juno 4.2 version
706 installed and you do not want to upgrade the IDE, you can
707 configure Juno to work with the Yocto Project.
708 </para>
709
710 <para>
711 If you do not have the Kepler 4.3.2 Eclipse IDE installed,
712 you can find the tarball at
713 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
714 From that site, choose the Eclipse Standard 4.3.2 version
715 particular to your development host.
716 This version contains the Eclipse Platform, the Java
717 Development Tools (JDT), and the Plug-in Development
718 Environment.
719 </para>
720
721 <para>
722 Once you have downloaded the tarball, extract it into a
723 clean directory.
724 For example, the following commands unpack and install the
725 downloaded Eclipse IDE tarball into a clean directory
726 using the default name <filename>eclipse</filename>:
727 <literallayout class='monospaced'>
728 $ cd ~
729 $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz
730 </literallayout>
731 </para>
732 </section>
733
734 <section id='configuring-the-eclipse-ide'>
735 <title>Configuring the Eclipse IDE</title>
736
737 <para>
738 This section presents the steps needed to configure the
739 Eclipse IDE.
740 </para>
741
742 <para>
743 Before installing and configuring the Eclipse Yocto Plug-in,
744 you need to configure the Eclipse IDE.
745 Follow these general steps:
746 <orderedlist>
747 <listitem><para>Start the Eclipse IDE.</para></listitem>
748 <listitem><para>Make sure you are in your Workbench and
749 select "Install New Software" from the "Help"
750 pull-down menu.</para></listitem>
751 <listitem><para>Select
752 <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
753 from the "Work with:" pull-down menu.
754 <note>
755 For Juno, select
756 <filename>Juno - &ECLIPSE_JUNO_URL;</filename>
757 </note>
758 </para></listitem>
759 <listitem><para>Expand the box next to "Linux Tools"
760 and select the
761 <filename>LTTng - Linux Tracing Toolkit</filename>
762 boxes.</para></listitem>
763 <listitem><para>Expand the box next to "Mobile and
764 Device Development" and select the following boxes:
765 <itemizedlist>
766 <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem>
767 <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
768 <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
769 <listitem><para><filename>Target Management Terminal</filename></para></listitem>
770 <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
771 <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
772 </itemizedlist></para></listitem>
773 <listitem><para>Expand the box next to "Programming
774 Languages" and select the
775 <filename>C/C++ Autotools Support</filename>
776 and <filename>C/C++ Development Tools</filename>
777 boxes.</para></listitem>
778 <listitem><para>Complete the installation and restart
779 the Eclipse IDE.</para></listitem>
780 </orderedlist>
781 </para>
782 </section>
783
784 <section id='installing-the-eclipse-yocto-plug-in'>
785 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
786
787 <para>
788 You can install the Eclipse Yocto Plug-in into the Eclipse
789 IDE one of two ways: use the Yocto Project's Eclipse
790 Update site to install the pre-built plug-in or build and
791 install the plug-in from the latest source code.
792 </para>
793
794 <section id='new-software'>
795 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
796
797 <para>
798 To install the Eclipse Yocto Plug-in from the update
799 site, follow these steps:
800 <orderedlist>
801 <listitem><para>Start up the Eclipse IDE.
802 </para></listitem>
803 <listitem><para>In Eclipse, select "Install New
804 Software" from the "Help" menu.
805 </para></listitem>
806 <listitem><para>Click "Add..." in the "Work with:"
807 area.</para></listitem>
808 <listitem><para>Enter
809 <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
810 in the URL field and provide a meaningful name
811 in the "Name" field.
812 <note>
813 If you are using Juno, use
814 <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename>
815 in the URL field.
816 </note></para></listitem>
817 <listitem><para>Click "OK" to have the entry added
818 to the "Work with:" drop-down list.
819 </para></listitem>
820 <listitem><para>Select the entry for the plug-in
821 from the "Work with:" drop-down list.
822 </para></listitem>
823 <listitem><para>Check the boxes next to
824 <filename>Yocto Project ADT Plug-in</filename>,
825 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
826 and
827 <filename>Yocto Project Documentation plug-in</filename>.
828 </para></listitem>
829 <listitem><para>Complete the remaining software
830 installation steps and then restart the Eclipse
831 IDE to finish the installation of the plug-in.
832 </para></listitem>
833 </orderedlist>
834 </para>
835 </section>
836
837 <section id='zip-file-method'>
838 <title>Installing the Plug-in Using the Latest Source Code</title>
839
840 <para>
841 To install the Eclipse Yocto Plug-in from the latest
842 source code, follow these steps:
843 <orderedlist>
844 <listitem><para>Be sure your development system
845 is not using OpenJDK to build the plug-in
846 by doing the following:
847 <orderedlist>
848 <listitem><para>Use the Oracle JDK.
849 If you don't have that, go to
850 <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
851 and download the appropriate tarball
852 for your development system and
853 extract it into your home directory.
854 </para></listitem>
855 <listitem><para>In the shell you are going
856 to do your work, export the location of
857 the Oracle Java as follows:
858 <literallayout class='monospaced'>
859 export PATH=~/jdk1.7.0_40/bin:$PATH
860 </literallayout></para></listitem>
861 </orderedlist></para></listitem>
862 <listitem><para>In the same shell, create a Git
863 repository with:
864 <literallayout class='monospaced'>
865 $ cd ~
866 $ git clone git://git.yoctoproject.org/eclipse-poky-kepler
867 </literallayout>
868 <note>
869 If you are using Juno, the repository is
870 located at
871 <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>.
872 </note>
873 For this example, the repository is named
874 <filename>~/eclipse-poky-kepler</filename>.
875 </para></listitem>
876 <listitem><para>Change to the directory where you
877 set up the Git repository:
878 <literallayout class='monospaced'>
879 $ cd ~/eclipse-poky-kepler
880 </literallayout></para></listitem>
881 <listitem><para>Be sure you are in the right branch
882 for your Git repository.
883 For this release set the branch to
884 <filename>&DISTRO_NAME;</filename>:
885 <literallayout class='monospaced'>
886 $ git checkout &DISTRO_NAME;
887 </literallayout></para></listitem>
888 <listitem><para>Change to the
889 <filename>scripts</filename>
890 directory within the Git repository:
891 <literallayout class='monospaced'>
892 $ cd scripts
893 </literallayout></para></listitem>
894 <listitem><para>Set up the local build environment
895 by running the setup script:
896 <literallayout class='monospaced'>
897 $ ./setup.sh
898 </literallayout></para></listitem>
899 <listitem><para>When the script finishes execution,
900 it prompts you with instructions on how to run
901 the <filename>build.sh</filename> script, which
902 is also in the <filename>scripts</filename>
903 directory of
904 the Git repository created earlier.
905 </para></listitem>
906 <listitem><para>Run the <filename>build.sh</filename> script
907 as directed.
908 Be sure to provide the name of the Git branch
909 along with the Yocto Project release you are
910 using.
911 Here is an example that uses the
912 <filename>&DISTRO_NAME;</filename> branch:
913 <literallayout class='monospaced'>
914 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
915 </literallayout>
916 After running the script, the file
917 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
918 is in the current directory.</para></listitem>
919 <listitem><para>If necessary, start the Eclipse IDE
920 and be sure you are in the Workbench.
921 </para></listitem>
922 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
923 </para></listitem>
924 <listitem><para>Click "Add".</para></listitem>
925 <listitem><para>Provide anything you want in the
926 "Name" field.</para></listitem>
927 <listitem><para>Click "Archive" and browse to the
928 ZIP file you built in step eight.
929 This ZIP file should not be "unzipped", and must
930 be the <filename>*archive.zip</filename> file
931 created by running the
932 <filename>build.sh</filename> script.
933 </para></listitem>
934 <listitem><para>Click through the "Okay" buttons.
935 </para></listitem>
936 <listitem><para>Check the boxes
937 in the installation window and complete
938 the installation.</para></listitem>
939 <listitem><para>Restart the Eclipse IDE if
940 necessary.</para></listitem>
941 </orderedlist>
942 </para>
943
944 <para>
945 At this point you should be able to configure the
946 Eclipse Yocto Plug-in as described in the
947 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
948 section.</para>
949 </section>
950 </section>
951
952 <section id='configuring-the-eclipse-yocto-plug-in'>
953 <title>Configuring the Eclipse Yocto Plug-in</title>
954
955 <para>
956 Configuring the Eclipse Yocto Plug-in involves setting the
957 Cross Compiler options and the Target options.
958 The configurations you choose become the default settings
959 for all projects.
960 You do have opportunities to change them later when
961 you configure the project (see the following section).
962 </para>
963
964 <para>
965 To start, you need to do the following from within the
966 Eclipse IDE:
967 <itemizedlist>
968 <listitem><para>Choose "Preferences" from the
969 "Windows" menu to display the Preferences Dialog.
970 </para></listitem>
971 <listitem><para>Click "Yocto Project ADT".
972 </para></listitem>
973 </itemizedlist>
974 </para>
975
976 <section id='configuring-the-cross-compiler-options'>
977 <title>Configuring the Cross-Compiler Options</title>
978
979 <para>
980 To configure the Cross Compiler Options, you must select
981 the type of toolchain, point to the toolchain, specify
982 the sysroot location, and select the target
983 architecture.
984 <itemizedlist>
985 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
986 Choose between
987 <filename>Standalone pre-built toolchain</filename>
988 and
989 <filename>Build system derived toolchain</filename>
990 for Cross Compiler Options.
991 <itemizedlist>
992 <listitem><para><emphasis>
993 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
994 Select this mode when you are using
995 a stand-alone cross-toolchain.
996 For example, suppose you are an
997 application developer and do not
998 need to build a target image.
999 Instead, you just want to use an
1000 architecture-specific toolchain on
1001 an existing kernel and target root
1002 filesystem.</para></listitem>
1003 <listitem><para><emphasis>
1004 <filename>Build System Derived Toolchain:</filename></emphasis>
1005 Select this mode if the
1006 cross-toolchain has been installed
1007 and built as part of the
1008 <link linkend='build-directory'>Build Directory</link>.
1009 When you select
1010 <filename>Build system derived toolchain</filename>,
1011 you are using the toolchain bundled
1012 inside the Build Directory.
1013 </para></listitem>
1014 </itemizedlist>
1015 </para></listitem>
1016 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
1017 If you are using a stand-alone pre-built
1018 toolchain, you should be pointing to where it is
1019 installed.
1020 If you used the ADT Installer script and
1021 accepted the default installation directory, the
1022 toolchain will be installed in the
1023 <filename>&YOCTO_ADTPATH_DIR;</filename>
1024 directory.
1025 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>"
1026 and
1027 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1028 in the Yocto Project Application Developer's
1029 Guide describe how to install a stand-alone
1030 cross-toolchain.</para>
1031 <para>If you are using a system-derived
1032 toolchain, the path you provide for the
1033 <filename>Toolchain Root Location</filename>
1034 field is the
1035 <link linkend='build-directory'>Build Directory</link>.
1036 See the
1037 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>"
1038 section in the Yocto Project Application
1039 Developer's Guide for information on how to
1040 install the toolchain into the Build
1041 Directory.</para></listitem>
1042 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
1043 This location is where the root filesystem for
1044 the target hardware resides.
1045 If you used the ADT Installer script and
1046 accepted the default installation directory,
1047 then the location is
1048 <filename>/opt/poky/&DISTRO;</filename>.
1049 Additionally, when you use the ADT Installer
1050 script, the same location is used for the QEMU
1051 user-space tools and the NFS boot process.
1052 </para>
1053 <para>If you used either of the other two
1054 methods to install the toolchain or did not
1055 accept the ADT Installer script's default
1056 installation directory, then the location of
1057 the sysroot filesystem depends on where you
1058 separately extracted and installed the
1059 filesystem.</para>
1060 <para>For information on how to install the
1061 toolchain and on how to extract and install the
1062 sysroot filesystem, see the
1063 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1064 section in the Yocto Project Application
1065 Developer's Guide.
1066 </para></listitem>
1067 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1068 The target architecture is the type of hardware
1069 you are going to use or emulate.
1070 Use the pull-down
1071 <filename>Target Architecture</filename> menu
1072 to make your selection.
1073 The pull-down menu should have the supported
1074 architectures.
1075 If the architecture you need is not listed in
1076 the menu, you will need to build the image.
1077 See the
1078 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1079 section of the Yocto Project Quick Start for
1080 more information.</para></listitem>
1081 </itemizedlist>
1082 </para>
1083 </section>
1084
1085 <section id='configuring-the-target-options'>
1086 <title>Configuring the Target Options</title>
1087
1088 <para>
1089 You can choose to emulate hardware using the QEMU
1090 emulator, or you can choose to run your image on actual
1091 hardware.
1092 <itemizedlist>
1093 <listitem><para><emphasis>QEMU:</emphasis>
1094 Select this option if you will be using the
1095 QEMU emulator.
1096 If you are using the emulator, you also need to
1097 locate the kernel and specify any custom
1098 options.</para>
1099 <para>If you selected
1100 <filename>Build system derived toolchain</filename>,
1101 the target kernel you built will be located in
1102 the Build Directory in
1103 <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
1104 directory.
1105 If you selected
1106 <filename>Standalone pre-built toolchain</filename>,
1107 the pre-built image you downloaded is located
1108 in the directory you specified when you
1109 downloaded the image.</para>
1110 <para>Most custom options are for advanced QEMU
1111 users to further customize their QEMU instance.
1112 These options are specified between paired
1113 angled brackets.
1114 Some options must be specified outside the
1115 brackets.
1116 In particular, the options
1117 <filename>serial</filename>,
1118 <filename>nographic</filename>, and
1119 <filename>kvm</filename> must all be outside the
1120 brackets.
1121 Use the <filename>man qemu</filename> command
1122 to get help on all the options and their use.
1123 The following is an example:
1124 <literallayout class='monospaced'>
1125 serial ‘&lt;-m 256 -full-screen&gt;’
1126 </literallayout></para>
1127 <para>
1128 Regardless of the mode, Sysroot is already
1129 defined as part of the Cross-Compiler Options
1130 configuration in the
1131 <filename>Sysroot Location:</filename> field.
1132 </para></listitem>
1133 <listitem><para><emphasis>External HW:</emphasis>
1134 Select this option if you will be using actual
1135 hardware.</para></listitem>
1136 </itemizedlist>
1137 </para>
1138
1139 <para>
1140 Click the "OK" to save your plug-in configurations.
1141 </para>
1142 </section>
1143 </section>
1144 </section>
1145
1146 <section id='creating-the-project'>
1147 <title>Creating the Project</title>
1148
1149 <para>
1150 You can create two types of projects: Autotools-based, or
1151 Makefile-based.
1152 This section describes how to create Autotools-based projects
1153 from within the Eclipse IDE.
1154 For information on creating Makefile-based projects in a
1155 terminal window, see the section
1156 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1157 in the Yocto Project Application Developer's Guide.
1158 <note>
1159 Do not use special characters in project names
1160 (e.g. spaces, underscores, etc.). Doing so can
1161 cause configuration to fail.
1162 </note>
1163 </para>
1164
1165 <para>
1166 To create a project based on a Yocto template and then display
1167 the source code, follow these steps:
1168 <orderedlist>
1169 <listitem><para>Select "Project" from the "File -> New" menu.
1170 </para></listitem>
1171 <listitem><para>Double click <filename>CC++</filename>.
1172 </para></listitem>
1173 <listitem><para>Double click <filename>C Project</filename>
1174 to create the project.</para></listitem>
1175 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.
1176 </para></listitem>
1177 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1178 This is an Autotools-based project based on a Yocto
1179 template.</para></listitem>
1180 <listitem><para>Put a name in the <filename>Project name:</filename>
1181 field.
1182 Do not use hyphens as part of the name.
1183 </para></listitem>
1184 <listitem><para>Click "Next".</para></listitem>
1185 <listitem><para>Add information in the
1186 <filename>Author</filename> and
1187 <filename>Copyright notice</filename> fields.
1188 </para></listitem>
1189 <listitem><para>Be sure the <filename>License</filename>
1190 field is correct.</para></listitem>
1191 <listitem><para>Click "Finish".</para></listitem>
1192 <listitem><para>If the "open perspective" prompt appears,
1193 click "Yes" so that you in the C/C++ perspective.
1194 </para></listitem>
1195 <listitem><para>The left-hand navigation pane shows your
1196 project.
1197 You can display your source by double clicking the
1198 project's source file.</para></listitem>
1199 </orderedlist>
1200 </para>
1201 </section>
1202
1203 <section id='configuring-the-cross-toolchains'>
1204 <title>Configuring the Cross-Toolchains</title>
1205
1206 <para>
1207 The earlier section,
1208 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
1209 sets up the default project configurations.
1210 You can override these settings for a given project by following
1211 these steps:
1212 <orderedlist>
1213 <listitem><para>Select "Change Yocto Project Settings" from
1214 the "Project" menu.
1215 This selection brings up the Yocto Project Settings
1216 Dialog and allows you to make changes specific to an
1217 individual project.</para>
1218 <para>By default, the Cross Compiler Options and Target
1219 Options for a project are inherited from settings you
1220 provided using the Preferences Dialog as described
1221 earlier in the
1222 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
1223 The Yocto Project Settings Dialog allows you to override
1224 those default settings for a given project.
1225 </para></listitem>
1226 <listitem><para>Make your configurations for the project
1227 and click "OK".
1228 If you are running the Juno version of Eclipse, you can
1229 skip down to the next section where you build the
1230 project.
1231 If you are not working with Juno, you need to reconfigure the
1232 project as described in the next step.
1233 </para></listitem>
1234 <listitem><para>Select "Reconfigure Project" from the
1235 "Project" menu.
1236 This selection reconfigures the project by running
1237 <filename>autogen.sh</filename> in the workspace for
1238 your project.
1239 The script also runs <filename>libtoolize</filename>,
1240 <filename>aclocal</filename>,
1241 <filename>autoconf</filename>,
1242 <filename>autoheader</filename>,
1243 <filename>automake --a</filename>, and
1244 <filename>./configure</filename>.
1245 Click on the "Console" tab beneath your source code to
1246 see the results of reconfiguring your project.
1247 </para></listitem>
1248 </orderedlist>
1249 </para>
1250 </section>
1251
1252 <section id='building-the-project'>
1253 <title>Building the Project</title>
1254
1255 <para>
1256 To build the project in Juno, right click on the project in
1257 the navigator pane and select "Build Project".
1258 If you are not running Juno, select "Build Project" from the
1259 "Project" menu.
1260 The console should update and you can note the cross-compiler
1261 you are using.
1262 </para>
1263 </section>
1264
1265 <section id='starting-qemu-in-user-space-nfs-mode'>
1266 <title>Starting QEMU in User-Space NFS Mode</title>
1267
1268 <para>
1269 To start the QEMU emulator from within Eclipse, follow these
1270 steps:
1271 <note>
1272 See the
1273 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1274 chapter for more information on using QEMU.
1275 </note>
1276 <orderedlist>
1277 <listitem><para>Expose and select "External Tools" from
1278 the "Run" menu.
1279 Your image should appear as a selectable menu item.
1280 </para></listitem>
1281 <listitem><para>Select your image from the menu to launch
1282 the emulator in a new window.</para></listitem>
1283 <listitem><para>If needed, enter your host root password in
1284 the shell window at the prompt.
1285 This sets up a <filename>Tap 0</filename> connection
1286 needed for running in user-space NFS mode.
1287 </para></listitem>
1288 <listitem><para>Wait for QEMU to launch.</para></listitem>
1289 <listitem><para>Once QEMU launches, you can begin operating
1290 within that environment.
1291 For example, you could determine the IP Address
1292 for the user-space NFS by using the
1293 <filename>ifconfig</filename> command.</para></listitem>
1294 </orderedlist>
1295 </para>
1296 </section>
1297
1298 <section id='deploying-and-debugging-the-application'>
1299 <title>Deploying and Debugging the Application</title>
1300
1301 <para>
1302 Once the QEMU emulator is running the image, you can deploy
1303 your application using the Eclipse IDE and then use
1304 the emulator to perform debugging.
1305 Follow these steps to deploy the application.
1306 <orderedlist>
1307 <listitem><para>Select "Debug Configurations..." from the
1308 "Run" menu.</para></listitem>
1309 <listitem><para>In the left area, expand
1310 <filename>C/C++Remote Application</filename>.
1311 </para></listitem>
1312 <listitem><para>Locate your project and select it to bring
1313 up a new tabbed view in the Debug Configurations Dialog.
1314 </para></listitem>
1315 <listitem><para>Enter the absolute path into which you want
1316 to deploy the application.
1317 Use the "Remote Absolute File Path for
1318 C/C++Application:" field.
1319 For example, enter
1320 <filename>/usr/bin/&lt;programname&gt;</filename>.
1321 </para></listitem>
1322 <listitem><para>Click on the "Debugger" tab to see the
1323 cross-tool debugger you are using.</para></listitem>
1324 <listitem><para>Click on the "Main" tab.</para></listitem>
1325 <listitem><para>Create a new connection to the QEMU instance
1326 by clicking on "new".</para></listitem>
1327 <listitem><para>Select <filename>TCF</filename>, which means
1328 Target Communication Framework.</para></listitem>
1329 <listitem><para>Click "Next".</para></listitem>
1330 <listitem><para>Clear out the "host name" field and enter
1331 the IP Address determined earlier.</para></listitem>
1332 <listitem><para>Click "Finish" to close the
1333 New Connections Dialog.</para></listitem>
1334 <listitem><para>Use the drop-down menu now in the
1335 "Connection" field and pick the IP Address you entered.
1336 </para></listitem>
1337 <listitem><para>Click "Run" to bring up a login screen
1338 and login.</para></listitem>
1339 <listitem><para>Accept the debug perspective.
1340 </para></listitem>
1341 </orderedlist>
1342 </para>
1343 </section>
1344
1345 <section id='running-user-space-tools'>
1346 <title>Running User-Space Tools</title>
1347
1348 <para>
1349 As mentioned earlier in the manual, several tools exist that
1350 enhance your development experience.
1351 These tools are aids in developing and debugging applications
1352 and images.
1353 You can run these user-space tools from within the Eclipse
1354 IDE through the "YoctoTools" menu.
1355 </para>
1356
1357 <para>
1358 Once you pick a tool, you need to configure it for the remote
1359 target.
1360 Every tool needs to have the connection configured.
1361 You must select an existing TCF-based RSE connection to the
1362 remote target.
1363 If one does not exist, click "New" to create one.
1364 </para>
1365
1366 <para>
1367 Here are some specifics about the remote tools:
1368 <itemizedlist>
1369 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
1370 Selecting this tool causes the
1371 <filename>oprofile-server</filename> on the remote
1372 target to launch on the local host machine.
1373 The <filename>oprofile-viewer</filename> must be
1374 installed on the local host machine and the
1375 <filename>oprofile-server</filename> must be installed
1376 on the remote target, respectively, in order to use.
1377 You must compile and install the
1378 <filename>oprofile-viewer</filename> from the source
1379 code on your local host machine.
1380 Furthermore, in order to convert the target's sample
1381 format data into a form that the host can use, you must
1382 have OProfile version 0.9.4 or greater installed on the
1383 host.</para>
1384 <para>You can locate both the viewer and server from
1385 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1386 You can also find more information on setting up and
1387 using this tool in the
1388 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
1389 section of the Yocto Project Profiling and Tracing
1390 Manual.
1391 <note>The <filename>oprofile-server</filename> is
1392 installed by default on the
1393 <filename>core-image-sato-sdk</filename> image.</note>
1394 </para></listitem>
1395 <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
1396 Selecting this tool transfers the remote target's
1397 <filename>Lttng</filename> tracing data back to the
1398 local host machine and uses the Lttng Eclipse plug-in
1399 to graphically display the output.
1400 For information on how to use Lttng to trace an
1401 application,
1402 see <ulink url='http://lttng.org/documentation'></ulink>
1403 and the
1404 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1405 section, which is in the Yocto Project Profiling and
1406 Tracing Manual.
1407 <note>Do not use
1408 <filename>Lttng-user space (legacy)</filename> tool.
1409 This tool no longer has any upstream support.</note>
1410 </para>
1411 <para>Before you use the
1412 <filename>Lttng2.0 ust trace import</filename> tool,
1413 you need to setup the Lttng Eclipse plug-in and create a
1414 Tracing project.
1415 Do the following:
1416 <orderedlist>
1417 <listitem><para>Select "Open Perspective" from the
1418 "Window" menu and then select "Tracing".
1419 </para></listitem>
1420 <listitem><para>Click "OK" to change the Eclipse
1421 perspective into the Tracing perspective.
1422 </para></listitem>
1423 <listitem><para>Create a new Tracing project by
1424 selecting "Project" from the "File -> New" menu.
1425 </para></listitem>
1426 <listitem><para>Choose "Tracing Project" from the
1427 "Tracing" menu.
1428 </para></listitem>
1429 <listitem><para>Generate your tracing data on the
1430 remote target.</para></listitem>
1431 <listitem><para>Select "Lttng2.0 ust trace import"
1432 from the "Yocto Project Tools" menu to
1433 start the data import process.</para></listitem>
1434 <listitem><para>Specify your remote connection name.
1435 </para></listitem>
1436 <listitem><para>For the Ust directory path, specify
1437 the location of your remote tracing data.
1438 Make sure the location ends with
1439 <filename>ust</filename> (e.g.
1440 <filename>/usr/mysession/ust</filename>).
1441 </para></listitem>
1442 <listitem><para>Click "OK" to complete the import
1443 process.
1444 The data is now in the local tracing project
1445 you created.</para></listitem>
1446 <listitem><para>Right click on the data and then use
1447 the menu to Select "Generic CTF Trace" from the
1448 "Trace Type... -> Common Trace Format" menu to
1449 map the tracing type.</para></listitem>
1450 <listitem><para>Right click the mouse and select
1451 "Open" to bring up the Eclipse Lttng Trace
1452 Viewer so you view the tracing data.
1453 </para></listitem>
1454 </orderedlist></para></listitem>
1455 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1456 Selecting this tool runs PowerTOP on the remote target
1457 machine and displays the results in a new view called
1458 PowerTOP.</para>
1459 <para>The "Time to gather data(sec):" field is the time
1460 passed in seconds before data is gathered from the
1461 remote target for analysis.</para>
1462 <para>The "show pids in wakeups list:" field corresponds
1463 to the <filename>-p</filename> argument passed to
1464 <filename>PowerTOP</filename>.</para></listitem>
1465 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1466 LatencyTOP identifies system latency, while
1467 Perf monitors the system's performance counter
1468 registers.
1469 Selecting either of these tools causes an RSE terminal
1470 view to appear from which you can run the tools.
1471 Both tools refresh the entire screen to display results
1472 while they run.
1473 For more information on setting up and using
1474 <filename>perf</filename>, see the
1475 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1476 section in the Yocto Project Profiling and Tracing
1477 Manual.
1478 </para></listitem>
1479 </itemizedlist>
1480 </para>
1481 </section>
1482
1483 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1484 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1485
1486 <para>
1487 Within the Eclipse IDE, you can create a Yocto BitBake Commander
1488 project, edit the <link linkend='metadata'>Metadata</link>, and
1489 then use
1490 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE.
1491 </para>
1492
1493 <section id='creating-the-yocto-bitbake-commander-project'>
1494 <title>Creating the Yocto BitBake Commander Project</title>
1495
1496 <para>
1497 To create a Yocto BitBake Commander project, follow these
1498 steps:
1499 <orderedlist>
1500 <listitem><para>Select "Other" from the
1501 "Window -> Open Perspective" menu
1502 and then choose "Bitbake Commander".
1503 </para></listitem>
1504 <listitem><para>Click "OK" to change the perspective to
1505 Bitbake Commander.</para></listitem>
1506 <listitem><para>Select "Project" from the "File -> New"
1507 menu to create a new Yocto
1508 Bitbake Commander project.</para></listitem>
1509 <listitem><para>Choose "New Yocto Project" from the
1510 "Yocto Project Bitbake Commander" menu and click
1511 "Next".</para></listitem>
1512 <listitem><para>Enter the Project Name and choose the
1513 Project Location.
1514 The Yocto project's Metadata files will be put under
1515 the directory
1516 <filename><replaceable>project_location</replaceable>/<replaceable>project_name</replaceable></filename>.
1517 If that directory does not exist, you need to check
1518 the "Clone from Yocto Git Repository" box, which
1519 would execute a <filename>git clone</filename>
1520 command to get the project's Metadata files.
1521 <note>
1522 Do not specify your BitBake Commander project
1523 location as your Eclipse workspace.
1524 Doing so causes an error indicating that the
1525 current project overlaps the location of
1526 another project.
1527 This error occurs even if no such project exits.
1528 </note></para></listitem>
1529 <listitem><para>Select <filename>Finish</filename> to
1530 create the project.</para></listitem>
1531 </orderedlist>
1532 </para>
1533 </section>
1534
1535 <section id='editing-the-metadata'>
1536 <title>Editing the Metadata</title>
1537
1538 <para>
1539 After you create the Yocto Bitbake Commander project, you
1540 can modify the <link linkend='metadata'>Metadata</link>
1541 files by opening them in the project.
1542 When editing recipe files (<filename>.bb</filename> files),
1543 you can view BitBake variable values and information by
1544 hovering the mouse pointer over the variable name and
1545 waiting a few seconds.
1546 </para>
1547
1548 <para>
1549 To edit the Metadata, follow these steps:
1550 <orderedlist>
1551 <listitem><para>Select your Yocto Bitbake Commander
1552 project.</para></listitem>
1553 <listitem><para>Select "BitBake Recipe" from the
1554 "File -> New -> Yocto BitBake Commander" menu
1555 to open a new recipe wizard.</para></listitem>
1556 <listitem><para>Point to your source by filling in the
1557 "SRC_URL" field.
1558 For example, you can add a recipe to your
1559 <link linkend='source-directory'>Source Directory</link>
1560 by defining "SRC_URL" as follows:
1561 <literallayout class='monospaced'>
1562 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1563 </literallayout></para></listitem>
1564 <listitem><para>Click "Populate" to calculate the
1565 archive md5, sha256, license checksum values and to
1566 auto-generate the recipe filename.</para></listitem>
1567 <listitem><para>Fill in the "Description" field.
1568 </para></listitem>
1569 <listitem><para>Be sure values for all required
1570 fields exist.</para></listitem>
1571 <listitem><para>Click "Finish".</para></listitem>
1572 </orderedlist>
1573 </para>
1574 </section>
1575
1576 <section id='biding-and-customizing-the-image-using-hob'>
1577 <title>Building and Customizing the Image Using Hob</title>
1578
1579 <para>
1580 To build and customize the image using Hob from within the
1581 Eclipse IDE, follow these steps:
1582 <orderedlist>
1583 <listitem><para>Select your Yocto Bitbake Commander
1584 project.</para></listitem>
1585 <listitem><para>Select "Launch Hob" from the "Project"
1586 menu.</para></listitem>
1587 <listitem><para>Enter the
1588 <link linkend='build-directory'>Build Directory</link>
1589 where you want to put your final images.
1590 </para></listitem>
1591 <listitem><para>Click "OK" to launch Hob.
1592 </para></listitem>
1593 <listitem><para>Use Hob to customize and build your own
1594 images.
1595 For information on Hob, see the
1596 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink>
1597 on the Yocto Project website.</para></listitem>
1598 </orderedlist>
1599 </para>
1600 </section>
1601 </section>
1602 </section>
1603
1604 <section id='workflow-using-stand-alone-cross-development-toolchains'>
1605 <title>Workflow Using Stand-Alone Cross-Development Toolchains</title>
1606
1607 <para>
1608 If you want to develop an application without prior installation
1609 of the ADT, you still can employ the
1610 <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>,
1611 the QEMU emulator, and a number of supported target image files.
1612 You just need to follow these general steps:
1613 <orderedlist>
1614 <listitem><para><emphasis>Install the cross-development
1615 toolchain for your target hardware:</emphasis>
1616 For information on how to install the toolchain, see the
1617 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1618 section in the Yocto Project Application Developer's
1619 Guide.</para></listitem>
1620 <listitem><para><emphasis>Download the Target Image:</emphasis>
1621 The Yocto Project supports several target architectures
1622 and has many pre-built kernel images and root filesystem
1623 images.</para>
1624 <para>If you are going to develop your application on
1625 hardware, go to the
1626 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
1627 download area and choose a target machine area
1628 from which to download the kernel image and root filesystem.
1629 This download area could have several files in it that
1630 support development using actual hardware.
1631 For example, the area might contain
1632 <filename>.hddimg</filename> files that combine the
1633 kernel image with the filesystem, boot loaders, and
1634 so forth.
1635 Be sure to get the files you need for your particular
1636 development process.</para>
1637 <para>If you are going to develop your application and
1638 then run and test it using the QEMU emulator, go to the
1639 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
1640 download area.
1641 From this area, go down into the directory for your
1642 target architecture (e.g. <filename>qemux86_64</filename>
1643 for an <trademark class='registered'>Intel</trademark>-based
1644 64-bit architecture).
1645 Download kernel, root filesystem, and any other files you
1646 need for your process.
1647 <note>In order to use the root filesystem in QEMU, you
1648 need to extract it.
1649 See the
1650 "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
1651 section for information on how to extract the root
1652 filesystem.</note></para></listitem>
1653 <listitem><para><emphasis>Develop and Test your
1654 Application:</emphasis> At this point, you have the tools
1655 to develop your application.
1656 If you need to separately install and use the QEMU
1657 emulator, you can go to
1658 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
1659 to download and learn about the emulator.
1660 You can see the
1661 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1662 chapter for information on using QEMU within the Yocto
1663 Project.</para></listitem>
1664 </orderedlist>
1665 </para>
1666 </section>
1667</section>
1668
1669<section id="modifying-temporary-source-code">
1670 <title>Modifying Temporary Source Code</title>
1671
1672 <para>
1673 You might
1674 find it helpful during development to modify the temporary source code used by recipes
1675 to build packages.
1676 For example, suppose you are developing a patch and you need to experiment a bit
1677 to figure out your solution.
1678 After you have initially built the package, you can iteratively tweak the
1679 source code, which is located in the
1680 <link linkend='build-directory'>Build Directory</link>, and then
1681 you can force a re-compile and quickly test your altered code.
1682 Once you settle on a solution, you can then preserve your changes in the form of
1683 patches.
1684 You can accomplish these steps all within either a
1685 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1686 <link linkend='git'>Git</link> workflow.
1687 </para>
1688
1689 <section id='finding-the-temporary-source-code'>
1690 <title>Finding the Temporary Source Code</title>
1691
1692 <para>
1693 During a build, the unpacked temporary source code used by recipes
1694 to build packages is available in the Build Directory as
1695 defined by the
1696 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
1697 Below is the default value for the <filename>S</filename> variable as defined in the
1698 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1699 <link linkend='source-directory'>Source Directory</link>:
1700 <literallayout class='monospaced'>
1701 S = "${WORKDIR}/${BP}"
1702 </literallayout>
1703 You should be aware that many recipes override the <filename>S</filename> variable.
1704 For example, recipes that fetch their source from Git usually set
1705 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1706 <note>
1707 The
1708 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
1709 represents the base recipe name, which consists of the name and version:
1710 <literallayout class='monospaced'>
1711 BP = "${BPN}-${PV}"
1712 </literallayout>
1713 </note>
1714 </para>
1715
1716 <para>
1717 The path to the work directory for the recipe
1718 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
1719 is defined as follows:
1720 <literallayout class='monospaced'>
1721 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1722 </literallayout>
1723 The actual directory depends on several things:
1724 <itemizedlist>
1725 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1726 The top-level build output directory</listitem>
1727 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1728 The target system identifier</listitem>
1729 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1730 The recipe name</listitem>
1731 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1732 The epoch - (if
1733 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1734 is not specified, which is usually the case for most
1735 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1736 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1737 The recipe version</listitem>
1738 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1739 The recipe revision</listitem>
1740 </itemizedlist>
1741 </para>
1742
1743 <para>
1744 As an example, assume a Source Directory top-level folder
1745 name <filename>poky</filename>, a default Build Directory at
1746 <filename>poky/build</filename>, and a
1747 <filename>qemux86-poky-linux</filename> machine target
1748 system.
1749 Furthermore, suppose your recipe is named
1750 <filename>foo_1.3.0.bb</filename>.
1751 In this case, the work directory the build system uses to
1752 build the package would be as follows:
1753 <literallayout class='monospaced'>
1754 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1755 </literallayout>
1756 </para>
1757
1758 <para>
1759 Now that you know where to locate the directory that has the temporary source code,
1760 you can use a Quilt or Git workflow to make your edits, test the changes,
1761 and preserve the changes in the form of patches.
1762 </para>
1763 </section>
1764
1765 <section id="using-a-quilt-workflow">
1766 <title>Using a Quilt Workflow</title>
1767
1768 <para>
1769 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
1770 is a powerful tool that allows you to capture source code changes without having
1771 a clean source tree.
1772 This section outlines the typical workflow you can use to modify temporary source code,
1773 test changes, and then preserve the changes in the form of a patch all using Quilt.
1774 </para>
1775
1776 <para>
1777 Follow these general steps:
1778 <orderedlist>
1779 <listitem><para><emphasis>Find the Source Code:</emphasis>
1780 The temporary source code used by the OpenEmbedded build system is kept in the
1781 Build Directory.
1782 See the
1783 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1784 section to learn how to locate the directory that has the temporary source code for a
1785 particular package.</para></listitem>
1786 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1787 You need to be in the directory that has the temporary source code.
1788 That directory is defined by the
1789 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1790 variable.</para></listitem>
1791 <listitem><para><emphasis>Create a New Patch:</emphasis>
1792 Before modifying source code, you need to create a new patch.
1793 To create a new patch file, use <filename>quilt new</filename> as below:
1794 <literallayout class='monospaced'>
1795 $ quilt new my_changes.patch
1796 </literallayout></para></listitem>
1797 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1798 After creating the patch, you need to notify Quilt about the files
1799 you plan to edit.
1800 You notify Quilt by adding the files to the patch you just created:
1801 <literallayout class='monospaced'>
1802 $ quilt add file1.c file2.c file3.c
1803 </literallayout>
1804 </para></listitem>
1805 <listitem><para><emphasis>Edit the Files:</emphasis>
1806 Make your changes in the temporary source code to the files you added
1807 to the patch.</para></listitem>
1808 <listitem><para><emphasis>Test Your Changes:</emphasis>
1809 Once you have modified the source code, the easiest way to
1810 your changes is by calling the
1811 <filename>do_compile</filename> task as shown in the
1812 following example:
1813 <literallayout class='monospaced'>
1814 $ bitbake -c compile -f <replaceable>name_of_package</replaceable>
1815 </literallayout>
1816 The <filename>-f</filename> or <filename>--force</filename>
1817 option forces the specified task to execute.
1818 If you find problems with your code, you can just keep editing and
1819 re-testing iteratively until things work as expected.
1820 <note>All the modifications you make to the temporary source code
1821 disappear once you run the
1822 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>
1823 or
1824 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>
1825 tasks using BitBake (i.e.
1826 <filename>bitbake -c clean <replaceable>name_of_package</replaceable></filename>
1827 and
1828 <filename>bitbake -c cleanall <replaceable>name_of_package</replaceable></filename>).
1829 Modifications will also disappear if you use the <filename>rm_work</filename>
1830 feature as described in the
1831 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1832 section of the Yocto Project Quick Start.
1833 </note></para></listitem>
1834 <listitem><para><emphasis>Generate the Patch:</emphasis>
1835 Once your changes work as expected, you need to use Quilt to generate the final patch that
1836 contains all your modifications.
1837 <literallayout class='monospaced'>
1838 $ quilt refresh
1839 </literallayout>
1840 At this point, the <filename>my_changes.patch</filename> file has all your edits made
1841 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1842 <filename>file3.c</filename> files.</para>
1843 <para>You can find the resulting patch file in the <filename>patches/</filename>
1844 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1845 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1846 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1847 which you can create in the same directory that holds the recipe
1848 (<filename>.bb</filename>) file or the
1849 append (<filename>.bbappend</filename>) file.
1850 Placing the patch here guarantees that the OpenEmbedded build system will find
1851 the patch.
1852 Next, add the patch into the
1853 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1854 of the recipe.
1855 Here is an example:
1856 <literallayout class='monospaced'>
1857 SRC_URI += "file://my_changes.patch"
1858 </literallayout></para></listitem>
1859 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1860 Finally, don't forget to 'bump' the
1861 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1862 value in the recipe since the resulting packages have changed.</para></listitem>
1863 </orderedlist>
1864 </para> </section>
1865
1866 <section id='using-a-git-workflow'>
1867 <title>Using a Git Workflow</title>
1868 <para>
1869 Git is an even more powerful tool that allows you to capture source code changes without having
1870 a clean source tree.
1871 This section outlines the typical workflow you can use to modify temporary source code,
1872 test changes, and then preserve the changes in the form of a patch all using Git.
1873 For general information on Git as it is used in the Yocto Project, see the
1874 "<link linkend='git'>Git</link>" section.
1875 </para>
1876
1877 <note>
1878 This workflow uses Git only for its ability to manage local changes to the source code
1879 and produce patches independent of any version control system used with the Yocto Project.
1880 </note>
1881
1882 <para>
1883 Follow these general steps:
1884 <orderedlist>
1885 <listitem><para><emphasis>Find the Source Code:</emphasis>
1886 The temporary source code used by the OpenEmbedded build system is kept in the
1887 Build Directory.
1888 See the
1889 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1890 section to learn how to locate the directory that has the temporary source code for a
1891 particular package.</para></listitem>
1892 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1893 You need to be in the directory that has the temporary source code.
1894 That directory is defined by the
1895 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1896 variable.</para></listitem>
1897 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
1898 If the recipe you are working with does not use a Git fetcher,
1899 you need to set up a Git repository as follows:
1900 <literallayout class='monospaced'>
1901 $ git init
1902 $ git add *
1903 $ git commit -m "initial revision"
1904 </literallayout>
1905 The above Git commands initialize a Git repository that is based on the
1906 files in your current working directory, stage all the files, and commit
1907 the files.
1908 At this point, your Git repository is aware of all the source code files.
1909 Any edits you now make to files can be committed later and will be tracked by
1910 Git.</para></listitem>
1911 <listitem><para><emphasis>Edit the Files:</emphasis>
1912 Make your changes to the temporary source code.</para></listitem>
1913 <listitem><para><emphasis>Test Your Changes:</emphasis>
1914 Once you have modified the source code, the easiest way
1915 to test your changes is by calling the
1916 <filename>do_compile</filename> task as shown in the
1917 following example:
1918 <literallayout class='monospaced'>
1919 $ bitbake -c compile -f <replaceable>name_of_package</replaceable>
1920 </literallayout>
1921 The <filename>-f</filename> or <filename>--force</filename>
1922 option forces the specified task to execute.
1923 If you find problems with your code, you can just keep editing and
1924 re-testing iteratively until things work as expected.
1925 <note>All the modifications you make to the temporary source code
1926 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
1927 or <filename>-c cleanall</filename> with BitBake for the package.
1928 Modifications will also disappear if you use the <filename>rm_work</filename>
1929 feature as described in the
1930 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1931 section of the Yocto Project Quick Start.
1932 </note></para></listitem>
1933 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1934 Use the <filename>git status</filename> command to see what files you have actually edited.
1935 The ability to have Git track the files you have changed is an advantage that this
1936 workflow has over the Quilt workflow.
1937 Here is the Git command to list your changed files:
1938 <literallayout class='monospaced'>
1939 $ git status
1940 </literallayout></para></listitem>
1941 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1942 Use the <filename>git add</filename> command to stage the changed files so they
1943 can be committed as follows:
1944 <literallayout class='monospaced'>
1945 $ git add file1.c file2.c file3.c
1946 </literallayout></para></listitem>
1947 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1948 Use the <filename>git commit</filename> command to commit the changes to the
1949 local repository.
1950 Once you have committed the files, you can use the <filename>git log</filename>
1951 command to see your changes:
1952 <literallayout class='monospaced'>
1953 $ git commit -m "<replaceable>commit-summary-message</replaceable>"
1954 $ git log
1955 </literallayout>
1956 <note>The name of the patch file created in the next step is based on your
1957 <replaceable>commit-summary-message</replaceable>.</note></para></listitem>
1958 <listitem><para><emphasis>Generate the Patch:</emphasis>
1959 Once the changes are committed, use the <filename>git format-patch</filename>
1960 command to generate a patch file:
1961 <literallayout class='monospaced'>
1962 $ git format-patch -1
1963 </literallayout>
1964 Specifying "-1" causes Git to generate the
1965 patch file for the most recent commit.</para>
1966 <para>At this point, the patch file has all your edits made
1967 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1968 <filename>file3.c</filename> files.
1969 You can find the resulting patch file in the current directory and it
1970 is named according to the <filename>git commit</filename> summary line.
1971 The patch file ends with <filename>.patch</filename>.</para></listitem>
1972 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1973 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1974 which you can create in the same directory that holds the recipe
1975 (<filename>.bb</filename>) file or the
1976 append (<filename>.bbappend</filename>) file.
1977 Placing the patch here guarantees that the OpenEmbedded build system will find
1978 the patch.
1979 Next, add the patch into the
1980 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1981 of the recipe.
1982 Here is an example:
1983 <literallayout class='monospaced'>
1984 SRC_URI += "file://0001-<replaceable>commit-summary-message</replaceable>.patch"
1985 </literallayout></para></listitem>
1986 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1987 Finally, don't forget to 'bump' the
1988 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1989 value in the recipe since the resulting packages have changed.</para></listitem>
1990 </orderedlist>
1991 </para>
1992 </section>
1993</section>
1994
1995<section id='image-development-using-hob'>
1996 <title>Image Development Using Hob</title>
1997
1998 <para>
1999 The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the
2000 OpenEmbedded build system, which is based on BitBake.
2001 You can use the Hob to build custom operating system images within the Yocto Project build environment.
2002 Hob simply provides a friendly interface over the build system used during development.
2003 In other words, building images with the Hob lets you take care of common build tasks more easily.
2004 </para>
2005
2006 <para>
2007 For a better understanding of Hob, see the project page at
2008 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink>
2009 on the Yocto Project website.
2010 If you follow the "Documentation" link from the Hob page, you will
2011 find a short introductory training video on Hob.
2012 The following lists some features of Hob:
2013 <itemizedlist>
2014 <listitem><para>You can setup and run Hob using these commands:
2015 <literallayout class='monospaced'>
2016 $ source oe-init-build-env
2017 $ hob
2018 </literallayout></para></listitem>
2019 <listitem><para>You can set the
2020 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2021 for which you are building the image.</para></listitem>
2022 <listitem><para>You can modify various policy settings such as the
2023 package format with which to build,
2024 the parallelism BitBake uses, whether or not to build an
2025 external toolchain, and which host to build against.
2026 </para></listitem>
2027 <listitem><para>You can manage
2028 <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
2029 <listitem><para>You can select a base image and then add extra packages for your custom build.
2030 </para></listitem>
2031 <listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
2032 </itemizedlist>
2033 </para>
2034</section>
2035
2036<section id="platdev-appdev-devshell">
2037 <title>Using a Development Shell</title>
2038
2039 <para>
2040 When debugging certain commands or even when just editing packages,
2041 <filename>devshell</filename> can be a useful tool.
2042 When you invoke <filename>devshell</filename>, source files are
2043 extracted into your working directory and patches are applied.
2044 Then, a new terminal is opened and you are placed in the working directory.
2045 In the new terminal, all the OpenEmbedded build-related environment variables are
2046 still defined so you can use commands such as <filename>configure</filename> and
2047 <filename>make</filename>.
2048 The commands execute just as if the OpenEmbedded build system were executing them.
2049 Consequently, working this way can be helpful when debugging a build or preparing
2050 software to be used with the OpenEmbedded build system.
2051 </para>
2052
2053 <para>
2054 Following is an example that uses <filename>devshell</filename> on a target named
2055 <filename>matchbox-desktop</filename>:
2056 <literallayout class='monospaced'>
2057 $ bitbake matchbox-desktop -c devshell
2058 </literallayout>
2059 </para>
2060
2061 <para>
2062 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
2063 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
2064 variable controls what type of shell is opened.
2065 </para>
2066
2067 <para>
2068 For spawned terminals, the following occurs:
2069 <itemizedlist>
2070 <listitem><para>The <filename>PATH</filename> variable includes the
2071 cross-toolchain.</para></listitem>
2072 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
2073 <filename>.pc</filename> files.</para></listitem>
2074 <listitem><para>The <filename>configure</filename> command finds the
2075 Yocto Project site files as well as any other necessary files.</para></listitem>
2076 </itemizedlist>
2077 </para>
2078
2079 <para>
2080 Within this environment, you can run configure or compile
2081 commands as if they were being run by
2082 the OpenEmbedded build system itself.
2083 As noted earlier, the working directory also automatically changes to the
2084 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
2085 </para>
2086
2087 <para>
2088 When you are finished, you just exit the shell or close the terminal window.
2089 </para>
2090
2091 <note>
2092 <para>
2093 It is worth remembering that when using <filename>devshell</filename>
2094 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
2095 instead of just using <filename>gcc</filename>.
2096 The same applies to other applications such as <filename>binutils</filename>,
2097 <filename>libtool</filename> and so forth.
2098 BitBake sets up environment variables such as <filename>CC</filename>
2099 to assist applications, such as <filename>make</filename> to find the correct tools.
2100 </para>
2101
2102 <para>
2103 It is also worth noting that <filename>devshell</filename> still works over
2104 X11 forwarding and similar situations.
2105 </para>
2106 </note>
2107</section>
2108
2109</chapter>
2110<!--
2111vim: expandtab tw=80 ts=4
2112-->
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
new file mode 100644
index 0000000000..2385187f4d
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -0,0 +1,1692 @@
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='dev-manual-newbie'>
6
7<title>The Yocto Project Open Source Development Environment</title>
8
9<para>
10 This chapter helps you understand the Yocto Project as an open source development project.
11 In general, working in an open source environment is very different from working in a
12 closed, proprietary environment.
13 Additionally, the Yocto Project uses specific tools and constructs as part of its development
14 environment.
15 This chapter specifically addresses open source philosophy, using the
16 Yocto Project in a team environment, source repositories, Yocto Project
17 terms, licensing, the open source distributed version control system Git,
18 workflows, bug tracking, and how to submit changes.
19</para>
20
21<section id='open-source-philosophy'>
22 <title>Open Source Philosophy</title>
23
24 <para>
25 Open source philosophy is characterized by software development directed by peer production
26 and collaboration through an active community of developers.
27 Contrast this to the more standard centralized development models used by commercial software
28 companies where a finite set of developers produces a product for sale using a defined set
29 of procedures that ultimately result in an end product whose architecture and source material
30 are closed to the public.
31 </para>
32
33 <para>
34 Open source projects conceptually have differing concurrent agendas, approaches, and production.
35 These facets of the development process can come from anyone in the public (community) that has a
36 stake in the software project.
37 The open source environment contains new copyright, licensing, domain, and consumer issues
38 that differ from the more traditional development environment.
39 In an open source environment, the end product, source material, and documentation are
40 all available to the public at no cost.
41 </para>
42
43 <para>
44 A benchmark example of an open source project is the Linux kernel, which was initially conceived
45 and created by Finnish computer science student Linus Torvalds in 1991.
46 Conversely, a good example of a non-open source project is the
47 <trademark class='registered'>Windows</trademark> family of operating
48 systems developed by <trademark class='registered'>Microsoft</trademark> Corporation.
49 </para>
50
51 <para>
52 Wikipedia has a good historical description of the Open Source Philosophy
53 <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
54 You can also find helpful information on how to participate in the Linux Community
55 <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
56 </para>
57</section>
58
59<section id="usingpoky-changes-collaborate">
60 <title>Using the Yocto Project in a Team Environment</title>
61
62 <para>
63 It might not be immediately clear how you can use the Yocto
64 Project in a team environment, or scale it for a large team of
65 developers.
66 One of the strengths of the Yocto Project is that it is extremely
67 flexible.
68 Thus, you can adapt it to many different use cases and scenarios.
69 However, these characteristics can cause a struggle if you are trying
70 to create a working setup that scales across a large team.
71 </para>
72
73 <para>
74 To help with these types of situations, this section presents
75 some of the project's most successful experiences,
76 practices, solutions, and available technologies that work well.
77 Keep in mind, the information here is a starting point.
78 You can build off it and customize it to fit any
79 particular working environment and set of practices.
80 </para>
81
82 <section id='best-practices-system-configurations'>
83 <title>System Configurations</title>
84
85 <para>
86 Systems across a large team should meet the needs of
87 two types of developers: those working on the contents of the
88 operating system image itself and those developing applications.
89 Regardless of the type of developer, their workstations must
90 be both reasonably powerful and run Linux.
91 </para>
92
93 <section id='best-practices-application-development'>
94 <title>Application Development</title>
95
96 <para>
97 For developers who mainly do application level work
98 on top of an existing software stack,
99 here are some practices that work best:
100 <itemizedlist>
101 <listitem><para>Use a pre-built toolchain that
102 contains the software stack itself.
103 Then, develop the application code on top of the
104 stack.
105 This method works well for small numbers of relatively
106 isolated applications.</para></listitem>
107 <listitem><para>When possible, use the Yocto Project
108 plug-in for the <trademark class='trade'>Eclipse</trademark> IDE
109 and other pieces of Application Development
110 Technology (ADT).
111 For more information, see the
112 "<link linkend='application-development-workflow'>Application
113 Development Workflow</link>" section as well as the
114 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
115 </para></listitem>
116 <listitem><para>Keep your cross-development toolchains
117 updated.
118 You can do this through provisioning either as new
119 toolchain downloads or as updates through a package
120 update mechanism using <filename>opkg</filename>
121 to provide updates to an existing toolchain.
122 The exact mechanics of how and when to do this are a
123 question for local policy.</para></listitem>
124 <listitem><para>Use multiple toolchains installed locally
125 into different locations to allow development across
126 versions.</para></listitem>
127 </itemizedlist>
128 </para>
129 </section>
130
131 <section id='best-practices-core-system-development'>
132 <title>Core System Development</title>
133
134 <para>
135 For core system development, it is often best to have the
136 build system itself available on the developer workstations
137 so developers can run their own builds and directly
138 rebuild the software stack.
139 You should keep the core system unchanged as much as
140 possible and do your work in layers on top of the core system.
141 Doing so gives you a greater level of portability when
142 upgrading to new versions of the core system or Board
143 Support Packages (BSPs).
144 You can share layers amongst the developers of a particular
145 project and contain the policy configuration that defines
146 the project.
147 </para>
148
149 <para>
150 Aside from the previous best practices, there exists a number
151 of tips and tricks that can help speed up core development
152 projects:
153 <itemizedlist>
154 <listitem><para>Use a
155 <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>
156 (sstate) among groups of developers who are on a
157 fast network.
158 The best way to share sstate is through a
159 Network File System (NFS) share.
160 The first user to build a given component for the
161 first time contributes that object to the sstate,
162 while subsequent builds from other developers then
163 reuse the object rather than rebuild it themselves.
164 </para>
165 <para>Although it is possible to use other protocols for the
166 sstate such as HTTP and FTP, you should avoid these.
167 Using HTTP limits the sstate to read-only and
168 FTP provides poor performance.
169 </para></listitem>
170 <listitem><para>Have autobuilders contribute to the sstate
171 pool similarly to how the developer workstations
172 contribute.
173 For information, see the
174 "<link linkend='best-practices-autobuilders'>Autobuilders</link>"
175 section.</para></listitem>
176 <listitem><para>Build stand-alone tarballs that contain
177 "missing" system requirements if for some reason
178 developer workstations do not meet minimum system
179 requirements such as latest Python versions,
180 <filename>chrpath</filename>, or other tools.
181 You can install and relocate the tarball exactly as you
182 would the usual cross-development toolchain so that
183 all developers can meet minimum version requirements
184 on most distributions.</para></listitem>
185 <listitem><para>Use a small number of shared,
186 high performance systems for testing purposes
187 (e.g. dual, six-core Xeons with 24 Gbytes of RAM
188 and plenty of disk space).
189 Developers can use these systems for wider, more
190 extensive testing while they continue to develop
191 locally using their primary development system.
192 </para></listitem>
193 <listitem><para>Enable the PR Service when package feeds
194 need to be incremental with continually increasing
195 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink>
196 values.
197 Typically, this situation occurs when you use or
198 publish package feeds and use a shared state.
199 You should enable the PR Service for all users who
200 use the shared state pool.
201 For more information on the PR Service, see the
202 "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
203 </para></listitem>
204 </itemizedlist>
205 </para>
206 </section>
207 </section>
208
209 <section id='best-practices-source-control-management'>
210 <title>Source Control Management (SCM)</title>
211
212 <para>
213 Keeping your
214 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
215 and any software you are developing under the
216 control of an SCM system that is compatible
217 with the OpenEmbedded build system is advisable.
218 Of the SCMs BitBake supports, the
219 Yocto Project team strongly recommends using
220 <link linkend='git'>Git</link>.
221 Git is a distributed system that is easy to backup,
222 allows you to work remotely, and then connects back to the
223 infrastructure.
224 <note>
225 For information about BitBake, see the
226 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
227 </note>
228 </para>
229
230 <para>
231 It is relatively easy to set up Git services and create
232 infrastructure like
233 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
234 which is based on server software called
235 <filename>gitolite</filename> with <filename>cgit</filename>
236 being used to generate the web interface that lets you view the
237 repositories.
238 The <filename>gitolite</filename> software identifies users
239 using SSH keys and allows branch-based
240 access controls to repositories that you can control as little
241 or as much as necessary.
242 </para>
243
244 <note>
245 The setup of these services is beyond the scope of this manual.
246 However, sites such as these exist that describe how to perform
247 setup:
248 <itemizedlist>
249 <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
250 Describes how to install <filename>gitolite</filename>
251 on the server.</para></listitem>
252 <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
253 All topics for <filename>gitolite</filename>.
254 </para></listitem>
255 <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
256 Documentation on how to create interfaces and frontends
257 for Git.</para></listitem>
258 </itemizedlist>
259 </note>
260 </section>
261
262 <section id='best-practices-autobuilders'>
263 <title>Autobuilders</title>
264
265 <para>
266 Autobuilders are often the core of a development project.
267 It is here that changes from individual developers are brought
268 together and centrally tested and subsequent decisions about
269 releases can be made.
270 Autobuilders also allow for "continuous integration" style
271 testing of software components and regression identification
272 and tracking.
273 </para>
274
275 <para>
276 See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
277 for more information and links to buildbot.
278 The Yocto Project team has found this implementation
279 works well in this role.
280 A public example of this is the Yocto Project
281 Autobuilders, which we use to test the overall health of the
282 project.
283 </para>
284
285 <para>
286 The features of this system are:
287 <itemizedlist>
288 <listitem><para>Highlights when commits break the build.
289 </para></listitem>
290 <listitem><para>Populates an sstate cache from which
291 developers can pull rather than requiring local
292 builds.</para></listitem>
293 <listitem><para>Allows commit hook triggers,
294 which trigger builds when commits are made.
295 </para></listitem>
296 <listitem><para>Allows triggering of automated image booting
297 and testing under the QuickEMUlator (QEMU).
298 </para></listitem>
299 <listitem><para>Supports incremental build testing and
300 from-scratch builds.</para></listitem>
301 <listitem><para>Shares output that allows developer
302 testing and historical regression investigation.
303 </para></listitem>
304 <listitem><para>Creates output that can be used for releases.
305 </para></listitem>
306 <listitem><para>Allows scheduling of builds so that resources
307 can be used efficiently.</para></listitem>
308 </itemizedlist>
309 </para>
310 </section>
311
312 <section id='best-practices-policies-and-change-flow'>
313 <title>Policies and Change Flow</title>
314
315 <para>
316 The Yocto Project itself uses a hierarchical structure and a
317 pull model.
318 Scripts exist to create and send pull requests
319 (i.e. <filename>create-pull-request</filename> and
320 <filename>send-pull-request</filename>).
321 This model is in line with other open source projects where
322 maintainers are responsible for specific areas of the project
323 and a single maintainer handles the final "top-of-tree" merges.
324 </para>
325
326 <note>
327 You can also use a more collective push model.
328 The <filename>gitolite</filename> software supports both the
329 push and pull models quite easily.
330 </note>
331
332 <para>
333 As with any development environment, it is important
334 to document the policy used as well as any main project
335 guidelines so they are understood by everyone.
336 It is also a good idea to have well structured
337 commit messages, which are usually a part of a project's
338 guidelines.
339 Good commit messages are essential when looking back in time and
340 trying to understand why changes were made.
341 </para>
342
343 <para>
344 If you discover that changes are needed to the core layer of the
345 project, it is worth sharing those with the community as soon
346 as possible.
347 Chances are if you have discovered the need for changes, someone
348 else in the community needs them also.
349 </para>
350 </section>
351
352 <section id='best-practices-summary'>
353 <title>Summary</title>
354
355 <para>
356 This section summarizes the key recommendations described in the
357 previous sections:
358 <itemizedlist>
359 <listitem><para>Use <link linkend='git'>Git</link>
360 as the source control system.</para></listitem>
361 <listitem><para>Maintain your Metadata in layers that make sense
362 for your situation.
363 See the "<link linkend='understanding-and-creating-layers'>Understanding
364 and Creating Layers</link>" section for more information on
365 layers.</para></listitem>
366 <listitem><para>
367 Separate the project's Metadata and code by using
368 separate Git repositories.
369 See the
370 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
371 section for information on these repositories.
372 See the
373 "<link linkend='getting-setup'>Getting Set Up</link>"
374 section for information on how to set up local Git
375 repositories for related upstream Yocto Project
376 Git repositories.
377 </para></listitem>
378 <listitem><para>Set up the directory for the shared state cache
379 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
380 where it makes sense.
381 For example, set up the sstate cache on a system used
382 by developers in the same organization and share the
383 same source directories on their machines.
384 </para></listitem>
385 <listitem><para>Set up an Autobuilder and have it populate the
386 sstate cache and source directories.</para></listitem>
387 <listitem><para>The Yocto Project community encourages you
388 to send patches to the project to fix bugs or add features.
389 If you do submit patches, follow the project commit
390 guidelines for writing good commit messages.
391 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
392 section.</para></listitem>
393 <listitem><para>Send changes to the core sooner than later
394 as others are likely to run into the same issues.
395 For some guidance on mailing lists to use, see the list in the
396 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
397 section.
398 For a description of the available mailing lists, see the
399 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
400 section in the Yocto Project Reference Manual.
401 </para></listitem>
402 </itemizedlist>
403 </para>
404 </section>
405</section>
406
407<section id='yocto-project-repositories'>
408 <title>Yocto Project Source Repositories</title>
409
410 <para>
411 The Yocto Project team maintains complete source repositories for all
412 Yocto Project files at
413 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
414 This web-based source code browser is organized into categories by
415 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
416 so forth.
417 From the interface, you can click on any particular item in the "Name"
418 column and see the URL at the bottom of the page that you need to clone
419 a Git repository for that particular item.
420 Having a local Git repository of the
421 <link linkend='source-directory'>Source Directory</link>, which is
422 usually named "poky", allows
423 you to make changes, contribute to the history, and ultimately enhance
424 the Yocto Project's tools, Board Support Packages, and so forth.
425 </para>
426
427 <para>
428 For any supported release of Yocto Project, you can also go to the
429 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
430 select the "Downloads" tab and get a released tarball of the
431 <filename>poky</filename> repository or any supported BSP tarballs.
432 Unpacking these tarballs gives you a snapshot of the released
433 files.
434 <note><title>Notes</title>
435 <itemizedlist>
436 <listitem><para>
437 The recommended method for setting up the Yocto Project
438 <link linkend='source-directory'>Source Directory</link>
439 and the files for supported BSPs
440 (e.g., <filename>meta-intel</filename>) is to use
441 <link linkend='git'>Git</link> to create a local copy of
442 the upstream repositories.
443 </para></listitem>
444 <listitem><para>
445 Be sure to always work in matching branches for both
446 the selected BSP repository and the
447 <link linkend='source-directory'>Source Directory</link>
448 (i.e. <filename>poky</filename>) repository.
449 For example, if you have checked out the "master" branch
450 of <filename>poky</filename> and you are going to use
451 <filename>meta-intel</filename>, be sure to checkout the
452 "master" branch of <filename>meta-intel</filename>.
453 </para></listitem>
454 </itemizedlist>
455 </note>
456 </para>
457
458 <para>
459 In summary, here is where you can get the project files needed for development:
460 <itemizedlist>
461 <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
462 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
463 Metadata Layers.
464 You can create local copies of Git repositories for each of these areas.</para>
465 <para>
466 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
467 </para></listitem>
468 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
469 This is an index of releases such as
470 the <trademark class='trade'>Eclipse</trademark>
471 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains,
472 and all released versions of Yocto Project in the form of images or tarballs.
473 Downloading and extracting these files does not produce a local copy of the
474 Git repository but rather a snapshot of a particular release or image.</para>
475 <para>
476 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
477 </para></listitem>
478 <listitem><para><emphasis>"Downloads" page for the
479 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis>
480 Access this page by going to the website and then selecting
481 the "Downloads" tab.
482 This page allows you to download any Yocto Project
483 release or Board Support Package (BSP) in tarball form.
484 The tarballs are similar to those found in the
485 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
486 <para>
487 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
488 </para></listitem>
489 </itemizedlist>
490 </para>
491</section>
492
493<section id='yocto-project-terms'>
494 <title>Yocto Project Terms</title>
495
496 <para>
497 Following is a list of terms and definitions users new to the Yocto Project development
498 environment might find helpful.
499 While some of these terms are universal, the list includes them just in case:
500 <itemizedlist>
501 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
502 a recipe file.
503 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
504 The OpenEmbedded build system expects every append file to have a corresponding
505 recipe (<filename>.bb</filename>) file.
506 Furthermore, the append file and corresponding recipe file
507 must use the same root filename.
508 The filenames can differ only in the file type suffix used (e.g.
509 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
510 </para>
511 <para>Information in append files extends or overrides the
512 information in the similarly-named recipe file.
513 For an example of an append file in use, see the
514 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
515 <note>
516 Append files can also use wildcard patterns in their version numbers
517 so they can be applied to more than one version of the underlying recipe file.
518 </note>
519 </para></listitem>
520 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
521 The task executor and scheduler used by the OpenEmbedded build
522 system to build images.
523 For more information on BitBake, see the
524 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
525 </para></listitem>
526 <listitem>
527 <para id='build-directory'><emphasis>Build Directory:</emphasis>
528 This term refers to the area used by the OpenEmbedded build
529 system for builds.
530 The area is created when you <filename>source</filename> the
531 setup environment script that is found in the Source Directory
532 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
533 or
534 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
535 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
536 variable points to the Build Directory.</para>
537
538 <para>
539 You have a lot of flexibility when creating the Build
540 Directory.
541 Following are some examples that show how to create the
542 directory.
543 The examples assume your
544 <link linkend='source-directory'>Source Directory</link> is
545 named <filename>poky</filename>:
546 <itemizedlist>
547 <listitem><para>Create the Build Directory inside your
548 Source Directory and let the name of the Build
549 Directory default to <filename>build</filename>:
550 <literallayout class='monospaced'>
551 $ cd $HOME/poky
552 $ source &OE_INIT_FILE;
553 </literallayout></para></listitem>
554 <listitem><para>Create the Build Directory inside your
555 home directory and specifically name it
556 <filename>test-builds</filename>:
557 <literallayout class='monospaced'>
558 $ cd $HOME
559 $ source poky/&OE_INIT_FILE; test-builds
560 </literallayout></para></listitem>
561 <listitem><para>
562 Provide a directory path and
563 specifically name the Build Directory.
564 Any intermediate folders in the pathname must
565 exist.
566 This next example creates a Build Directory named
567 <filename>YP-&POKYVERSION;</filename>
568 in your home directory within the existing
569 directory <filename>mybuilds</filename>:
570 <literallayout class='monospaced'>
571 $cd $HOME
572 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
573 </literallayout></para></listitem>
574 </itemizedlist>
575 <note>
576 By default, the Build Directory contains
577 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
578 which is a temporary directory the build system uses for
579 its work.
580 <filename>TMPDIR</filename> cannot be under NFS.
581 Thus, by default, the Build Directory cannot be under NFS.
582 However, if you need the Build Directory to be under NFS,
583 you can set this up by setting <filename>TMPDIR</filename>
584 in your <filename>local.conf</filename> file
585 to use a local drive.
586 Doing so effectively separates <filename>TMPDIR</filename>
587 from <filename>TOPDIR</filename>, which is the Build
588 Directory.
589 </note>
590 </para></listitem>
591 <listitem><para id='build-system-term'><emphasis>Build System:</emphasis>
592 In the context of the Yocto Project,
593 this term refers to the OpenEmbedded build system used by the project.
594 This build system is based on the project known as "Poky."
595 For some historical information about Poky, see the
596 <link linkend='poky'>Poky</link> term.
597 </para></listitem>
598 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
599 and inheritance so that commonly used patterns can be defined once and then easily used
600 in multiple recipes.
601 For reference information on the Yocto Project classes, see the
602 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
603 Yocto Project Reference Manual.
604 Class files end with the <filename>.bbclass</filename> filename extension.
605 </para></listitem>
606 <listitem><para><emphasis>Configuration File:</emphasis>
607 Configuration information in various <filename>.conf</filename>
608 files provides global definitions of variables.
609 The <filename>conf/local.conf</filename> configuration file in
610 the
611 <link linkend='build-directory'>Build Directory</link>
612 contains user-defined variables that affect every build.
613 The <filename>meta-yocto/conf/distro/poky.conf</filename>
614 configuration file defines Yocto "distro" configuration
615 variables used only when building with this policy.
616 Machine configuration files, which
617 are located throughout the
618 <link linkend='source-directory'>Source Directory</link>, define
619 variables for specific hardware and are only used when building
620 for that target (e.g. the
621 <filename>machine/beaglebone.conf</filename> configuration
622 file defines variables for the Texas Instruments ARM Cortex-A8
623 development board).
624 Configuration files end with a <filename>.conf</filename>
625 filename extension.
626 </para></listitem>
627 <listitem><para id='cross-development-toolchain'>
628 <emphasis>Cross-Development Toolchain:</emphasis>
629 In general, a cross-development toolchain is a collection of
630 software development tools and utilities that run on one
631 architecture and allow you to develop software for a
632 different, or targeted, architecture.
633 These toolchains contain cross-compilers, linkers, and
634 debuggers that are specific to the target architecture.
635 </para>
636
637 <para>The Yocto Project supports two different cross-development
638 toolchains:
639 <itemizedlist>
640 <listitem><para>A toolchain only used by and within
641 BitBake when building an image for a target
642 architecture.</para></listitem>
643 <listitem><para>A relocatable toolchain used outside of
644 BitBake by developers when developing applications
645 that will run on a targeted device.
646 Sometimes this relocatable cross-development
647 toolchain is referred to as the meta-toolchain.
648 </para></listitem>
649 </itemizedlist>
650 </para>
651
652 <para>
653 Creation of these toolchains is simple and automated.
654 For information on toolchain concepts as they apply to the
655 Yocto Project, see the
656 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
657 section in the Yocto Project Reference Manual.
658 You can also find more information on using the
659 relocatable toolchain in the
660 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
661 Application Developer's Guide</ulink>.
662 </para></listitem>
663 <listitem><para><emphasis>Image:</emphasis>
664 An image is an artifact of the BitBake build process given
665 a collection of recipes and related Metadata.
666 Images are the binary output that run on specific hardware or
667 QEMU and are used for specific use-cases.
668 For a list of the supported image types that the Yocto Project provides, see the
669 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
670 chapter in the Yocto Project Reference Manual.</para></listitem>
671 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
672 a BSP, or an application stack.
673 For a discussion specifically on BSP Layers, see the
674 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
675 section in the Yocto Project Board Support Packages (BSP)
676 Developer's Guide.</para></listitem>
677 <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis>
678 A term sometimes used for
679 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
680 </para></listitem>
681 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
682 The files that BitBake parses when building an image.
683 In general, Metadata includes recipes, classes, and
684 configuration files.
685 In the context of the kernel ("kernel Metadata"),
686 it refers to Metadata in the <filename>meta</filename>
687 branches of the kernel source Git repositories.
688 </para></listitem>
689 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
690 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
691 This Metadata is found in the <filename>meta</filename> directory of the
692 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
693 <listitem><para><emphasis>Package:</emphasis>
694 In the context of the Yocto Project, this term refers to a
695 recipe's packaged output produced by BitBake (i.e. a
696 "baked recipe").
697 A package is generally the compiled binaries produced from the
698 recipe's sources.
699 You "bake" something by running it through BitBake.</para>
700 <para>It is worth noting that the term "package" can, in general, have subtle
701 meanings. For example, the packages referred to in the
702 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are
703 compiled binaries that, when installed, add functionality to your Linux
704 distribution.</para>
705 <para>Another point worth noting is that historically within the Yocto Project,
706 recipes were referred to as packages - thus, the existence of several BitBake
707 variables that are seemingly mis-named,
708 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
709 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
710 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
711 </para></listitem>
712 <listitem><para><emphasis>Package Groups:</emphasis>
713 Arbitrary groups of software Recipes.
714 You use package groups to hold recipes that, when built,
715 usually accomplish a single task.
716 For example, a package group could contain the recipes for a
717 company’s proprietary or value-add software.
718 Or, the package group could contain the recipes that enable
719 graphics.
720 A package group is really just another recipe.
721 Because package group files are recipes, they end with the
722 <filename>.bb</filename> filename extension.</para></listitem>
723 <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
724 In its most general sense, it is an open-source project that was initially developed
725 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
726 build system becoming a build system for embedded images.
727 After Intel Corporation acquired OpenedHand, the project poky became the basis for
728 the Yocto Project's build system.</para>
729 <para>
730 Within the Yocto Project source repositories, <filename>poky</filename>
731 exists as a separate Git repository
732 that can be cloned to yield a local copy on the host system.
733 Thus, "poky" can refer to the local copy of the Source Directory used to develop within
734 the Yocto Project.</para></listitem>
735 <listitem><para><emphasis>Recipe:</emphasis>
736 A set of instructions for building packages.
737 A recipe describes where you get source code, which patches
738 to apply, how to configure the source, how to compile it and so on.
739 Recipes also describe dependencies for libraries or for other
740 recipes.
741 Recipes represent the logical unit of execution, the software
742 to build, the images to build, and use the
743 <filename>.bb</filename> file extension.
744 </para></listitem>
745 <listitem>
746 <para id='source-directory'><emphasis>Source Directory:</emphasis>
747 This term refers to the directory structure created as a result
748 of creating a local copy of the <filename>poky</filename> Git
749 repository <filename>git://git.yoctoproject.org/poky</filename>
750 or expanding a released <filename>poky</filename> tarball.
751 <note>
752 Creating a local copy of the <filename>poky</filename>
753 Git repository is the recommended method for setting up
754 your Source Directory.
755 </note>
756 Sometimes you might hear the term "poky directory" used to refer
757 to this directory structure.
758 <note>
759 The OpenEmbedded build system does not support file or
760 directory names that contain spaces.
761 Be sure that the Source Directory you use does not contain
762 these types of names.
763 </note></para>
764
765 <para>The Source Directory contains BitBake, Documentation,
766 Metadata and other files that all support the Yocto Project.
767 Consequently, you must have the Source Directory in place on
768 your development system in order to do any development using
769 the Yocto Project.</para>
770
771 <para>When you create a local copy of the Git repository, you
772 can name the repository anything you like.
773 Throughout much of the documentation, "poky"
774 is used as the name of the top-level folder of the local copy of
775 the poky Git repository.
776 So, for example, cloning the <filename>poky</filename> Git
777 repository results in a local Git repository whose top-level
778 folder is also named "poky".</para>
779
780 <para>While it is not recommended that you use tarball expansion
781 to set up the Source Directory, if you do, the top-level
782 directory name of the Source Directory is derived from the
783 Yocto Project release tarball.
784 For example, downloading and unpacking
785 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
786 Source Directory whose root folder is named
787 <filename>&YOCTO_POKY;</filename>.</para>
788
789 <para>It is important to understand the differences between the
790 Source Directory created by unpacking a released tarball as
791 compared to cloning
792 <filename>git://git.yoctoproject.org/poky</filename>.
793 When you unpack a tarball, you have an exact copy of the files
794 based on the time of release - a fixed release point.
795 Any changes you make to your local files in the Source Directory
796 are on top of the release and will remain local only.
797 On the other hand, when you clone the <filename>poky</filename>
798 Git repository, you have an active development repository with
799 access to the upstream repository's branches and tags.
800 In this case, any local changes you make to the local
801 Source Directory can be later applied to active development
802 branches of the upstream <filename>poky</filename> Git
803 repository.</para>
804
805 <para>For more information on concepts related to Git
806 repositories, branches, and tags, see the
807 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
808 section.</para></listitem>
809 <listitem><para><emphasis>Task:</emphasis>
810 A unit of execution for BitBake (e.g.
811 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>,
812 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
813 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>,
814 and so forth).
815 </para></listitem>
816 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
817 that are not local to the development system but located in a master area that is controlled
818 by the maintainer of the source code.
819 For example, in order for a developer to work on a particular piece of code, they need to
820 first get a copy of it from an "upstream" source.</para></listitem>
821 </itemizedlist>
822 </para>
823</section>
824
825<section id='licensing'>
826 <title>Licensing</title>
827
828 <para>
829 Because open source projects are open to the public, they have different licensing structures in place.
830 License evolution for both Open Source and Free Software has an interesting history.
831 If you are interested in this history, you can find basic information here:
832 <itemizedlist>
833 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
834 </para></listitem>
835 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license
836 history</ulink></para></listitem>
837 </itemizedlist>
838 </para>
839
840 <para>
841 In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
842 (MIT) License.
843 MIT licensing permits the reuse of software within proprietary software as long as the
844 license is distributed with that software.
845 MIT is also compatible with the GNU General Public License (GPL).
846 Patches to the Yocto Project follow the upstream licensing scheme.
847 You can find information on the MIT license
848 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
849 You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>
850 here</ulink>.
851 </para>
852
853 <para>
854 When you build an image using the Yocto Project, the build process uses a
855 known list of licenses to ensure compliance.
856 You can find this list in the
857 <link linkend='source-directory'>Source Directory</link> at
858 <filename>meta/files/common-licenses</filename>.
859 Once the build completes, the list of all licenses found and used during that build are
860 kept in the
861 <link linkend='build-directory'>Build Directory</link> at
862 <filename>tmp/deploy/licenses</filename>.
863 </para>
864
865 <para>
866 If a module requires a license that is not in the base list, the build process
867 generates a warning during the build.
868 These tools make it easier for a developer to be certain of the licenses with which
869 their shipped products must comply.
870 However, even with these tools it is still up to the developer to resolve potential licensing issues.
871 </para>
872
873 <para>
874 The base list of licenses used by the build process is a combination of the Software Package
875 Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
876 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation
877 that maintains a specification
878 for a standard format for communicating the components, licenses, and copyrights
879 associated with a software package.
880 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
881 Definition and the effort for reviewing and approving licenses that
882 conform to the Open Source Definition (OSD).
883 </para>
884
885 <para>
886 You can find a list of the combined SPDX and OSI licenses that the
887 Yocto Project uses in the
888 <filename>meta/files/common-licenses</filename> directory in your
889 <link linkend='source-directory'>Source Directory</link>.
890 </para>
891
892 <para>
893 For information that can help you maintain compliance with various
894 open source licensing during the lifecycle of a product created using
895 the Yocto Project, see the
896 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"
897 section.
898 </para>
899</section>
900
901<section id='git'>
902 <title>Git</title>
903
904 <para>
905 The Yocto Project makes extensive use of Git,
906 which is a free, open source distributed version control system.
907 Git supports distributed development, non-linear development, and can handle large projects.
908 It is best that you have some fundamental understanding of how Git tracks projects and
909 how to work with Git if you are going to use the Yocto Project for development.
910 This section provides a quick overview of how Git works and provides you with a summary
911 of some essential Git commands.
912 </para>
913
914 <para>
915 For more information on Git, see
916 <ulink url='http://git-scm.com/documentation'></ulink>.
917 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
918 </para>
919
920 <section id='repositories-tags-and-branches'>
921 <title>Repositories, Tags, and Branches</title>
922
923 <para>
924 As mentioned earlier in the section
925 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
926 the Yocto Project maintains source repositories at
927 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
928 If you look at this web-interface of the repositories, each item is a separate
929 Git repository.
930 </para>
931
932 <para>
933 Git repositories use branching techniques that track content change (not files)
934 within a project (e.g. a new feature or updated documentation).
935 Creating a tree-like structure based on project divergence allows for excellent historical
936 information over the life of a project.
937 This methodology also allows for an environment from which you can do lots of
938 local experimentation on projects as you develop changes or new features.
939 </para>
940
941 <para>
942 A Git repository represents all development efforts for a given project.
943 For example, the Git repository <filename>poky</filename> contains all changes
944 and developments for Poky over the course of its entire life.
945 That means that all changes that make up all releases are captured.
946 The repository maintains a complete history of changes.
947 </para>
948
949 <para>
950 You can create a local copy of any repository by "cloning" it with the Git
951 <filename>clone</filename> command.
952 When you clone a Git repository, you end up with an identical copy of the
953 repository on your development system.
954 Once you have a local copy of a repository, you can take steps to develop locally.
955 For examples on how to clone Git repositories, see the
956 "<link linkend='getting-setup'>Getting Set Up</link>" section.
957 </para>
958
959 <para>
960 It is important to understand that Git tracks content change and
961 not files.
962 Git uses "branches" to organize different development efforts.
963 For example, the <filename>poky</filename> repository has
964 <filename>denzil</filename>, <filename>danny</filename>,
965 <filename>dylan</filename>, <filename>dora</filename>,
966 <filename>daisy</filename>, and <filename>master</filename> branches
967 among others.
968 You can see all the branches by going to
969 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
970 clicking on the
971 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
972 link beneath the "Branch" heading.
973 </para>
974
975 <para>
976 Each of these branches represents a specific area of development.
977 The <filename>master</filename> branch represents the current or most recent
978 development.
979 All other branches represent offshoots of the <filename>master</filename>
980 branch.
981 </para>
982
983 <para>
984 When you create a local copy of a Git repository, the copy has the same set
985 of branches as the original.
986 This means you can use Git to create a local working area (also called a branch)
987 that tracks a specific development branch from the source Git repository.
988 in other words, you can define your local Git environment to work on any development
989 branch in the repository.
990 To help illustrate, here is a set of commands that creates a local copy of the
991 <filename>poky</filename> Git repository and then creates and checks out a local
992 Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
993 <literallayout class='monospaced'>
994 $ cd ~
995 $ git clone git://git.yoctoproject.org/poky
996 $ cd poky
997 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
998 </literallayout>
999 In this example, the name of the top-level directory of your local
1000 <link linkend='source-directory'>Source Directory</link>
1001 is "poky" and the name of that local working area (local branch)
1002 you just created and checked out is "&DISTRO_NAME;".
1003 The files in your local repository now reflect the same files that
1004 are in the "&DISTRO_NAME;" development branch of the
1005 Yocto Project's "poky" upstream repository.
1006 It is important to understand that when you create and checkout a
1007 local working branch based on a branch name,
1008 your local environment matches the "tip" of that development branch
1009 at the time you created your local branch, which could be
1010 different from the files at the time of a similarly named release.
1011 In other words, creating and checking out a local branch based on
1012 the "&DISTRO_NAME;" branch name is not the same as
1013 cloning and checking out the "master" branch.
1014 Keep reading to see how you create a local snapshot of a Yocto
1015 Project Release.
1016 </para>
1017
1018 <para>
1019 Git uses "tags" to mark specific changes in a repository.
1020 Typically, a tag is used to mark a special point such as the final
1021 change before a project is released.
1022 You can see the tags used with the <filename>poky</filename> Git
1023 repository by going to
1024 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
1025 clicking on the
1026 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
1027 link beneath the "Tag" heading.
1028 </para>
1029
1030 <para>
1031 Some key tags are <filename>dylan-9.0.0</filename>,
1032 <filename>dora-10.0.0</filename>, <filename>daisy-11.0.0</filename>,
1033 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
1034 These tags represent Yocto Project releases.
1035 </para>
1036
1037 <para>
1038 When you create a local copy of the Git repository, you also have access to all the
1039 tags.
1040 Similar to branches, you can create and checkout a local working Git branch based
1041 on a tag name.
1042 When you do this, you get a snapshot of the Git repository that reflects
1043 the state of the files when the change was made associated with that tag.
1044 The most common use is to checkout a working branch that matches a specific
1045 Yocto Project release.
1046 Here is an example:
1047 <literallayout class='monospaced'>
1048 $ cd ~
1049 $ git clone git://git.yoctoproject.org/poky
1050 $ cd poky
1051 $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
1052 </literallayout>
1053 In this example, the name of the top-level directory of your local Yocto Project
1054 Files Git repository is <filename>poky</filename>.
1055 And, the name of the local branch you have created and checked out is
1056 <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.
1057 The files in your repository now exactly match the Yocto Project &DISTRO;
1058 Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).
1059 It is important to understand that when you create and checkout a local
1060 working branch based on a tag, your environment matches a specific point
1061 in time and not the entire development branch.
1062 </para>
1063 </section>
1064
1065 <section id='basic-commands'>
1066 <title>Basic Commands</title>
1067
1068 <para>
1069 Git has an extensive set of commands that lets you manage changes and perform
1070 collaboration over the life of a project.
1071 Conveniently though, you can manage with a small set of basic operations and workflows
1072 once you understand the basic philosophy behind Git.
1073 You do not have to be an expert in Git to be functional.
1074 A good place to look for instruction on a minimal set of Git commands is
1075 <ulink url='http://git-scm.com/documentation'>here</ulink>.
1076 If you need to download Git, you can do so
1077 <ulink url='http://git-scm.com/download'>here</ulink>.
1078 </para>
1079
1080 <para>
1081 If you do not know much about Git, you should educate
1082 yourself by visiting the links previously mentioned.
1083 </para>
1084
1085 <para>
1086 The following list briefly describes some basic Git operations as a way to get started.
1087 As with any set of commands, this list (in most cases) simply shows the base command and
1088 omits the many arguments they support.
1089 See the Git documentation for complete descriptions and strategies on how to use these commands:
1090 <itemizedlist>
1091 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
1092 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
1093 <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
1094 Creates a local clone of a Git repository.
1095 During collaboration, this command allows you to create a
1096 local Git repository that is on equal footing with a fellow
1097 developer’s Git repository.
1098 </para></listitem>
1099 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
1100 to the index that
1101 Git uses to track changes.
1102 You must stage all files that have changed before you can commit them.</para></listitem>
1103 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents
1104 the changes you made.
1105 Commits are used for historical purposes, for determining if a maintainer of a project
1106 will allow the change, and for ultimately pushing the change from your local Git repository
1107 into the project’s upstream (or master) repository.</para></listitem>
1108 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
1109 possibly need to be staged and committed.</para></listitem>
1110 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
1111 your working branch.
1112 This command is analogous to "cd".</para></listitem>
1113 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
1114 a working branch on your local machine where you can isolate work.
1115 It is a good idea to use local branches when adding specific features or changes.
1116 This way if you do not like what you have done you can easily get rid of the work.</para></listitem>
1117 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
1118 existing local branches and
1119 tells you the branch in which you are currently working.</para></listitem>
1120 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
1121 Deletes an existing local branch.
1122 You need to be in a local branch other than the one you are deleting
1123 in order to delete <filename>&lt;branch-name&gt;</filename>.</para></listitem>
1124 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
1125 from an upstream Git
1126 repository and places it in your local Git repository.
1127 You use this command to make sure you are synchronized with the repository
1128 from which you are basing changes (.e.g. the master branch).</para></listitem>
1129 <listitem><para><emphasis><filename>git push</filename>:</emphasis>
1130 Sends all your committed local changes to an upstream Git
1131 repository (e.g. a contribution repository).
1132 The maintainer of the project draws from these repositories
1133 when adding changes to the project’s master repository or
1134 other development branch.
1135 </para></listitem>
1136 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
1137 local branch of your repository with another branch.
1138 When you create a local Git repository, the default branch is named "master".
1139 A typical workflow is to create a temporary branch for isolated work, make and commit your
1140 changes, switch to your local master branch, merge the changes from the temporary branch into the
1141 local master branch, and then delete the temporary branch.</para></listitem>
1142 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
1143 commits from one branch into another branch.
1144 There are times when you might not be able to merge all the changes in one branch with
1145 another but need to pick out certain ones.</para></listitem>
1146 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
1147 and changes in your local Git repository.
1148 This command is a good way to graphically see where things have diverged in your
1149 local repository.</para></listitem>
1150 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
1151 repository.</para></listitem>
1152 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
1153 between your local working files and the same files in the upstream Git repository that your
1154 branch currently tracks.</para></listitem>
1155 </itemizedlist>
1156 </para>
1157 </section>
1158</section>
1159
1160<section id='workflows'>
1161 <title>Workflows</title>
1162
1163 <para>
1164 This section provides some overview on workflows using Git.
1165 In particular, the information covers basic practices that describe roles and actions in a
1166 collaborative development environment.
1167 Again, if you are familiar with this type of development environment, you might want to just
1168 skip this section.
1169 </para>
1170
1171 <para>
1172 The Yocto Project files are maintained using Git in a "master" branch whose Git history
1173 tracks every change and whose structure provides branches for all diverging functionality.
1174 Although there is no need to use Git, many open source projects do so.
1175 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
1176 branch of a given Git repository.
1177 The "master" branch is the “upstream” repository where the final builds of the project occur.
1178 The maintainer is responsible for accepting changes from other developers and for
1179 organizing the underlying branch structure to reflect release strategies and so forth.
1180 <note>For information on finding out who is responsible for (maintains)
1181 a particular area of code, see the
1182 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1183 section.
1184 </note>
1185 </para>
1186
1187 <para>
1188 The project also has an upstream contribution Git repository named
1189 <filename>poky-contrib</filename>.
1190 You can see all the branches in this repository using the web interface
1191 of the
1192 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
1193 within the "Poky Support" area.
1194 These branches temporarily hold changes to the project that have been
1195 submitted or committed by the Yocto Project development team and by
1196 community members who contribute to the project.
1197 The maintainer determines if the changes are qualified to be moved
1198 from the "contrib" branches into the "master" branch of the Git
1199 repository.
1200 </para>
1201
1202 <para>
1203 Developers (including contributing community members) create and maintain cloned repositories
1204 of the upstream "master" branch.
1205 These repositories are local to their development platforms and are used to develop changes.
1206 When a developer is satisfied with a particular feature or change, they "push" the changes
1207 to the appropriate "contrib" repository.
1208 </para>
1209
1210 <para>
1211 Developers are responsible for keeping their local repository up-to-date with "master".
1212 They are also responsible for straightening out any conflicts that might arise within files
1213 that are being worked on simultaneously by more than one person.
1214 All this work is done locally on the developer’s machines before anything is pushed to a
1215 "contrib" area and examined at the maintainer’s level.
1216 </para>
1217
1218 <para>
1219 A somewhat formal method exists by which developers commit changes and push them into the
1220 "contrib" area and subsequently request that the maintainer include them into "master"
1221 This process is called “submitting a patch” or "submitting a change."
1222 For information on submitting patches and changes, see the
1223 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
1224 </para>
1225
1226 <para>
1227 To summarize the environment: a single point of entry exists for
1228 changes into the project’s "master" branch of the Git repository,
1229 which is controlled by the project’s maintainer.
1230 And, a set of developers exist who independently develop, test, and
1231 submit changes to "contrib" areas for the maintainer to examine.
1232 The maintainer then chooses which changes are going to become a
1233 permanent part of the project.
1234 </para>
1235
1236 <para>
1237 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
1238 </para>
1239
1240 <para>
1241 While each development environment is unique, there are some best practices or methods
1242 that help development run smoothly.
1243 The following list describes some of these practices.
1244 For more information about Git workflows, see the workflow topics in the
1245 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
1246 <itemizedlist>
1247 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
1248 small as compared to bundling many disparate changes into a single commit.
1249 This practice not only keeps things manageable but also allows the maintainer
1250 to more easily include or refuse changes.</para>
1251 <para>It is also good practice to leave the repository in a state that allows you to
1252 still successfully build your project. In other words, do not commit half of a feature,
1253 then add the other half as a separate, later commit.
1254 Each commit should take you from one buildable project state to another
1255 buildable state.</para></listitem>
1256 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
1257 delete local branches in your working Git repository.
1258 You can name these branches anything you like.
1259 It is helpful to give them names associated with the particular feature or change
1260 on which you are working.
1261 Once you are done with a feature or change and have merged it
1262 into your local master branch, simply discard the temporary
1263 branch.</para></listitem>
1264 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
1265 command allows you to take the
1266 changes from one branch and fold them into another branch.
1267 This process is especially helpful when more than a single developer might be working
1268 on different parts of the same feature.
1269 Merging changes also automatically identifies any collisions or "conflicts"
1270 that might happen as a result of the same lines of code being altered by two different
1271 developers.</para></listitem>
1272 <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
1273 use a system where branches indicate varying levels of code readiness.
1274 For example, you can have a "work" branch to develop in, a "test" branch where the code or
1275 change is tested, a "stage" branch where changes are ready to be committed, and so forth.
1276 As your project develops, you can merge code across the branches to reflect ever-increasing
1277 stable states of the development.</para></listitem>
1278 <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
1279 concept of developers "pushing" local commits to a remote repository, which is
1280 usually a contribution repository.
1281 This workflow is also based on developers "pulling" known states of the project down into their
1282 local development repositories.
1283 The workflow easily allows you to pull changes submitted by other developers from the
1284 upstream repository into your work area ensuring that you have the most recent software
1285 on which to develop.
1286 The Yocto Project has two scripts named <filename>create-pull-request</filename> and
1287 <filename>send-pull-request</filename> that ship with the release to facilitate this
1288 workflow.
1289 You can find these scripts in the <filename>scripts</filename>
1290 folder of the
1291 <link linkend='source-directory'>Source Directory</link>.
1292 For information on how to use these scripts, see the
1293 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
1294 </para></listitem>
1295 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
1296 maintainer through an email that you have a change (or patch) you would like considered
1297 for the "master" branch of the Git repository.
1298 To send this type of change, you format the patch and then send the email using the Git commands
1299 <filename>git format-patch</filename> and <filename>git send-email</filename>.
1300 For information on how to use these scripts, see the
1301 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1302 section.
1303 </para></listitem>
1304 </itemizedlist>
1305 </para>
1306</section>
1307
1308<section id='tracking-bugs'>
1309 <title>Tracking Bugs</title>
1310
1311 <para>
1312 The Yocto Project uses its own implementation of
1313 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
1314 Implementations of Bugzilla work well for group development because they track bugs and code
1315 changes, can be used to communicate changes and problems with developers, can be used to
1316 submit and review patches, and can be used to manage quality assurance.
1317 The home page for the Yocto Project implementation of Bugzilla is
1318 <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
1319 </para>
1320
1321 <para>
1322 Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
1323 such as when discovering an issue with some component of the build system that acts contrary
1324 to the documentation or your expectations.
1325 Following is the general procedure for submitting a new bug using the Yocto Project
1326 Bugzilla.
1327 You can find more information on defect management, bug tracking, and feature request
1328 processes all accomplished through the Yocto Project Bugzilla on the wiki page
1329 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
1330 <orderedlist>
1331 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
1332 a bug.</para></listitem>
1333 <listitem><para>When submitting a new bug, be sure to choose the appropriate
1334 Classification, Product, and Component for which the issue was found.
1335 Defects for the Yocto Project fall into one of seven classifications:
1336 Yocto Project Components, Infrastructure, Build System &amp; Metadata,
1337 Documentation, QA/Testing, Runtime and Hardware.
1338 Each of these Classifications break down into multiple Products and, in some
1339 cases, multiple Components.</para></listitem>
1340 <listitem><para>Use the bug form to choose the correct Hardware and Architecture
1341 for which the bug applies.</para></listitem>
1342 <listitem><para>Indicate the Yocto Project version you were using when the issue
1343 occurred.</para></listitem>
1344 <listitem><para>Be sure to indicate the Severity of the bug.
1345 Severity communicates how the bug impacted your work.</para></listitem>
1346 <listitem><para>Select the appropriate "Documentation change" item
1347 for the bug.
1348 Fixing a bug may or may not affect the Yocto Project
1349 documentation.</para></listitem>
1350 <listitem><para>Provide a brief summary of the issue.
1351 Try to limit your summary to just a line or two and be sure to capture the
1352 essence of the issue.</para></listitem>
1353 <listitem><para>Provide a detailed description of the issue.
1354 You should provide as much detail as you can about the context, behavior, output,
1355 and so forth that surrounds the issue.
1356 You can even attach supporting files for output from logs by
1357 using the "Add an attachment" button.</para></listitem>
1358 <listitem><para>Be sure to copy the appropriate people in the
1359 "CC List" for the bug.
1360 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1361 section for information about finding out who is responsible
1362 for code.</para></listitem>
1363 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
1364 </orderedlist>
1365 </para>
1366</section>
1367
1368<section id='how-to-submit-a-change'>
1369 <title>How to Submit a Change</title>
1370
1371 <para>
1372 Contributions to the Yocto Project and OpenEmbedded are very welcome.
1373 Because the system is extremely configurable and flexible, we recognize that developers
1374 will want to extend, configure or optimize it for their specific uses.
1375 You should send patches to the appropriate mailing list so that they
1376 can be reviewed and merged by the appropriate maintainer.
1377 </para>
1378
1379 <para>
1380 Before submitting any change, be sure to find out who you should be
1381 notifying.
1382 Several methods exist through which you find out who you should be copying
1383 or notifying:
1384 <itemizedlist>
1385 <listitem><para><emphasis>Maintenance File:</emphasis>
1386 Examine the <filename>maintainers.inc</filename> file, which is
1387 located in the
1388 <link linkend='source-directory'>Source Directory</link>
1389 at <filename>meta-yocto/conf/distro/include</filename>, to
1390 see who is responsible for code.
1391 </para></listitem>
1392 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
1393 For BSP maintainers of supported BSPs, you can examine
1394 individual BSP <filename>README</filename> files.
1395 In addition, some layers (such as the <filename>meta-intel</filename> layer),
1396 include a <filename>MAINTAINERS</filename> file which contains
1397 a list of all supported BSP maintainers for that layer.
1398 </para></listitem>
1399 <listitem><para><emphasis>Search by File:</emphasis>
1400 Using <link linkend='git'>Git</link>, you can enter the
1401 following command to bring up a short list of all commits
1402 against a specific file:
1403 <literallayout class='monospaced'>
1404 git shortlog -- <replaceable>filename</replaceable>
1405 </literallayout>
1406 Just provide the name of the file for which you are interested.
1407 The information returned is not ordered by history but does
1408 include a list of all committers grouped by name.
1409 From the list, you can see who is responsible for the bulk of
1410 the changes against the file.
1411 </para></listitem>
1412 </itemizedlist>
1413 </para>
1414
1415 <para>
1416 For a list of the Yocto Project and related mailing lists, see the
1417 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
1418 the Yocto Project Reference Manual.
1419 </para>
1420
1421 <para>
1422 Here is some guidance on which mailing list to use for what type of change:
1423 <itemizedlist>
1424 <listitem><para>For changes to the core
1425 <link linkend='metadata'>Metadata</link>, send your patch to the
1426 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
1427 For example, a change to anything under the <filename>meta</filename> or
1428 <filename>scripts</filename> directories
1429 should be sent to this mailing list.</para></listitem>
1430 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
1431 directory), send your patch to the
1432 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
1433 <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
1434 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
1435 <listitem><para>For changes to other layers hosted on
1436 <filename>yoctoproject.org</filename> (unless the
1437 layer's documentation specifies otherwise), tools, and Yocto Project
1438 documentation, use the
1439 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
1440 <listitem><para>For additional recipes that do not fit into the core Metadata,
1441 you should determine which layer the recipe should go into and submit the
1442 change in the manner recommended by the documentation (e.g. README) supplied
1443 with the layer. If in doubt, please ask on the
1444 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
1445 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
1446 mailing lists.</para></listitem>
1447 </itemizedlist>
1448 </para>
1449
1450 <para>
1451 When you send a patch, be sure to include a "Signed-off-by:"
1452 line in the same style as required by the Linux kernel.
1453 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
1454 as follows:
1455 <literallayout class='monospaced'>
1456 Developer's Certificate of Origin 1.1
1457
1458 By making a contribution to this project, I certify that:
1459
1460 (a) The contribution was created in whole or in part by me and I
1461 have the right to submit it under the open source license
1462 indicated in the file; or
1463
1464 (b) The contribution is based upon previous work that, to the best
1465 of my knowledge, is covered under an appropriate open source
1466 license and I have the right under that license to submit that
1467 work with modifications, whether created in whole or in part
1468 by me, under the same open source license (unless I am
1469 permitted to submit under a different license), as indicated
1470 in the file; or
1471
1472 (c) The contribution was provided directly to me by some other
1473 person who certified (a), (b) or (c) and I have not modified
1474 it.
1475
1476 (d) I understand and agree that this project and the contribution
1477 are public and that a record of the contribution (including all
1478 personal information I submit with it, including my sign-off) is
1479 maintained indefinitely and may be redistributed consistent with
1480 this project or the open source license(s) involved.
1481 </literallayout>
1482 </para>
1483
1484 <para>
1485 In a collaborative environment, it is necessary to have some sort of standard
1486 or method through which you submit changes.
1487 Otherwise, things could get quite chaotic.
1488 One general practice to follow is to make small, controlled changes.
1489 Keeping changes small and isolated aids review, makes merging/rebasing easier
1490 and keeps the change history clean when anyone needs to refer to it in future.
1491 </para>
1492
1493 <para>
1494 When you make a commit, you must follow certain standards established by the
1495 OpenEmbedded and Yocto Project development teams.
1496 For each commit, you must provide a single-line summary of the change and you
1497 should almost always provide a more detailed description of what you did (i.e.
1498 the body of the commit message).
1499 The only exceptions for not providing a detailed description would be if your
1500 change is a simple, self-explanatory change that needs no further description
1501 beyond the summary.
1502 Here are the guidelines for composing a commit message:
1503 <itemizedlist>
1504 <listitem><para>Provide a single-line, short summary of the change.
1505 This summary is typically viewable in the "shortlist" of changes.
1506 Thus, providing something short and descriptive that gives the reader
1507 a summary of the change is useful when viewing a list of many commits.
1508 This short description should be prefixed by the recipe name (if changing a recipe), or
1509 else the short form path to the file being changed.
1510 </para></listitem>
1511 <listitem><para>For the body of the commit message, provide detailed information
1512 that describes what you changed, why you made the change, and the approach
1513 you used. It may also be helpful if you mention how you tested the change.
1514 Provide as much detail as you can in the body of the commit message.
1515 </para></listitem>
1516 <listitem><para>
1517 If the change addresses a specific bug or issue that is
1518 associated with a bug-tracking ID, include a reference to that
1519 ID in your detailed description.
1520 For example, the Yocto Project uses a specific convention for
1521 bug references - any commit that addresses a specific bug should
1522 use the following form for the detailed description:
1523 <literallayout class='monospaced'>
1524 Fixes [YOCTO #<replaceable>bug-id</replaceable>]
1525
1526 <replaceable>detailed description of change</replaceable>
1527 </literallayout></para></listitem>
1528 Where <replaceable>bug-id</replaceable> is replaced with the
1529 specific bug ID from the Yocto Project Bugzilla instance.
1530 </itemizedlist>
1531 </para>
1532
1533 <para>
1534 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1535 wiki page:
1536 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1537 </para>
1538
1539 <para>
1540 The next two sections describe general instructions for both pushing
1541 changes upstream and for submitting changes as patches.
1542 </para>
1543
1544 <section id='pushing-a-change-upstream'>
1545 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
1546
1547 <para>
1548 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1549 <itemizedlist>
1550 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1551 <listitem><para>Stage your changes by using the <filename>git add</filename>
1552 command on each file you changed.</para></listitem>
1553 <listitem><para>
1554 Commit the change by using the
1555 <filename>git commit</filename> command.
1556 Be sure to provide a commit message that follows the
1557 project’s commit message standards as described earlier.
1558 </para></listitem>
1559 <listitem><para>
1560 Push the change to the upstream "contrib" repository by
1561 using the <filename>git push</filename> command.
1562 </para></listitem>
1563 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1564 request.
1565 The Yocto Project provides two scripts that conveniently let you generate and send
1566 pull requests to the Yocto Project.
1567 These scripts are <filename>create-pull-request</filename> and
1568 <filename>send-pull-request</filename>.
1569 You can find these scripts in the <filename>scripts</filename> directory
1570 within the <link linkend='source-directory'>Source Directory</link>.</para>
1571 <para>Using these scripts correctly formats the requests without introducing any
1572 whitespace or HTML formatting.
1573 The maintainer that receives your patches needs to be able to save and apply them
1574 directly from your emails.
1575 Using these scripts is the preferred method for sending patches.</para>
1576 <para>For help on using these scripts, simply provide the
1577 <filename>-h</filename> argument as follows:
1578 <literallayout class='monospaced'>
1579 $ poky/scripts/create-pull-request -h
1580 $ poky/scripts/send-pull-request -h
1581 </literallayout></para></listitem>
1582 </itemizedlist>
1583 </para>
1584
1585 <para>
1586 You can find general Git information on how to push a change upstream in the
1587 <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>.
1588 </para>
1589 </section>
1590
1591 <section id='submitting-a-patch'>
1592 <title>Using Email to Submit a Patch</title>
1593
1594 <para>
1595 You can submit patches without using the <filename>create-pull-request</filename> and
1596 <filename>send-pull-request</filename> scripts described in the previous section.
1597 However, keep in mind, the preferred method is to use the scripts.
1598 </para>
1599
1600 <para>
1601 Depending on the components changed, you need to submit the email to a specific
1602 mailing list.
1603 For some guidance on which mailing list to use, see the list in the
1604 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1605 section.
1606 For a description of the available mailing lists, see the
1607 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
1608 section in the Yocto Project Reference Manual.
1609 </para>
1610
1611 <para>
1612 Here is the general procedure on how to submit a patch through email without using the
1613 scripts:
1614 <itemizedlist>
1615 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1616 <listitem><para>Stage your changes by using the <filename>git add</filename>
1617 command on each file you changed.</para></listitem>
1618 <listitem><para>Commit the change by using the
1619 <filename>git commit --signoff</filename> command.
1620 Using the <filename>--signoff</filename> option identifies you as the person
1621 making the change and also satisfies the Developer's Certificate of
1622 Origin (DCO) shown earlier.</para>
1623 <para>When you form a commit, you must follow certain standards established by the
1624 Yocto Project development team.
1625 See the earlier section
1626 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1627 for Yocto Project commit message standards.</para></listitem>
1628 <listitem><para>Format the commit into an email message.
1629 To format commits, use the <filename>git format-patch</filename> command.
1630 When you provide the command, you must include a revision list or a number of patches
1631 as part of the command.
1632 For example, either of these two commands takes your most
1633 recent single commit and formats it as an email message in
1634 the current directory:
1635 <literallayout class='monospaced'>
1636 $ git format-patch -1
1637 </literallayout>
1638 or
1639 <literallayout class='monospaced'>
1640 $ git format-patch HEAD~
1641 </literallayout></para>
1642 <para>After the command is run, the current directory contains a
1643 numbered <filename>.patch</filename> file for the commit.</para>
1644 <para>If you provide several commits as part of the command,
1645 the <filename>git format-patch</filename> command produces a
1646 series of numbered files in the current directory – one for each commit.
1647 If you have more than one patch, you should also use the
1648 <filename>--cover</filename> option with the command, which generates a
1649 cover letter as the first "patch" in the series.
1650 You can then edit the cover letter to provide a description for
1651 the series of patches.
1652 For information on the <filename>git format-patch</filename> command,
1653 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
1654 <filename>man git-format-patch</filename> command.</para>
1655 <note>If you are or will be a frequent contributor to the Yocto Project
1656 or to OpenEmbedded, you might consider requesting a contrib area and the
1657 necessary associated rights.</note></listitem>
1658 <listitem><para>Import the files into your mail client by using the
1659 <filename>git send-email</filename> command.
1660 <note>In order to use <filename>git send-email</filename>, you must have the
1661 the proper Git packages installed.
1662 For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para>
1663 <para>The <filename>git send-email</filename> command sends email by using a local
1664 or remote Mail Transport Agent (MTA) such as
1665 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
1666 <filename>smtp</filename> configuration in your Git <filename>config</filename>
1667 file.
1668 If you are submitting patches through email only, it is very important
1669 that you submit them without any whitespace or HTML formatting that
1670 either you or your mailer introduces.
1671 The maintainer that receives your patches needs to be able to save and
1672 apply them directly from your emails.
1673 A good way to verify that what you are sending will be applicable by the
1674 maintainer is to do a dry run and send them to yourself and then
1675 save and apply them as the maintainer would.</para>
1676 <para>The <filename>git send-email</filename> command is the preferred method
1677 for sending your patches since there is no risk of compromising whitespace
1678 in the body of the message, which can occur when you use your own mail client.
1679 The command also has several options that let you
1680 specify recipients and perform further editing of the email message.
1681 For information on how to use the <filename>git send-email</filename> command,
1682 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
1683 the <filename>man git-send-email</filename> command.
1684 </para></listitem>
1685 </itemizedlist>
1686 </para>
1687 </section>
1688</section>
1689</chapter>
1690<!--
1691vim: expandtab tw=80 ts=4
1692-->
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
new file mode 100644
index 0000000000..739fd7104b
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -0,0 +1,419 @@
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='dev-manual-qemu'>
6
7<title>Using the Quick EMUlator (QEMU)</title>
8
9<para>
10 Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
11 as part of its development "tool set".
12 As such, the information in this chapter is limited to the
13 Yocto Project integration of QEMU and not QEMU in general.
14 For official information and documentation on QEMU, see the
15 following references:
16 <itemizedlist>
17 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
18 The official website for the QEMU Open Source project.
19 </para></listitem>
20 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
21 The QEMU user manual.
22 </para></listitem>
23 </itemizedlist>
24</para>
25
26<para>
27 This chapter provides an overview of the Yocto Project's integration of
28 QEMU, a description of how you use QEMU and its various options, running
29 under a Network File System (NFS) server, and a few tips and tricks you
30 might find helpful when using QEMU.
31</para>
32
33<section id='qemu-overview'>
34 <title>Overview</title>
35
36 <para>
37 Within the context of the Yocto Project, QEMU is an
38 emulator and virtualization machine that allows you to run a complete
39 image you have built using the Yocto Project as just another task
40 on your build system.
41 QEMU is useful for running and testing images and applications on
42 supported Yocto Project architectures without having actual hardware.
43 Among other things, the Yocto Project uses QEMU to run automated
44 Quality Assurance (QA) tests on final images shipped with each
45 release.
46 </para>
47
48 <para>
49 QEMU is made available with the Yocto Project a number of ways.
50 The easiest and recommended method for getting QEMU is to run the
51 ADT installer. For more information on how to make sure you have
52 QEMU available, see the
53 "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
54 section in the Yocto Project Application Developer's Guide.
55 </para>
56</section>
57
58<section id='qemu-running-qemu'>
59 <title>Running QEMU</title>
60
61 <para>
62 Running QEMU involves having your build environment set up, having the
63 right artifacts available, and understanding how to use the many
64 options that are available to you when you start QEMU using the
65 <filename>runqemu</filename> command.
66 </para>
67
68 <section id='qemu-setting-up-the-environment'>
69 <title>Setting Up the Environment</title>
70
71 <para>
72 You run QEMU in the same environment from which you run BitBake.
73 This means you need to source a build environment script (i.e.
74 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
75 or
76 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
77 </para>
78 </section>
79
80 <section id='qemu-using-the-runqemu-command'>
81 <title>Using the <filename>runqemu</filename> Command</title>
82
83 <para>
84 The basic <filename>runqemu</filename> command syntax is as
85 follows:
86 <literallayout class='monospaced'>
87 $ runqemu [<replaceable>option</replaceable> ] [...]
88 </literallayout>
89 Based on what you provide on the command line,
90 <filename>runqemu</filename> does a good job of figuring out what
91 you are trying to do.
92 For example, by default, QEMU looks for the most recently built
93 image according to the timestamp when it needs to look for an
94 image.
95 Minimally, through the use of options, you must provide either
96 a machine name, a virtual machine image
97 (<filename>*.vmdk</filename>), or a kernel image
98 (<filename>*.bin</filename>).
99 </para>
100
101 <para>
102 Following is a description of <filename>runqemu</filename>
103 options you can provide on the command line:
104 <note><title>Tip</title>
105 If you do provide some "illegal" option combination or perhaps
106 you do not provide enough in the way of options,
107 <filename>runqemu</filename> provides appropriate error
108 messaging to help you correct the problem.
109 </note>
110 <itemizedlist>
111 <listitem><para><replaceable>QEMUARCH</replaceable>:
112 The QEMU machine architecture, which must be "qemux86",
113 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
114 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
115 or "qemuzynq".
116 </para></listitem>
117 <listitem><para><filename><replaceable>VM</replaceable></filename>:
118 The virtual machine image, which must be a
119 <filename>.vmdk</filename> file.
120 Use this option when you want to boot a
121 <filename>.vmdk</filename> image.
122 The image filename you provide must contain one of the
123 following strings: "qemux86-64", "qemux86", "qemuarm",
124 "qemumips64", "qemumips", "qemuppc", or "qemush4".
125 </para></listitem>
126 <listitem><para><replaceable>ROOTFS</replaceable>:
127 A root filesystem that has one of the following
128 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
129 "nfs", or "btrfs".
130 If the filename you provide for this option uses “nfs”, it
131 must provide an explicit root filesystem path.
132 </para></listitem>
133 <listitem><para><replaceable>KERNEL</replaceable>:
134 A kernel image, which is a <filename>.bin</filename> file.
135 When you provide a <filename>.bin</filename> file,
136 <filename>runqemu</filename> detects it and assumes the
137 file is a kernel image.
138 </para></listitem>
139 <listitem><para><replaceable>MACHINE</replaceable>:
140 The architecture of the QEMU machine, which must be one
141 of the following: "qemux86",
142 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
143 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
144 or "qemuzynq".
145 The <replaceable>MACHINE</replaceable> and
146 <replaceable>QEMUARCH</replaceable> options are basically
147 identical.
148 If you do not provide a <replaceable>MACHINE</replaceable>
149 option, <filename>runqemu</filename> tries to determine
150 it based on other options.
151 </para></listitem>
152 <listitem><para><filename>ramfs</filename>:
153 Indicates you are booting an initial RAM disk (initramfs)
154 image, which means the <filename>FSTYPE</filename> is
155 <filename>cpio.gz</filename>.
156 </para></listitem>
157 <listitem><para><filename>iso</filename>:
158 Indicates you are booting an ISO image, which means the
159 <filename>FSTYPE</filename> is
160 <filename>.iso</filename>.
161 </para></listitem>
162 <listitem><para><filename>nographic</filename>:
163 Disables the video console, which sets the console to
164 "ttys0".
165 </para></listitem>
166 <listitem><para><filename>serial</filename>:
167 Enables a serial console on
168 <filename>/dev/ttyS0</filename>.
169 </para></listitem>
170 <listitem><para><filename>biosdir</filename>:
171 Establishes a custom directory for BIOS, VGA BIOS and
172 keymaps.
173 </para></listitem>
174 <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
175 Specifies custom QEMU parameters.
176 Use this option to pass options other than the simple
177 "kvm" and "serial" options.
178 </para></listitem>
179 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
180 Specifies custom boot parameters for the kernel.
181 </para></listitem>
182 <listitem><para><filename>audio</filename>:
183 Enables audio in QEMU.
184 The <replaceable>MACHINE</replaceable> option must be
185 either "qemux86" or "qemux86-64" in order for audio to be
186 enabled.
187 Additionally, the <filename>snd_intel8x0</filename>
188 or <filename>snd_ens1370</filename> driver must be
189 installed in linux guest.
190 </para></listitem>
191 <listitem><para><filename>slirp</filename>:
192 Enables "slirp" networking, which is a different way
193 of networking that does not need root access
194 but also is not as easy to use or comprehensive
195 as the default.
196 </para></listitem>
197 <listitem><para><filename>kvm</filename>:
198 Enables KVM when running "qemux86" or "qemux86-64"
199 QEMU architectures.
200 For KVM to work, all the following conditions must be met:
201 <itemizedlist>
202 <listitem><para>
203 Your <replaceable>MACHINE</replaceable> must be either
204 "qemux86" or "qemux86-64".
205 </para></listitem>
206 <listitem><para>
207 Your build host has to have the KVM modules
208 installed, which are
209 <filename>/dev/kvm</filename>.
210 </para></listitem>
211 <listitem><para>
212 Your build host has to have virtio net device, which
213 are <filename>/dev/vhost-net</filename>.
214 </para></listitem>
215 <listitem><para>
216 The build host <filename>/dev/kvm</filename>
217 directory has to be both writable and readable.
218 </para></listitem>
219 <listitem><para>
220 The build host <filename>/dev/vhost-net</filename>
221 directory has to be either readable or writable
222 and “slirp-enabled”.
223 </para></listitem>
224 </itemizedlist>
225 </para></listitem>
226 <listitem><para><filename>publicvnc</filename>:
227 Enables a VNC server open to all hosts.
228 </para></listitem>
229 </itemizedlist>
230 </para>
231
232 <para>
233 For further understanding regarding option use with
234 <filename>runqemu</filename>, consider some examples.
235 </para>
236
237 <para>
238 This example starts QEMU with
239 <replaceable>MACHINE</replaceable> set to "qemux86".
240 Assuming a standard
241 <link linkend='build-directory'>Build Directory</link>,
242 <filename>runqemu</filename> automatically finds the
243 <filename>bzImage-qemux86.bin</filename> image file and
244 the
245 <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
246 (assuming the current build created a
247 <filename>core-image-minimal</filename> image).
248 <note>
249 When more than one image with the same name exists, QEMU finds
250 and uses the most recently built image according to the
251 timestamp.
252 </note>
253 <literallayout class='monospaced'>
254 $ runqemu qemux86
255 </literallayout>
256 This example produces the exact same results as the
257 previous example.
258 This command, however, specifically provides the image
259 and root filesystem type.
260 <literallayout class='monospaced'>
261 $ runqemu qemux86 core-image-minimal ext3
262 </literallayout>
263 This example specifies to boot an initial RAM disk image
264 and to enable audio in QEMU.
265 For this case, <filename>runqemu</filename> set the
266 internal variable <filename>FSTYPE</filename> to
267 "cpio.gz".
268 Also, for audio to be enabled, an appropriate driver must
269 be installed (see the previous description for the
270 <filename>audio</filename> option for more information).
271 <literallayout class='monospaced'>
272 $ runqemu qemux86 ramfs audio
273 </literallayout>
274 This example does not provide enough information for
275 QEMU to launch.
276 While the command does provide a root filesystem type, it
277 must also minimally provide a
278 <replaceable>MACHINE</replaceable>,
279 <replaceable>KERNEL</replaceable>, or
280 <replaceable>VM</replaceable> option.
281 <literallayout class='monospaced'>
282 $ runqemu ext3
283 </literallayout>
284 This example specifies to boot a virtual machine image
285 (<filename>.vmdk</filename> file).
286 From the <filename>.vmdk</filename>,
287 <filename>runqemu</filename> determines the QEMU
288 architecture (<replaceable>MACHINE</replaceable>) to be
289 "qemux86" and the root filesystem type to be "vmdk".
290 <literallayout class='monospaced'>
291 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
292 </literallayout>
293 </para>
294 </section>
295</section>
296
297<section id='qemu-running-under-a-network-file-system-nfs-server'>
298 <title>Running Under a Network File System (NFS) Server</title>
299
300 <para>
301 One method for running QEMU is to run it on an NFS server.
302 This is useful when you need to access the same file system from both
303 the build and the emulated system at the same time.
304 It is also worth noting that the system does not need root privileges
305 to run.
306 It uses a user space NFS server to avoid that.
307 This section describes how to set up for running QEMU using an NFS
308 server and then how you can start and stop the server.
309 </para>
310
311 <section id='qemu-setting-up-to-use-nfs'>
312 <title>Setting Up to Use NFS</title>
313
314 <para>
315 Once you are able to run QEMU in your environment, you can use the
316 <filename>runqemu-extract-sdk</filename> script, which is located
317 in the <filename>scripts</filename> directory along with
318 <filename>runqemu</filename> script.
319 The <filename>runqemu-extract-sdk</filename> takes a root
320 file system tarball and extracts it into a location that you
321 specify.
322 Then, when you run <filename>runqemu</filename>, you can specify
323 the location that has the file system to pass it to QEMU.
324 Here is an example that takes a file system and extracts it to
325 a directory named <filename>test-nfs</filename>:
326 <literallayout class='monospaced'>
327 runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
328 </literallayout>
329 Once you have extracted the file system, you can run
330 <filename>runqemu</filename> normally with the additional
331 location of the file system.
332 You can then also make changes to the files within
333 <filename>./test-nfs</filename> and see those changes appear in the
334 image in real time.
335 Here is an example using the <filename>qemux86</filename> image:
336 <literallayout class='monospaced'>
337 runqemu qemux86 ./test-nfs
338 </literallayout>
339 </para>
340 </section>
341
342 <section id='qemu-starting-and-stopping-nfs'>
343 <title>Starting and Stopping NFS</title>
344
345 <para>
346 You can manually start and stop the NFS share using these
347 commands:
348 <itemizedlist>
349 <listitem><para><emphasis><filename>start</filename>:</emphasis>
350 Starts the NFS share:
351 <literallayout class='monospaced'>
352 runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
353 </literallayout>
354 </para></listitem>
355 <listitem><para><emphasis><filename>stop</filename>:</emphasis>
356 Stops the NFS share:
357 <literallayout class='monospaced'>
358 runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
359 </literallayout>
360 </para></listitem>
361 <listitem><para><emphasis><filename>restart</filename>:</emphasis>
362 Restarts the NFS share:
363 <literallayout class='monospaced'>
364 runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
365 </literallayout>
366 </para></listitem>
367 </itemizedlist>
368 </para>
369 </section>
370</section>
371
372<section id='qemu-tips-and-tricks'>
373 <title>Tips and Tricks</title>
374
375 <para>
376 The following list describes things you can do to make running QEMU
377 in the context of the Yocto Project a better experience:
378 <itemizedlist>
379 <listitem><para><emphasis>Switching Between Consoles:</emphasis>
380 When booting or running QEMU, you can switch between
381 supported consoles by using
382 Ctrl+Alt+<replaceable>number</replaceable>.
383 For example, Ctrl+Alt+3 switches you to the serial console as
384 long as that console is enabled.
385 Being able to switch consoles is helpful, for example, if the
386 main QEMU console breaks for some reason.
387 <note>
388 Usually, "2" gets you to the main console and "3" gets you
389 to the serial console.
390 </note>
391 </para></listitem>
392 <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
393 You can remove the splash screen when QEMU is booting by
394 using Alt+left.
395 Removing the splash screen allows you to see what is happening
396 in the background.
397 </para></listitem>
398 <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
399 The default QEMU integration captures the cursor within the
400 main window.
401 It does this since standard mouse devices only provide relative
402 input and not absolute coordinates.
403 You then have to break out of the grab using the "Ctrl+Alt" key
404 combination.
405 However, the Yocto Project's integration of QEMU enables the
406 wacom USB touch pad driver by default to allow input of absolute
407 coordinates.
408 This default means that the mouse can enter and leave the
409 main window without the grab taking effect leading to a better
410 user experience.
411 </para></listitem>
412 </itemizedlist>
413 </para>
414</section>
415
416</chapter>
417<!--
418vim: expandtab tw=80 ts=4
419-->
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000000..61434ff72c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,418 @@
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='dev-manual-start'>
6
7<title>Getting Started with the Yocto Project</title>
8
9<para>
10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
11 You can find enough information to set up your development host and build or use images for
12 hardware supported by the Yocto Project by reading the
13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
14</para>
15
16<para>
17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
18 some higher-level concepts you might want to consider.
19</para>
20
21<section id='introducing-the-yocto-project'>
22 <title>Introducing the Yocto Project</title>
23
24 <para>
25 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
26 The project currently provides a build system that is
27 referred to as the
28 <link linkend='build-system-term'>OpenEmbedded build system</link>
29 in the Yocto Project documentation.
30 The Yocto Project provides various ancillary tools for the embedded developer
31 and also features the Sato reference User Interface, which is optimized for
32 stylus driven, low-resolution screens.
33 </para>
34
35 <para>
36 You can use the OpenEmbedded build system, which uses
37 <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux
38 images and associated user-space applications for architectures based
39 on ARM, MIPS, PowerPC, x86 and x86-64.
40 <note>
41 By default, using the Yocto Project creates a Poky distribution.
42 However, you can create your own distribution by providing key
43 <link linkend='metadata'>Metadata</link>.
44 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
45 section for more information.
46 </note>
47 While the Yocto Project does not provide a strict testing framework,
48 it does provide or generate for you artifacts that let you perform target-level and
49 emulated testing and debugging.
50 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
51 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
52 develop within that familiar environment.
53 </para>
54</section>
55
56<section id='getting-setup'>
57 <title>Getting Set Up</title>
58
59 <para>
60 Here is what you need to use the Yocto Project:
61 <itemizedlist>
62 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
63 Linux-based host system.
64 You will have the best results with a recent release of Fedora,
65 openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
66 and officially supported.
67 For a list of the distributions under validation and their status, see the
68 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
69 in the Yocto Project Reference Manual and the wiki page at
70 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
71 <para>
72 You should also have about 50 Gbytes of free disk space for building images.
73 </para></listitem>
74 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
75 requires that certain packages exist on your development system (e.g. Python 2.6 or 2.7).
76 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
77 section in the Yocto Project Quick Start and the
78 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
79 section in the Yocto Project Reference Manual for the exact
80 package requirements and the installation commands to install
81 them for the supported distributions.
82 </para></listitem>
83 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
84 You need a release of the Yocto Project locally installed on
85 your development system.
86 The documentation refers to this set of locally installed files
87 as the <link linkend='source-directory'>Source Directory</link>.
88 You create your Source Directory by using
89 <link linkend='git'>Git</link> to clone a local copy
90 of the upstream <filename>poky</filename> repository,
91 or by downloading and unpacking a tarball of an official
92 Yocto Project release.
93 The preferred method is to create a clone of the repository.
94 </para>
95 <para>Working from a copy of the upstream repository allows you
96 to contribute back into the Yocto Project or simply work with
97 the latest software on a development branch.
98 Because Git maintains and creates an upstream repository with
99 a complete history of changes and you are working with a local
100 clone of that repository, you have access to all the Yocto
101 Project development branches and tag names used in the upstream
102 repository.</para>
103 <note>You can view the Yocto Project Source Repositories at
104 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>
105 </note>
106 <para>The following transcript shows how to clone the
107 <filename>poky</filename> Git repository into the current
108 working directory.
109 The command creates the local repository in a directory
110 named <filename>poky</filename>.
111 For information on Git used within the Yocto Project, see
112 the "<link linkend='git'>Git</link>" section.
113 <literallayout class='monospaced'>
114 $ git clone git://git.yoctoproject.org/poky
115 Cloning into 'poky'...
116 remote: Counting objects: 226790, done.
117 remote: Compressing objects: 100% (57465/57465), done.
118 remote: Total 226790 (delta 165212), reused 225887 (delta 164327)
119 Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
120 Resolving deltas: 100% (165212/165212), done.
121 </literallayout></para>
122 <para>For another example of how to set up your own local Git
123 repositories, see this
124 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
125 wiki page</ulink>, which describes how to create local
126 Git repositories for both
127 <filename>poky</filename> and <filename>meta-intel</filename>.
128 </para></listitem>
129 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
130 If you are going to be making modifications to a supported Yocto Project kernel, you
131 need to establish local copies of the source.
132 You can find Git repositories of supported Yocto Project kernels organized under
133 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
134 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
135 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
136 copying that cloned repository.
137 You can create the bare clone and the copy of the bare clone anywhere you like.
138 For simplicity, it is recommended that you create these structures outside of the
139 Source Directory, which is usually named <filename>poky</filename>.</para>
140 <para>As an example, the following transcript shows how to create the bare clone
141 of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of
142 that clone.
143 <note>When you have a local Yocto Project kernel Git repository, you can
144 reference that repository rather than the upstream Git repository as
145 part of the <filename>clone</filename> command.
146 Doing so can speed up the process.</note></para>
147 <para>In the following example, the bare clone is named
148 <filename>linux-yocto-3.10.git</filename>, while the
149 copy is named <filename>my-linux-yocto-3.10-work</filename>:
150 <literallayout class='monospaced'>
151 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git
152 Cloning into bare repository 'linux-yocto-3.10.git'...
153 remote: Counting objects: 3364487, done.
154 remote: Compressing objects: 100% (507178/507178), done.
155 remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709)
156 Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done.
157 Resolving deltas: 100% (2827715/2827715), done.
158 </literallayout></para>
159 <para>Now create a clone of the bare clone just created:
160 <literallayout class='monospaced'>
161 $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work
162 Cloning into 'my-linux-yocto-3.10-work'...
163 done.
164 </literallayout></para></listitem>
165 <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
166 The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
167 The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
168 only if you are modifying and building the kernel image.
169 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
170 files that you
171 edit to point to your locally modified kernel source files and to build the kernel
172 image.
173 Pointing to these local files is much more efficient than requiring a download of the
174 kernel's source files from upstream each time you make changes to the kernel.</para>
175 <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
176 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
177 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
178 It is good practice to create this Git repository inside the Source Directory.</para>
179 <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
180 repository inside the Source Directory, which is named <filename>poky</filename>
181 in this case:
182 <literallayout class='monospaced'>
183 $ cd ~/poky
184 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
185 Cloning into 'meta-yocto-kernel-extras'...
186 remote: Counting objects: 727, done.
187 remote: Compressing objects: 100% (452/452), done.
188 remote: Total 727 (delta 260), reused 719 (delta 252)
189 Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done.
190 Resolving deltas: 100% (260/260), done.
191 </literallayout></para></listitem>
192 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis>
193 The Yocto Project supports many BSPs, which are maintained in
194 their own layers or in layers designed to contain several
195 BSPs.
196 To get an idea of machine support through BSP layers, you can
197 look at the
198 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
199 for the release.</para>
200
201 <para>The Yocto Project uses the following BSP layer naming
202 scheme:
203 <literallayout class='monospaced'>
204 meta-<replaceable>bsp_name</replaceable>
205 </literallayout>
206 where <replaceable>bsp_name</replaceable> is the recognized
207 BSP name.
208 Here are some examples:
209 <literallayout class='monospaced'>
210 meta-crownbay
211 meta-emenlow
212 meta-n450
213 </literallayout>
214 See the
215 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
216 section in the Yocto Project Board Support Package (BSP)
217 Developer's Guide for more information on BSP Layers.</para>
218
219 <para>A useful Git repository released with the Yocto
220 Project is <filename>meta-intel</filename>, which is a
221 parent layer that contains many supported
222 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.
223 You can locate the <filename>meta-intel</filename> Git
224 repository in the "Yocto Metadata Layers" area of the Yocto
225 Project Source Repositories at
226 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
227
228 <para>Using
229 <link linkend='git'>Git</link> to create a local clone of the
230 upstream repository can be helpful if you are working with
231 BSPs.
232 Typically, you set up the <filename>meta-intel</filename>
233 Git repository inside the Source Directory.
234 For example, the following transcript shows the steps to clone
235 <filename>meta-intel</filename>.
236 <note>
237 Be sure to work in the <filename>meta-intel</filename>
238 branch that matches your
239 <link linkend='source-directory'>Source Directory</link>
240 (i.e. <filename>poky</filename>) branch.
241 For example, if you have checked out the "master" branch
242 of <filename>poky</filename> and you are going to use
243 <filename>meta-intel</filename>, be sure to checkout the
244 "master" branch of <filename>meta-intel</filename>.
245 </note>
246 <literallayout class='monospaced'>
247 $ cd ~/poky
248 $ git clone git://git.yoctoproject.org/meta-intel.git
249 Cloning into 'meta-intel'...
250 remote: Counting objects: 8844, done.
251 remote: Compressing objects: 100% (2864/2864), done.
252 remote: Total 8844 (delta 4931), reused 8780 (delta 4867)
253 Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done.
254 Resolving deltas: 100% (4931/4931), done.
255 </literallayout></para>
256
257 <para>The same
258 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>
259 referenced earlier covers how to set up the
260 <filename>meta-intel</filename> Git repository.
261 </para></listitem>
262 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
263 applications using the Eclipse Integrated Development Environment (IDE),
264 you will need this plug-in.
265 See the
266 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
267 section for more information.</para></listitem>
268 </itemizedlist>
269 </para>
270</section>
271
272<section id='building-images'>
273 <title>Building Images</title>
274
275 <para>
276 The build process creates an entire Linux distribution, including the toolchain, from source.
277 For more information on this topic, see the
278 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
279 section in the Yocto Project Quick Start.
280 </para>
281
282 <para>
283 The build process is as follows:
284 <orderedlist>
285 <listitem><para>Make sure you have set up the Source Directory described in the
286 previous section.</para></listitem>
287 <listitem><para>Initialize the build environment by sourcing a build
288 environment script (i.e.
289 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
290 or
291 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
292 </para></listitem>
293 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
294 which is found in the
295 <link linkend='build-directory'>Build Directory</link>,
296 is set up how you want it.
297 This file defines many aspects of the build environment including
298 the target machine architecture through the
299 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
300 the development machine's processor use through the
301 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
302 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
303 a centralized tarball download directory through the
304 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
305 <listitem><para>
306 Build the image using the <filename>bitbake</filename> command.
307 If you want information on BitBake, see the
308 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
309 </para></listitem>
310 <listitem><para>Run the image either on the actual hardware or using the QEMU
311 emulator.</para></listitem>
312 </orderedlist>
313 </para>
314</section>
315
316<section id='using-pre-built-binaries-and-qemu'>
317 <title>Using Pre-Built Binaries and QEMU</title>
318
319 <para>
320 Another option you have to get started is to use pre-built binaries.
321 The Yocto Project provides many types of binaries with each release.
322 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
323 chapter in the Yocto Project Reference Manual
324 for descriptions of the types of binaries that ship with a Yocto Project
325 release.
326 </para>
327
328 <para>
329 Using a pre-built binary is ideal for developing software applications to run on your
330 target hardware.
331 To do this, you need to be able to access the appropriate cross-toolchain tarball for
332 the architecture on which you are developing.
333 If you are using an SDK type image, the image ships with the complete toolchain native to
334 the architecture.
335 If you are not using an SDK type image, you need to separately download and
336 install the stand-alone Yocto Project cross-toolchain tarball.
337 </para>
338
339 <para>
340 Regardless of the type of image you are using, you need to download the pre-built kernel
341 that you will boot in the QEMU emulator and then download and extract the target root
342 filesystem for your target machine’s architecture.
343 You can get architecture-specific binaries and file systems from
344 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
345 You can get installation scripts for stand-alone toolchains from
346 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
347 Once you have all your files, you set up the environment to emulate the hardware
348 by sourcing an environment setup script.
349 Finally, you start the QEMU emulator.
350 You can find details on all these steps in the
351 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
352 section of the Yocto Project Quick Start.
353 You can learn more about using QEMU with the Yocto Project in the
354 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
355 section.
356 </para>
357
358 <para>
359 Using QEMU to emulate your hardware can result in speed issues
360 depending on the target and host architecture mix.
361 For example, using the <filename>qemux86</filename> image in the emulator
362 on an Intel-based 32-bit (x86) host machine is fast because the target and
363 host architectures match.
364 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
365 host can be slower.
366 But, you still achieve faithful emulation of ARM-specific issues.
367 </para>
368
369 <para>
370 To speed things up, the QEMU images support using <filename>distcc</filename>
371 to call a cross-compiler outside the emulated system.
372 If you used <filename>runqemu</filename> to start QEMU, and the
373 <filename>distccd</filename> application is present on the host system, any
374 BitBake cross-compiling toolchain available from the build system is automatically
375 used from within QEMU simply by calling <filename>distcc</filename>.
376 You can accomplish this by defining the cross-compiler variable
377 (e.g. <filename>export CC="distcc"</filename>).
378 Alternatively, if you are using a suitable SDK image or the appropriate
379 stand-alone toolchain is present,
380 the toolchain is also automatically used.
381 </para>
382
383 <note>
384 Several mechanisms exist that let you connect to the system running on the
385 QEMU emulator:
386 <itemizedlist>
387 <listitem><para>QEMU provides a framebuffer interface that makes standard
388 consoles available.</para></listitem>
389 <listitem><para>Generally, headless embedded devices have a serial port.
390 If so, you can configure the operating system of the running image
391 to use that port to run a console.
392 The connection uses standard IP networking.</para></listitem>
393 <listitem><para>
394 SSH servers exist in some QEMU images.
395 The <filename>core-image-sato</filename> QEMU image has a
396 Dropbear secure shell (SSH) server that runs with the root
397 password disabled.
398 The <filename>core-image-full-cmdline</filename> and
399 <filename>core-image-lsb</filename> QEMU images
400 have OpenSSH instead of Dropbear.
401 Including these SSH servers allow you to use standard
402 <filename>ssh</filename> and <filename>scp</filename> commands.
403 The <filename>core-image-minimal</filename> QEMU image,
404 however, contains no SSH server.
405 </para></listitem>
406 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
407 using a local copy of the root filesystem on the host.
408 In order to make this connection, you must extract a root filesystem tarball by using the
409 <filename>runqemu-extract-sdk</filename> command.
410 After running the command, you must then point the <filename>runqemu</filename>
411 script to the extracted directory instead of a root filesystem image file.</para></listitem>
412 </itemizedlist>
413 </note>
414</section>
415</chapter>
416<!--
417vim: expandtab tw=80 ts=4
418-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
new file mode 100644
index 0000000000..4e498b8201
--- /dev/null
+++ b/documentation/dev-manual/dev-manual.xml
@@ -0,0 +1,124 @@
1<!DOCTYPE book 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<book id='dev-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/dev-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Development Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Scott</firstname> <surname>Rifenbark</surname>
26 <affiliation>
27 <orgname>Intel Corporation</orgname>
28 </affiliation>
29 <email>scott.m.rifenbark@intel.com</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.1</revnumber>
36 <date>6 October 2011</date>
37 <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.2</revnumber>
41 <date>April 2012</date>
42 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>1.3</revnumber>
46 <date>October 2012</date>
47 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.4</revnumber>
51 <date>April 2013</date>
52 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.5</revnumber>
56 <date>October 2013</date>
57 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>1.5.1</revnumber>
61 <date>January 2014</date>
62 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>1.6</revnumber>
66 <date>April 2014</date>
67 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>1.7</revnumber>
71 <date>October 2014</date>
72 <revremark>Released with the Yocto Project 1.7 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>1.7.1</revnumber>
76 <date>January 2015</date>
77 <revremark>Released with the Yocto Project 1.7.1 Release.</revremark>
78 </revision>
79 <revision>
80 <revnumber>1.7.2</revnumber>
81 <date>June 2015</date>
82 <revremark>Released with the Yocto Project 1.7.2 Release.</revremark>
83 </revision>
84 </revhistory>
85
86 <copyright>
87 <year>&COPYRIGHT_YEAR;</year>
88 <holder>Linux Foundation</holder>
89 </copyright>
90
91 <legalnotice>
92 <para>
93 Permission is granted to copy, distribute and/or modify this document under
94 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
95 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
96 Creative Commons.
97 </para>
98
99 <note>
100 For the latest version of this manual associated with this
101 Yocto Project release, see the
102 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
103 from the Yocto Project website.
104 </note>
105 </legalnotice>
106
107 </bookinfo>
108
109 <xi:include href="dev-manual-intro.xml"/>
110
111 <xi:include href="dev-manual-start.xml"/>
112
113 <xi:include href="dev-manual-newbie.xml"/>
114
115 <xi:include href="dev-manual-model.xml"/>
116
117 <xi:include href="dev-manual-common-tasks.xml"/>
118
119 <xi:include href="dev-manual-qemu.xml"/>
120
121</book>
122<!--
123vim: expandtab tw=80 ts=4
124-->
diff --git a/documentation/dev-manual/dev-style.css b/documentation/dev-manual/dev-style.css
new file mode 100644
index 0000000000..b900ffc9b2
--- /dev/null
+++ b/documentation/dev-manual/dev-style.css
@@ -0,0 +1,984 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/dev-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316/* This style defines how the permalink character
317 appears by itself and when hovered over with
318 the mouse. */
319
320[alt='Permalink'] { color: #eee; }
321[alt='Permalink']:hover { color: black; }
322
323
324div.informalfigure,
325div.informalexample,
326div.informaltable,
327div.figure,
328div.table,
329div.example {
330 margin: 1em 0em;
331 padding: 1em;
332 page-break-inside: avoid;
333}
334
335
336div.informalfigure p.title b,
337div.informalexample p.title b,
338div.informaltable p.title b,
339div.figure p.title b,
340div.example p.title b,
341div.table p.title b{
342 padding-top: 0em;
343 margin-top: 0em;
344 font-size: 100%;
345 font-weight: normal;
346}
347
348.mediaobject .caption,
349.mediaobject .caption p {
350 text-align: center;
351 font-size: 80%;
352 padding-top: 0.5em;
353 padding-bottom: 0.5em;
354}
355
356.epigraph {
357 padding-left: 55%;
358 margin-bottom: 1em;
359}
360
361.epigraph p {
362 text-align: left;
363}
364
365.epigraph .quote {
366 font-style: italic;
367}
368.epigraph .attribution {
369 font-style: normal;
370 text-align: right;
371}
372
373span.application {
374 font-style: italic;
375}
376
377.programlisting {
378 font-family: monospace;
379 font-size: 80%;
380 white-space: pre;
381 margin: 1.33em 0em;
382 padding: 1.33em;
383}
384
385.tip,
386.warning,
387.caution,
388.note {
389 margin-top: 1em;
390 margin-bottom: 1em;
391
392}
393
394/* force full width of table within div */
395.tip table,
396.warning table,
397.caution table,
398.note table {
399 border: none;
400 width: 100%;
401}
402
403
404.tip table th,
405.warning table th,
406.caution table th,
407.note table th {
408 padding: 0.8em 0.0em 0.0em 0.0em;
409 margin : 0em 0em 0em 0em;
410}
411
412.tip p,
413.warning p,
414.caution p,
415.note p {
416 margin-top: 0.5em;
417 margin-bottom: 0.5em;
418 padding-right: 1em;
419 text-align: left;
420}
421
422.acronym {
423 text-transform: uppercase;
424}
425
426b.keycap,
427.keycap {
428 padding: 0.09em 0.3em;
429 margin: 0em;
430}
431
432.itemizedlist li {
433 clear: none;
434}
435
436.filename {
437 font-size: medium;
438 font-family: Courier, monospace;
439}
440
441
442div.navheader, div.heading{
443 position: absolute;
444 left: 0em;
445 top: 0em;
446 width: 100%;
447 background-color: #cdf;
448 width: 100%;
449}
450
451div.navfooter, div.footing{
452 position: fixed;
453 left: 0em;
454 bottom: 0em;
455 background-color: #eee;
456 width: 100%;
457}
458
459
460div.navheader td,
461div.navfooter td {
462 font-size: 66%;
463}
464
465div.navheader table th {
466 /*font-family: Georgia, Times, serif;*/
467 /*font-size: x-large;*/
468 font-size: 80%;
469}
470
471div.navheader table {
472 border-left: 0em;
473 border-right: 0em;
474 border-top: 0em;
475 width: 100%;
476}
477
478div.navfooter table {
479 border-left: 0em;
480 border-right: 0em;
481 border-bottom: 0em;
482 width: 100%;
483}
484
485div.navheader table td a,
486div.navfooter table td a {
487 color: #777;
488 text-decoration: none;
489}
490
491/* normal text in the footer */
492div.navfooter table td {
493 color: black;
494}
495
496div.navheader table td a:visited,
497div.navfooter table td a:visited {
498 color: #444;
499}
500
501
502/* links in header and footer */
503div.navheader table td a:hover,
504div.navfooter table td a:hover {
505 text-decoration: underline;
506 background-color: transparent;
507 color: #33a;
508}
509
510div.navheader hr,
511div.navfooter hr {
512 display: none;
513}
514
515
516.qandaset tr.question td p {
517 margin: 0em 0em 1em 0em;
518 padding: 0em 0em 0em 0em;
519}
520
521.qandaset tr.answer td p {
522 margin: 0em 0em 1em 0em;
523 padding: 0em 0em 0em 0em;
524}
525.answer td {
526 padding-bottom: 1.5em;
527}
528
529.emphasis {
530 font-weight: bold;
531}
532
533
534 /************* /
535 / decorations /
536/ *************/
537
538.titlepage {
539}
540
541.part .title {
542}
543
544.subtitle {
545 border: none;
546}
547
548/*
549h1 {
550 border: none;
551}
552
553h2 {
554 border-top: solid 0.2em;
555 border-bottom: solid 0.06em;
556}
557
558h3 {
559 border-top: 0em;
560 border-bottom: solid 0.06em;
561}
562
563h4 {
564 border: 0em;
565 border-bottom: solid 0.06em;
566}
567
568h5 {
569 border: 0em;
570}
571*/
572
573.programlisting {
574 border: solid 1px;
575}
576
577div.figure,
578div.table,
579div.informalfigure,
580div.informaltable,
581div.informalexample,
582div.example {
583 border: 1px solid;
584}
585
586
587
588.tip,
589.warning,
590.caution,
591.note {
592 border: 1px solid;
593}
594
595.tip table th,
596.warning table th,
597.caution table th,
598.note table th {
599 border-bottom: 1px solid;
600}
601
602.question td {
603 border-top: 1px solid black;
604}
605
606.answer {
607}
608
609
610b.keycap,
611.keycap {
612 border: 1px solid;
613}
614
615
616div.navheader, div.heading{
617 border-bottom: 1px solid;
618}
619
620
621div.navfooter, div.footing{
622 border-top: 1px solid;
623}
624
625 /********* /
626 / colors /
627/ *********/
628
629body {
630 color: #333;
631 background: white;
632}
633
634a {
635 background: transparent;
636}
637
638a:hover {
639 background-color: #dedede;
640}
641
642
643h1,
644h2,
645h3,
646h4,
647h5,
648h6,
649h7,
650h8 {
651 background-color: transparent;
652}
653
654hr {
655 border-color: #aaa;
656}
657
658
659.tip, .warning, .caution, .note {
660 border-color: #fff;
661}
662
663
664.tip table th,
665.warning table th,
666.caution table th,
667.note table th {
668 border-bottom-color: #fff;
669}
670
671
672.warning {
673 background-color: #f0f0f2;
674}
675
676.caution {
677 background-color: #f0f0f2;
678}
679
680.tip {
681 background-color: #f0f0f2;
682}
683
684.note {
685 background-color: #f0f0f2;
686}
687
688.glossary dl dt,
689.variablelist dl dt,
690.variablelist dl dt span.term {
691 color: #044;
692}
693
694div.figure,
695div.table,
696div.example,
697div.informalfigure,
698div.informaltable,
699div.informalexample {
700 border-color: #aaa;
701}
702
703pre.programlisting {
704 color: black;
705 background-color: #fff;
706 border-color: #aaa;
707 border-width: 2px;
708}
709
710.guimenu,
711.guilabel,
712.guimenuitem {
713 background-color: #eee;
714}
715
716
717b.keycap,
718.keycap {
719 background-color: #eee;
720 border-color: #999;
721}
722
723
724div.navheader {
725 border-color: black;
726}
727
728
729div.navfooter {
730 border-color: black;
731}
732
733
734 /*********** /
735 / graphics /
736/ ***********/
737
738/*
739body {
740 background-image: url("images/body_bg.jpg");
741 background-attachment: fixed;
742}
743
744.navheader,
745.note,
746.tip {
747 background-image: url("images/note_bg.jpg");
748 background-attachment: fixed;
749}
750
751.warning,
752.caution {
753 background-image: url("images/warning_bg.jpg");
754 background-attachment: fixed;
755}
756
757.figure,
758.informalfigure,
759.example,
760.informalexample,
761.table,
762.informaltable {
763 background-image: url("images/figure_bg.jpg");
764 background-attachment: fixed;
765}
766
767*/
768h1,
769h2,
770h3,
771h4,
772h5,
773h6,
774h7{
775}
776
777/*
778Example of how to stick an image as part of the title.
779
780div.article .titlepage .title
781{
782 background-image: url("figures/white-on-black.png");
783 background-position: center;
784 background-repeat: repeat-x;
785}
786*/
787
788div.preface .titlepage .title,
789div.colophon .title,
790div.chapter .titlepage .title,
791div.article .titlepage .title
792{
793}
794
795div.section div.section .titlepage .title,
796div.sect2 .titlepage .title {
797 background: none;
798}
799
800
801h1.title {
802 background-color: transparent;
803 background-repeat: no-repeat;
804 height: 256px;
805 text-indent: -9000px;
806 overflow:hidden;
807}
808
809h2.subtitle {
810 background-color: transparent;
811 text-indent: -9000px;
812 overflow:hidden;
813 width: 0px;
814 display: none;
815}
816
817 /*************************************** /
818 / pippin.gimp.org specific alterations /
819/ ***************************************/
820
821/*
822div.heading, div.navheader {
823 color: #777;
824 font-size: 80%;
825 padding: 0;
826 margin: 0;
827 text-align: left;
828 position: absolute;
829 top: 0px;
830 left: 0px;
831 width: 100%;
832 height: 50px;
833 background: url('/gfx/heading_bg.png') transparent;
834 background-repeat: repeat-x;
835 background-attachment: fixed;
836 border: none;
837}
838
839div.heading a {
840 color: #444;
841}
842
843div.footing, div.navfooter {
844 border: none;
845 color: #ddd;
846 font-size: 80%;
847 text-align:right;
848
849 width: 100%;
850 padding-top: 10px;
851 position: absolute;
852 bottom: 0px;
853 left: 0px;
854
855 background: url('/gfx/footing_bg.png') transparent;
856}
857*/
858
859
860
861 /****************** /
862 / nasty ie tweaks /
863/ ******************/
864
865/*
866div.heading, div.navheader {
867 width:expression(document.body.clientWidth + "px");
868}
869
870div.footing, div.navfooter {
871 width:expression(document.body.clientWidth + "px");
872 margin-left:expression("-5em");
873}
874body {
875 padding:expression("4em 5em 0em 5em");
876}
877*/
878
879 /**************************************** /
880 / mozilla vendor specific css extensions /
881/ ****************************************/
882/*
883div.navfooter, div.footing{
884 -moz-opacity: 0.8em;
885}
886
887div.figure,
888div.table,
889div.informalfigure,
890div.informaltable,
891div.informalexample,
892div.example,
893.tip,
894.warning,
895.caution,
896.note {
897 -moz-border-radius: 0.5em;
898}
899
900b.keycap,
901.keycap {
902 -moz-border-radius: 0.3em;
903}
904*/
905
906table tr td table tr td {
907 display: none;
908}
909
910
911hr {
912 display: none;
913}
914
915table {
916 border: 0em;
917}
918
919 .photo {
920 float: right;
921 margin-left: 1.5em;
922 margin-bottom: 1.5em;
923 margin-top: 0em;
924 max-width: 17em;
925 border: 1px solid gray;
926 padding: 3px;
927 background: white;
928}
929 .seperator {
930 padding-top: 2em;
931 clear: both;
932 }
933
934 #validators {
935 margin-top: 5em;
936 text-align: right;
937 color: #777;
938 }
939 @media print {
940 body {
941 font-size: 8pt;
942 }
943 .noprint {
944 display: none;
945 }
946 }
947
948
949.tip,
950.note {
951 background: #f0f0f2;
952 color: #333;
953 padding: 20px;
954 margin: 20px;
955}
956
957.tip h3,
958.note h3 {
959 padding: 0em;
960 margin: 0em;
961 font-size: 2em;
962 font-weight: bold;
963 color: #333;
964}
965
966.tip a,
967.note a {
968 color: #333;
969 text-decoration: underline;
970}
971
972.footnote {
973 font-size: small;
974 color: #333;
975}
976
977/* Changes the announcement text */
978.tip h3,
979.warning h3,
980.caution h3,
981.note h3 {
982 font-size:large;
983 color: #00557D;
984}
diff --git a/documentation/dev-manual/figures/app-dev-flow.png b/documentation/dev-manual/figures/app-dev-flow.png
new file mode 100644
index 0000000000..ec93374ee7
--- /dev/null
+++ b/documentation/dev-manual/figures/app-dev-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/bsp-dev-flow.png b/documentation/dev-manual/figures/bsp-dev-flow.png
new file mode 100644
index 0000000000..540b0abb9f
--- /dev/null
+++ b/documentation/dev-manual/figures/bsp-dev-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/dev-title.png b/documentation/dev-manual/figures/dev-title.png
new file mode 100644
index 0000000000..d3cac4a7e5
--- /dev/null
+++ b/documentation/dev-manual/figures/dev-title.png
Binary files differ
diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/dev-manual/figures/git-workflow.png
new file mode 100644
index 0000000000..e401330a12
--- /dev/null
+++ b/documentation/dev-manual/figures/git-workflow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/index-downloads.png b/documentation/dev-manual/figures/index-downloads.png
new file mode 100644
index 0000000000..41251d5d18
--- /dev/null
+++ b/documentation/dev-manual/figures/index-downloads.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png
new file mode 100644
index 0000000000..009105d122
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-dev-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png
new file mode 100644
index 0000000000..116c0b9bd4
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-1.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png
new file mode 100644
index 0000000000..889ff1bf0d
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-2-generic.png
Binary files differ
diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png
new file mode 100644
index 0000000000..c0e960b13b
--- /dev/null
+++ b/documentation/dev-manual/figures/recipe-workflow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/source-repos.png b/documentation/dev-manual/figures/source-repos.png
new file mode 100644
index 0000000000..65c5f29a43
--- /dev/null
+++ b/documentation/dev-manual/figures/source-repos.png
Binary files differ
diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png
new file mode 100644
index 0000000000..5770be6883
--- /dev/null
+++ b/documentation/dev-manual/figures/yp-download.png
Binary files differ