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.xml5913
-rw-r--r--documentation/dev-manual/dev-manual-customization.xsl10
-rw-r--r--documentation/dev-manual/dev-manual-eclipse-customization.xsl27
-rw-r--r--documentation/dev-manual/dev-manual-intro.xml210
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2058
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml1575
-rw-r--r--documentation/dev-manual/dev-manual-start.xml407
-rw-r--r--documentation/dev-manual/dev-manual.xml102
-rw-r--r--documentation/dev-manual/dev-style.css979
-rw-r--r--documentation/dev-manual/figures/app-dev-flow.pngbin0 -> 53301 bytes
-rw-r--r--documentation/dev-manual/figures/bsp-dev-flow.pngbin0 -> 56047 bytes
-rw-r--r--documentation/dev-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/dev-manual/figures/git-workflow.pngbin0 -> 26610 bytes
-rw-r--r--documentation/dev-manual/figures/index-downloads.pngbin0 -> 100374 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin0 -> 45225 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/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/dev-manual/figures/yp-download.pngbin0 -> 193275 bytes
19 files changed, 11281 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..e2e89a032c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,5913 @@
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 the procedures documented here occur often in the
13 develop 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 you organize 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 Specific 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 are layers begin with the string
64 <filename>meta</filename>.
65 <note>
66 It is not a requirement that a layer begins with the
67 string <filename>meta</filename>.
68 </note>
69 For example, when you set up the Source Directory structure,
70 you will see several layers:
71 <filename>meta</filename>, <filename>meta-hob</filename>,
72 <filename>meta-skeleton</filename>,
73 <filename>meta-yocto</filename>, and
74 <filename>meta-yocto-bsp</filename>.
75 Each of these folders is a layer.
76 </para>
77
78 <para>
79 Furthermore, if you set up a local copy of the
80 <filename>meta-intel</filename> Git repository
81 and then explore the folder of that general layer,
82 you will discover many BSP layers inside.
83 For more information on BSP layers, see the
84 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
85 section in the Yocto Project Board Support Package (BSP)
86 Developer's Guide.
87 </para>
88 </section>
89
90 <section id='creating-your-own-layer'>
91 <title>Creating Your Own Layer</title>
92
93 <para>
94 It is very easy to create your own layers to use with the
95 OpenEmbedded build system.
96 The Yocto Project ships with scripts that speed up creating
97 general layers and BSP layers.
98 This section describes the steps you perform by hand to create
99 a layer so that you can better understand them.
100 For information about the layer-creation scripts, see the
101 "<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>"
102 section in the Yocto Project Board Support Package (BSP)
103 Developer's Guide and the
104 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
105 section further down in this manual.
106 </para>
107
108 <para>
109 Follow these general steps to create your layer:
110 <orderedlist>
111 <listitem><para><emphasis>Check Existing Layers:</emphasis>
112 Before creating a new layer, you should be sure someone
113 has not already created a layer containing the Metadata
114 you need.
115 You can see the
116 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
117 for a list of layers from the OpenEmbedded community
118 that can be used in the Yocto Project.
119 </para></listitem>
120 <listitem><para><emphasis>Create a Directory:</emphasis>
121 Create the directory for your layer.
122 While not strictly required, prepend the name of the
123 folder with the string <filename>meta-</filename>.
124 For example:
125 <literallayout class='monospaced'>
126 meta-mylayer
127 meta-GUI_xyz
128 meta-mymachine
129 </literallayout>
130 </para></listitem>
131 <listitem><para><emphasis>Create a Layer Configuration
132 File:</emphasis>
133 Inside your new layer folder, you need to create a
134 <filename>conf/layer.conf</filename> file.
135 It is easiest to take an existing layer configuration
136 file and copy that to your layer's
137 <filename>conf</filename> directory and then modify the
138 file as needed.</para>
139 <para>The
140 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
141 demonstrates the required syntax:
142 <literallayout class='monospaced'>
143 # We have a conf and classes directory, add to BBPATH
144 BBPATH .= ":${LAYERDIR}"
145
146 # We have recipes-* directories, add to BBFILES
147 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
148 ${LAYERDIR}/recipes-*/*/*.bbappend"
149
150 BBFILE_COLLECTIONS += "yoctobsp"
151 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
152 BBFILE_PRIORITY_yoctobsp = "5"
153 LAYERVERSION_yoctobsp = "2"
154 </literallayout></para>
155 <para>Here is an explanation of the example:
156 <itemizedlist>
157 <listitem><para>The configuration and
158 classes directory is appended to
159 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
160 <note>
161 All non-distro layers, which include all BSP
162 layers, are expected to append the layer
163 directory to the
164 <filename>BBPATH</filename>.
165 On the other hand, distro layers, such as
166 <filename>meta-yocto</filename>, can choose
167 to enforce their own precedence over
168 <filename>BBPATH</filename>.
169 For an example of that syntax, see the
170 <filename>layer.conf</filename> file for
171 the <filename>meta-yocto</filename> layer.
172 </note></para></listitem>
173 <listitem><para>The recipes for the layers are
174 appended to
175 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
176 </para></listitem>
177 <listitem><para>The
178 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
179 variable is then appended with the layer name.
180 </para></listitem>
181 <listitem><para>The
182 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
183 variable is set to a regular expression and is
184 used to match files from
185 <filename>BBFILES</filename> into a particular
186 layer.
187 In this case,
188 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
189 is used to make <filename>BBFILE_PATTERN</filename> match within the
190 layer's path.</para></listitem>
191 <listitem><para>The
192 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
193 variable then assigns a priority to the layer.
194 Applying priorities is useful in situations
195 where the same package might appear in multiple
196 layers and allows you to choose what layer
197 should take precedence.</para></listitem>
198 <listitem><para>The
199 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
200 variable optionally specifies the version of a
201 layer as a single number.</para></listitem>
202 </itemizedlist></para>
203 <para>Note the use of the
204 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
205 variable, which expands to the directory of the current
206 layer.</para>
207 <para>Through the use of the <filename>BBPATH</filename>
208 variable, BitBake locates <filename>.bbclass</filename>
209 files, configuration files, and files that are included
210 with <filename>include</filename> and
211 <filename>require</filename> statements.
212 For these cases, BitBake uses the first file that
213 matches the name found in <filename>BBPATH</filename>.
214 This is similar to the way the <filename>PATH</filename>
215 variable is used for binaries.
216 We recommend, therefore, that you use unique
217 <filename>.bbclass</filename> and configuration
218 filenames in your custom layer.</para></listitem>
219 <listitem><para><emphasis>Add Content:</emphasis> Depending
220 on the type of layer, add the content.
221 If the layer adds support for a machine, add the machine
222 configuration in a <filename>conf/machine/</filename>
223 file within the layer.
224 If the layer adds distro policy, add the distro
225 configuration in a <filename>conf/distro/</filename>
226 file with the layer.
227 If the layer introduces new recipes, put the recipes
228 you need in <filename>recipes-*</filename>
229 subdirectories within the layer.
230 <note>In order to be compliant with the Yocto Project,
231 a layer must contain a
232 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
233 </note></para></listitem>
234 </orderedlist>
235 </para>
236 </section>
237
238 <section id='best-practices-to-follow-when-creating-layers'>
239 <title>Best Practices to Follow When Creating Layers</title>
240
241 <para>
242 To create layers that are easier to maintain and that will
243 not impact builds for other machines, you should consider the
244 information in the following sections.
245 </para>
246
247 <section id='avoid-overlaying-entire-recipes'>
248 <title>Avoid "Overlaying" Entire Recipes</title>
249
250 <para>
251 Avoid "overlaying" entire recipes from other layers in your
252 configuration.
253 In other words, do not copy an entire recipe into your
254 layer and then modify it.
255 Use <filename>.bbappend</filename> files to override the
256 parts of the recipe you need to modify.
257 </para>
258 </section>
259
260 <section id='avoid-duplicating-include-files'>
261 <title>Avoid Duplicating Include Files</title>
262
263 <para>
264 Avoid duplicating include files.
265 Use <filename>.bbappend</filename> files for each recipe
266 that uses an include file.
267 Or, if you are introducing a new recipe that requires
268 the included file, use the path relative to the original
269 layer directory to refer to the file.
270 For example, use
271 <filename>require recipes-core/somepackage/somefile.inc</filename>
272 instead of <filename>require somefile.inc</filename>.
273 If you're finding you have to overlay the include file,
274 it could indicate a deficiency in the include file in
275 the layer to which it originally belongs.
276 If this is the case, you need to address that deficiency
277 instead of overlaying the include file.
278 For example, consider how support plug-ins for the Qt 4
279 database are configured.
280 The Source Directory does not have MySQL or PostgreSQL.
281 However, OpenEmbedded's layer <filename>meta-oe</filename>
282 does.
283 Consequently, <filename>meta-oe</filename> uses
284 <filename>.bbappend</filename> files to modify the
285 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
286 enable the appropriate plug-ins.
287 This variable was added to the <filename>qt4.inc</filename>
288 include file in the Source Directory specifically to allow
289 the <filename>meta-oe</filename> layer to be able to control
290 which plug-ins are built.
291 </para>
292 </section>
293
294 <section id='structure-your-layers'>
295 <title>Structure Your Layers</title>
296
297 <para>
298 Proper use of overrides within append files and placement
299 of machine-specific files within your layer can ensure that
300 a build is not using the wrong Metadata and negatively
301 impacting a build for a different machine.
302 Following are some examples:
303 <itemizedlist>
304 <listitem><para><emphasis>Modifying Variables to Support
305 a Different Machine:</emphasis>
306 Suppose you have a layer named
307 <filename>meta-one</filename> that adds support
308 for building machine "one".
309 To do so, you use an append file named
310 <filename>base-files.bbappend</filename> and
311 create a dependency on "foo" by altering the
312 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
313 variable:
314 <literallayout class='monospaced'>
315 DEPENDS = "foo"
316 </literallayout>
317 The dependency is created during any build that
318 includes the layer
319 <filename>meta-one</filename>.
320 However, you might not want this dependency
321 for all machines.
322 For example, suppose you are building for
323 machine "two" but your
324 <filename>bblayers.conf</filename> file has the
325 <filename>meta-one</filename> layer included.
326 During the build, the
327 <filename>base-files</filename> for machine
328 "two" will also have the dependency on
329 <filename>foo</filename>.</para>
330 <para>To make sure your changes apply only when
331 building machine "one", use a machine override
332 with the <filename>DEPENDS</filename> statement:
333 <literallayout class='monospaced'>
334 DEPENDS_one = "foo"
335 </literallayout>
336 You should follow the same strategy when using
337 <filename>_append</filename> and
338 <filename>_prepend</filename> operations:
339 <literallayout class='monospaced'>
340 DEPENDS_append_one = " foo"
341 DEPENDS_prepend_one = "foo "
342 </literallayout>
343 <note>
344 Avoiding "+=" and "=+" and using
345 machine-specific
346 <filename>_append</filename>
347 and <filename>_prepend</filename> operations
348 is recommended as well.
349 </note></para></listitem>
350 <listitem><para><emphasis>Place Machine-Specific Files
351 in Machine-Specific Locations:</emphasis>
352 When you have a base recipe, such as
353 <filename>base-files.bb</filename>, that
354 contains a
355 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
356 statement to a file, you can use an append file
357 to cause the build to use your own version of
358 the file.
359 For example, an append file in your layer at
360 <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
361 could extend
362 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
363 using
364 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
365 as follows:
366 <literallayout class='monospaced'>
367 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
368 </literallayout>
369 The build for machine "one" will pick up your
370 machine-specific file as long as you have the
371 file in
372 <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
373 However, if you are building for a different
374 machine and the
375 <filename>bblayers.conf</filename> file includes
376 the <filename>meta-one</filename> layer and
377 the location of your machine-specific file is
378 the first location where that file is found
379 according to <filename>FILESPATH</filename>,
380 builds for all machines will also use that
381 machine-specific file.</para>
382 <para>You can make sure that a machine-specific
383 file is used for a particular machine by putting
384 the file in a subdirectory specific to the
385 machine.
386 For example, rather than placing the file in
387 <filename>/meta-one/recipes-core/base-files/base-files/</filename>
388 as shown above, put it in
389 <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
390 Not only does this make sure the file is used
391 only when building for machine "one" but the
392 build process locates the file more quickly.</para>
393 <para>In summary, you need to place all files
394 referenced from <filename>SRC_URI</filename>
395 in a machine-specific subdirectory within the
396 layer in order to restrict those files to
397 machine-specific builds.</para></listitem>
398 </itemizedlist>
399 </para>
400 </section>
401
402 <section id='other-recommendations'>
403 <title>Other Recommendations</title>
404
405 <para>
406 We also recommend the following:
407 <itemizedlist>
408 <listitem><para>Store custom layers in a Git repository
409 that uses the
410 <filename>meta-&lt;layer_name&gt;</filename> format.
411 </para></listitem>
412 <listitem><para>Clone the repository alongside other
413 <filename>meta</filename> directories in the
414 <link linkend='source-directory'>Source Directory</link>.
415 </para></listitem>
416 </itemizedlist>
417 Following these recommendations keeps your Source Directory and
418 its configuration entirely inside the Yocto Project's core
419 base.
420 </para>
421 </section>
422 </section>
423
424 <section id='enabling-your-layer'>
425 <title>Enabling Your Layer</title>
426
427 <para>
428 Before the OpenEmbedded build system can use your new layer,
429 you need to enable it.
430 To enable your layer, simply add your layer's path to the
431 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
432 variable in your <filename>conf/bblayers.conf</filename> file,
433 which is found in the
434 <link linkend='build-directory'>Build Directory</link>.
435 The following example shows how to enable a layer named
436 <filename>meta-mylayer</filename>:
437 <literallayout class='monospaced'>
438 LCONF_VERSION = "6"
439
440 BBPATH = "${TOPDIR}"
441 BBFILES ?= ""
442
443 BBLAYERS ?= " \
444 $HOME/poky/meta \
445 $HOME/poky/meta-yocto \
446 $HOME/poky/meta-yocto-bsp \
447 $HOME/poky/meta-mylayer \
448 "
449
450 BBLAYERS_NON_REMOVABLE ?= " \
451 $HOME/poky/meta \
452 $HOME/poky/meta-yocto \
453 "
454 </literallayout>
455 </para>
456
457 <para>
458 BitBake parses each <filename>conf/layer.conf</filename> file
459 as specified in the <filename>BBLAYERS</filename> variable
460 within the <filename>conf/bblayers.conf</filename> file.
461 During the processing of each
462 <filename>conf/layer.conf</filename> file, BitBake adds the
463 recipes, classes and configurations contained within the
464 particular layer to the source directory.
465 </para>
466 </section>
467
468 <section id='using-bbappend-files'>
469 <title>Using .bbappend Files</title>
470
471 <para>
472 Recipes used to append Metadata to other recipes are called
473 BitBake append files.
474 BitBake append files use the <filename>.bbappend</filename> file
475 type suffix, while the corresponding recipes to which Metadata
476 is being appended use the <filename>.bb</filename> file type
477 suffix.
478 </para>
479
480 <para>
481 A <filename>.bbappend</filename> file allows your layer to make
482 additions or changes to the content of another layer's recipe
483 without having to copy the other recipe into your layer.
484 Your <filename>.bbappend</filename> file resides in your layer,
485 while the main <filename>.bb</filename> recipe file to
486 which you are appending Metadata resides in a different layer.
487 </para>
488
489 <para>
490 Append files must have the same root names as their corresponding
491 recipes.
492 For example, the append file
493 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
494 <filename>someapp_&DISTRO;.bb</filename>.
495 This means the original recipe and append file names are version
496 number-specific.
497 If the corresponding recipe is renamed to update to a newer
498 version, the corresponding <filename>.bbappend</filename> file must
499 be renamed as well.
500 During the build process, BitBake displays an error on starting
501 if it detects a <filename>.bbappend</filename> file that does
502 not have a corresponding recipe with a matching name.
503 See the
504 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
505 variable for information on how to handle this error.
506 </para>
507
508 <para>
509 Being able to append information to an existing recipe not only
510 avoids duplication, but also automatically applies recipe
511 changes in a different layer to your layer.
512 If you were copying recipes, you would have to manually merge
513 changes as they occur.
514 </para>
515
516 <para>
517 As an example, consider the main formfactor recipe and a
518 corresponding formfactor append file both from the
519 <link linkend='source-directory'>Source Directory</link>.
520 Here is the main formfactor recipe, which is named
521 <filename>formfactor_0.0.bb</filename> and located in the
522 "meta" layer at
523 <filename>meta/recipes-bsp/formfactor</filename>:
524 <literallayout class='monospaced'>
525 DESCRIPTION = "Device formfactor information"
526 SECTION = "base"
527 LICENSE = "MIT"
528 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
529 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
530 PR = "r41"
531
532 SRC_URI = "file://config file://machconfig"
533 S = "${WORKDIR}"
534
535 PACKAGE_ARCH = "${MACHINE_ARCH}"
536 INHIBIT_DEFAULT_DEPS = "1"
537
538 do_install() {
539 # Only install file if it has a contents
540 install -d ${D}${sysconfdir}/formfactor/
541 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
542 if [ -s "${S}/machconfig" ]; then
543 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
544 fi
545 }
546 </literallayout>
547 In the main recipe, note the
548 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
549 variable, which tells the OpenEmbedded build system where to
550 find files during the build.
551 </para>
552
553 <para>
554 Following is the append file, which is named
555 <filename>formfactor_0.0.bbappend</filename> and is from the
556 Crown Bay BSP Layer named
557 <filename>meta-intel/meta-crownbay</filename>.
558 The file is in <filename>recipes-bsp/formfactor</filename>:
559 <literallayout class='monospaced'>
560 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
561 </literallayout>
562 </para>
563
564 <para>
565 By default, the build system uses the
566 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
567 variable to locate files.
568 This append file extends the locations by setting the
569 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
570 variable.
571 Setting this variable in the <filename>.bbappend</filename>
572 file is the most reliable and recommended method for adding
573 directories to the search path used by the build system
574 to find files.
575 </para>
576
577 <para>
578 The statement in this example extends the directories to include
579 <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>,
580 which resolves to a directory named
581 <filename>formfactor</filename> in the same directory
582 in which the append file resides (i.e.
583 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
584 This implies that you must have the supporting directory
585 structure set up that will contain any files or patches you
586 will be including from the layer.
587 </para>
588
589 <para>
590 Using the immediate expansion assignment operator
591 <filename>:=</filename> is important because of the reference to
592 <filename>THISDIR</filename>.
593 The trailing colon character is important as it ensures that
594 items in the list remain colon-separated.
595 <note><para>BitBake automatically defines the
596 <filename>THISDIR</filename> variable.
597 You should never set this variable yourself.
598 Using <filename>_prepend</filename> ensures your path will
599 be searched prior to other paths in the final list.</para>
600 <para>Also, not all append files add extra files.
601 Many append files simply exist to add build options
602 (e.g. <filename>systemd</filename>).
603 For these cases, it is not necessary to use the
604 "_prepend" part of the statement.</para>
605 </note>
606 </para>
607 </section>
608
609 <section id='prioritizing-your-layer'>
610 <title>Prioritizing Your Layer</title>
611
612 <para>
613 Each layer is assigned a priority value.
614 Priority values control which layer takes precedence if there
615 are recipe files with the same name in multiple layers.
616 For these cases, the recipe file from the layer with a higher
617 priority number takes precedence.
618 Priority values also affect the order in which multiple
619 <filename>.bbappend</filename> files for the same recipe are
620 applied.
621 You can either specify the priority manually, or allow the
622 build system to calculate it based on the layer's dependencies.
623 </para>
624
625 <para>
626 To specify the layer's priority manually, use the
627 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
628 variable.
629 For example:
630 <literallayout class='monospaced'>
631 BBFILE_PRIORITY_mylayer = "1"
632 </literallayout>
633 </para>
634
635 <note>
636 <para>It is possible for a recipe with a lower version number
637 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
638 in a layer that has a higher priority to take precedence.</para>
639 <para>Also, the layer priority does not currently affect the
640 precedence order of <filename>.conf</filename>
641 or <filename>.bbclass</filename> files.
642 Future versions of BitBake might address this.</para>
643 </note>
644 </section>
645
646 <section id='managing-layers'>
647 <title>Managing Layers</title>
648
649 <para>
650 You can use the BitBake layer management tool to provide a view
651 into the structure of recipes across a multi-layer project.
652 Being able to generate output that reports on configured layers
653 with their paths and priorities and on
654 <filename>.bbappend</filename> files and their applicable
655 recipes can help to reveal potential problems.
656 </para>
657
658 <para>
659 Use the following form when running the layer management tool.
660 <literallayout class='monospaced'>
661 $ bitbake-layers &lt;command&gt; [arguments]
662 </literallayout>
663 The following list describes the available commands:
664 <itemizedlist>
665 <listitem><para><filename><emphasis>help:</emphasis></filename>
666 Displays general help or help on a specified command.
667 </para></listitem>
668 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
669 Shows the current configured layers.
670 </para></listitem>
671 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
672 Lists available recipes and the layers that provide them.
673 </para></listitem>
674 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
675 Lists overlayed recipes.
676 A recipe is overlayed when a recipe with the same name
677 exists in another layer that has a higher layer
678 priority.
679 </para></listitem>
680 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
681 Lists <filename>.bbappend</filename> files and the
682 recipe files to which they apply.
683 </para></listitem>
684 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
685 Lists dependency relationships between recipes that
686 cross layer boundaries.
687 </para></listitem>
688 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
689 Flattens the layer configuration into a separate output
690 directory.
691 Flattening your layer configuration builds a "flattened"
692 directory that contains the contents of all layers,
693 with any overlayed recipes removed and any
694 <filename>.bbappend</filename> files appended to the
695 corresponding recipes.
696 You might have to perform some manual cleanup of the
697 flattened layer as follows:
698 <itemizedlist>
699 <listitem><para>Non-recipe files (such as patches)
700 are overwritten.
701 The flatten command shows a warning for these
702 files.
703 </para></listitem>
704 <listitem><para>Anything beyond the normal layer
705 setup has been added to the
706 <filename>layer.conf</filename> file.
707 Only the lowest priority layer's
708 <filename>layer.conf</filename> is used.
709 </para></listitem>
710 <listitem><para>Overridden and appended items from
711 <filename>.bbappend</filename> files need to be
712 cleaned up.
713 The contents of each
714 <filename>.bbappend</filename> end up in the
715 flattened recipe.
716 However, if there are appended or changed
717 variable values, you need to tidy these up
718 yourself.
719 Consider the following example.
720 Here, the <filename>bitbake-layers</filename>
721 command adds the line
722 <filename>#### bbappended ...</filename> so that
723 you know where the following lines originate:
724 <literallayout class='monospaced'>
725 ...
726 DESCRIPTION = "A useful utility"
727 ...
728 EXTRA_OECONF = "--enable-something"
729 ...
730
731 #### bbappended from meta-anotherlayer ####
732
733 DESCRIPTION = "Customized utility"
734 EXTRA_OECONF += "--enable-somethingelse"
735 </literallayout>
736 Ideally, you would tidy up these utilities as
737 follows:
738 <literallayout class='monospaced'>
739 ...
740 DESCRIPTION = "Customized utility"
741 ...
742 EXTRA_OECONF = "--enable-something --enable-somethingelse"
743 ...
744 </literallayout></para></listitem>
745 </itemizedlist></para></listitem>
746 </itemizedlist>
747 </para>
748 </section>
749
750 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
751 <title>Creating a General Layer Using the yocto-layer Script</title>
752
753 <para>
754 The <filename>yocto-layer</filename> script simplifies
755 creating a new general layer.
756 <note>
757 For information on BSP layers, see the
758 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
759 section in the Yocto Project Board Specific (BSP)
760 Developer's Guide.
761 </note>
762 The default mode of the script's operation is to prompt you for
763 information needed to generate the layer:
764 <itemizedlist>
765 <listitem><para>The layer priority
766 </para></listitem>
767 <listitem><para>Whether or not to create a sample recipe.
768 </para></listitem>
769 <listitem><para>Whether or not to create a sample
770 append file.
771 </para></listitem>
772 </itemizedlist>
773 </para>
774
775 <para>
776 Use the <filename>yocto-layer create</filename> sub-command
777 to create a new general layer.
778 In its simplest form, you can create a layer as follows:
779 <literallayout class='monospaced'>
780 $ yocto-layer create mylayer
781 </literallayout>
782 The previous example creates a layer named
783 <filename>meta-mylayer</filename> in the current directory.
784 </para>
785
786 <para>
787 As the <filename>yocto-layer create</filename> command runs,
788 default values for the prompts appear in brackets.
789 Pressing enter without supplying anything for the prompts
790 or pressing enter and providing an invalid response causes the
791 script to accept the default value.
792 Once the script completes, the new layer
793 is created in the current working directory.
794 The script names the layer by prepending
795 <filename>meta-</filename> to the name you provide.
796 </para>
797
798 <para>
799 Minimally, the script creates the following within the layer:
800 <itemizedlist>
801 <listitem><para><emphasis>The <filename>conf</filename>
802 directory:</emphasis>
803 This directory contains the layer's configuration file.
804 The root name for the file is the same as the root name
805 your provided for the layer (e.g.
806 <filename>&lt;layer&gt;.conf</filename>).
807 </para></listitem>
808 <listitem><para><emphasis>The
809 <filename>COPYING.MIT</filename>:</emphasis>
810 The copyright and use notice for the software.
811 </para></listitem>
812 <listitem><para><emphasis>The <filename>README</filename>
813 file:</emphasis>
814 A file describing the contents of your new layer.
815 </para></listitem>
816 </itemizedlist>
817 </para>
818
819 <para>
820 If you choose to generate a sample recipe file, the script
821 prompts you for the name for the recipe and then creates it
822 in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
823 The script creates a <filename>.bb</filename> file and a
824 directory, which contains a sample
825 <filename>helloworld.c</filename> source file and along with
826 a sample patch file.
827 If you do not provide a recipe name, the script uses
828 "example".
829 </para>
830
831 <para>
832 If you choose to generate a sample append file, the script
833 prompts you for the name for the file and then creates it
834 in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
835 The script creates a <filename>.bbappend</filename> file and a
836 directory, which contains a sample patch file.
837 If you do not provide a recipe name, the script uses
838 "example".
839 The script also prompts you for the version of the append file.
840 The version should match the recipe to which the append file
841 is associated.
842 </para>
843
844 <para>
845 The easiest way to see how the <filename>yocto-layer</filename>
846 script works is to experiment with the script.
847 You can also read the usage information by entering the
848 following:
849 <literallayout class='monospaced'>
850 $ yocto-layer help
851 </literallayout>
852 </para>
853
854 <para>
855 Once you create your general layer, you must add it to your
856 <filename>bblayers.conf</filename> file.
857 Here is an example where a layer named
858 <filename>meta-mylayer</filename> is added:
859 <literallayout class='monospaced'>
860 BBLAYERS = ?" \
861 /usr/local/src/yocto/meta \
862 /usr/local/src/yocto/meta-yocto \
863 /usr/local/src/yocto/meta-yocto-bsp \
864 /usr/local/src/yocto/meta-mylayer \
865 "
866
867 BBLAYERS_NON_REMOVABLE ?= " \
868 /usr/local/src/yocto/meta \
869 /usr/local/src/yocto/meta-yocto \
870 "
871 </literallayout>
872 Adding the layer to this file enables the build system to
873 locate the layer during the build.
874 </para>
875 </section>
876 </section>
877
878 <section id='usingpoky-extend-customimage'>
879 <title>Customizing Images</title>
880
881 <para>
882 You can customize images to satisfy particular requirements.
883 This section describes several methods and provides guidelines for each.
884 </para>
885
886 <section id='usingpoky-extend-customimage-custombb'>
887 <title>Customizing Images Using Custom .bb Files</title>
888
889 <para>
890 One way to get additional software into an image is to create a custom image.
891 The following example shows the form for the two lines you need:
892 <literallayout class='monospaced'>
893 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
894
895 inherit core-image
896 </literallayout>
897 </para>
898
899 <para>
900 By creating a custom image, a developer has total control
901 over the contents of the image.
902 It is important to use the correct names of packages in the
903 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
904 variable.
905 You must use the OpenEmbedded notation and not the Debian notation for the names
906 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
907 </para>
908
909 <para>
910 The other method for creating a custom image is to base it on an existing image.
911 For example, if you want to create an image based on <filename>core-image-sato</filename>
912 but add the additional package <filename>strace</filename> to the image,
913 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
914 new <filename>.bb</filename> and add the following line to the end of the copy:
915 <literallayout class='monospaced'>
916 IMAGE_INSTALL += "strace"
917 </literallayout>
918 </para>
919 </section>
920
921 <section id='usingpoky-extend-customimage-customtasks'>
922 <title>Customizing Images Using Custom Package Groups</title>
923
924 <para>
925 For complex custom images, the best approach is to create a
926 custom package group recipe that is used to build the image or
927 images.
928 A good example of a package group recipe is
929 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
930 The
931 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
932 variable lists the package group packages you wish to produce.
933 <filename>inherit packagegroup</filename> sets appropriate
934 default values and automatically adds <filename>-dev</filename>,
935 <filename>-dbg</filename>, and <filename>-ptest</filename>
936 complementary packages for every package specified in
937 <filename>PACKAGES</filename>.
938 Note that the inherit line should be towards
939 the top of the recipe, certainly before you set
940 <filename>PACKAGES</filename>.
941 For each package you specify in <filename>PACKAGES</filename>,
942 you can use
943 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
944 and
945 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
946 entries to provide a list of packages the parent task package
947 should contain.
948 Following is an example:
949 <literallayout class='monospaced'>
950 DESCRIPTION = "My Custom Package Groups"
951
952 inherit packagegroup
953
954 PACKAGES = "\
955 packagegroup-custom-apps \
956 packagegroup-custom-tools \
957 "
958
959 RDEPENDS_packagegroup-custom-apps = "\
960 dropbear \
961 portmap \
962 psplash"
963
964 RDEPENDS_packagegroup-custom-tools = "\
965 oprofile \
966 oprofileui-server \
967 lttng-control \
968 lttng-viewer"
969
970 RRECOMMENDS_packagegroup-custom-tools = "\
971 kernel-module-oprofile"
972 </literallayout>
973 </para>
974
975 <para>
976 In the previous example, two package group packages are created with their dependencies and their
977 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
978 <filename>packagegroup-custom-tools</filename>.
979 To build an image using these package group packages, you need to add
980 <filename>packagegroup-custom-apps</filename> and/or
981 <filename>packagegroup-custom-tools</filename> to
982 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
983 For other forms of image dependencies see the other areas of this section.
984 </para>
985 </section>
986
987 <section id='usingpoky-extend-customimage-imagefeatures'>
988 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
989 <filename>EXTRA_IMAGE_FEATURES</filename></title>
990
991 <para>
992 You might want to customize your image by enabling or
993 disabling high-level image features by using the
994 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
995 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
996 variables.
997 Although the functions for both variables are nearly equivalent,
998 best practices dictate using <filename>IMAGE_FEATURES</filename>
999 from within a recipe and using
1000 <filename>EXTRA_IMAGE_FEATURES</filename> from within
1001 your <filename>local.conf</filename> file, which is found in the
1002 <link linkend='build-directory'>Build Directory</link>.
1003 </para>
1004
1005 <para>
1006 To understand how these features work, the best reference is
1007 <filename>meta/classes/core-image.bbclass</filename>.
1008 In summary, the file looks at the contents of the
1009 <filename>IMAGE_FEATURES</filename> variable and then maps
1010 those contents into a set of package groups.
1011 Based on this information, the build system automatically
1012 adds the appropriate packages to the
1013 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
1014 variable.
1015 Effectively, you are enabling extra features by extending the
1016 class or creating a custom class for use with specialized image
1017 <filename>.bb</filename> files.
1018 </para>
1019
1020 <para>
1021 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1022 from within your local configuration file.
1023 Using a separate area from which to enable features with
1024 this variable helps you avoid overwriting the features in the
1025 image recipe that are enabled with
1026 <filename>IMAGE_FEATURES</filename>.
1027 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1028 to <filename>IMAGE_FEATURES</filename> within
1029 <filename>meta/conf/bitbake.conf</filename>.
1030 </para>
1031
1032 <para>
1033 To illustrate how you can use these variables to modify your
1034 image, consider an example that selects the SSH server.
1035 The Yocto Project ships with two SSH servers you can use
1036 with your images: Dropbear and OpenSSH.
1037 Dropbear is a minimal SSH server appropriate for
1038 resource-constrained environments, while OpenSSH is a
1039 well-known standard SSH server implementation.
1040 By default, the <filename>core-image-sato</filename> image
1041 is configured to use Dropbear.
1042 The <filename>core-image-basic</filename> and
1043 <filename>core-image-lsb</filename> images both
1044 include OpenSSH.
1045 The <filename>core-image-minimal</filename> image does not
1046 contain an SSH server.
1047 </para>
1048
1049 <para>
1050 You can customize your image and change these defaults.
1051 Edit the <filename>IMAGE_FEATURES</filename> variable
1052 in your recipe or use the
1053 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1054 <filename>local.conf</filename> file so that it configures the
1055 image you are working with to include
1056 <filename>ssh-server-dropbear</filename> or
1057 <filename>ssh-server-openssh</filename>.
1058 </para>
1059
1060 <note>
1061 See the
1062 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1063 section in the Yocto Project Reference Manual for a complete
1064 list of image features that ship with the Yocto Project.
1065 </note>
1066 </section>
1067
1068 <section id='usingpoky-extend-customimage-localconf'>
1069 <title>Customizing Images Using <filename>local.conf</filename></title>
1070
1071 <para>
1072 It is possible to customize image contents by using variables from your
1073 local configuration in your <filename>conf/local.conf</filename> file.
1074 Because it is limited to local use, this method generally only allows you to
1075 add packages and is not as flexible as creating your own customized image.
1076 When you add packages using local variables this way, you need to realize that
1077 these variable changes affect all images at the same time and might not be
1078 what you require.
1079 </para>
1080
1081 <para>
1082 The simplest way to add extra packages to all images is by using the
1083 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1084 variable with the <filename>_append</filename> operator:
1085 <literallayout class='monospaced'>
1086 IMAGE_INSTALL_append = " strace"
1087 </literallayout>
1088 Use of the syntax is important - specifically, the space between
1089 the quote and the package name, which is
1090 <filename>strace</filename> in this example.
1091 This space is required since the <filename>_append</filename>
1092 operator does not add the space.
1093 </para>
1094
1095 <para>
1096 Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename>
1097 operator if you want to avoid ordering issues.
1098 The reason for this is because doing so unconditionally appends to the variable and
1099 avoids ordering problems due to the variable being set in image recipes and
1100 <filename>.bbclass</filename> files with operators like <filename>?=</filename>.
1101 Using <filename>_append</filename> ensures the operation takes affect.
1102 </para>
1103
1104 <para>
1105 As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
1106 all images.
1107 It is possible to extend the syntax so that the variable applies to a specific image only.
1108 Here is an example:
1109 <literallayout class='monospaced'>
1110 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
1111 </literallayout>
1112 This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
1113 only.
1114 </para>
1115
1116 <para>
1117 You can add packages using a similar approach through the
1118 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
1119 variable.
1120 If you use this variable, only <filename>core-image-*</filename> images are affected.
1121 </para>
1122 </section>
1123 </section>
1124
1125 <section id='usingpoky-extend-addpkg'>
1126 <title>Writing a Recipe to Add a Package to Your Image</title>
1127
1128 <para>
1129 Recipes add packages to your image.
1130 Writing a recipe means creating a <filename>.bb</filename> file that sets some
1131 variables.
1132 For information on variables that are useful for recipes and for information about recipe naming
1133 issues, see the
1134 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1135 section of the Yocto Project Reference Manual.
1136 </para>
1137
1138 <para>
1139 Before writing a recipe from scratch, it is often useful to check
1140 whether someone else has written one already.
1141 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
1142 Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
1143 you find there should work for you.
1144 </para>
1145
1146 <para>
1147 For new packages, the simplest way to add a recipe is to base it on a similar
1148 pre-existing recipe.
1149 The sections that follow provide some examples that show how to add standard
1150 types of packages.
1151 </para>
1152
1153 <note>
1154 <para>When writing shell functions, you need to be aware of BitBake's
1155 curly brace parsing.
1156 If a recipe uses a closing curly brace within the function and
1157 the character has no leading spaces, BitBake produces a parsing
1158 error.
1159 If you use a pair of curly brace in a shell function, the
1160 closing curly brace must not be located at the start of the line
1161 without leading spaces.</para>
1162 <para>Here is an example that causes BitBake to produce a parsing
1163 error:
1164 <literallayout class='monospaced'>
1165 fakeroot create_shar() {
1166 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1167 usage()
1168 {
1169 echo "test"
1170 ###### The following "}" at the start of the line causes a parsing error ######
1171 }
1172 EOF
1173 }
1174 </literallayout>
1175 Writing the recipe this way avoids the error:
1176 <literallayout class='monospaced'>
1177 fakeroot create_shar() {
1178 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1179 usage()
1180 {
1181 echo "test"
1182 ######The following "}" with a leading space at the start of the line avoids the error ######
1183 }
1184 EOF
1185 }
1186 </literallayout></para>
1187 </note>
1188
1189 <section id='usingpoky-extend-addpkg-singlec'>
1190 <title>Single .c File Package (Hello World!)</title>
1191
1192 <para>
1193 Building an application from a single file that is stored locally (e.g. under
1194 <filename>files/</filename>) requires a recipe that has the file listed in
1195 the
1196 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1197 variable.
1198 Additionally, you need to manually write the <filename>do_compile</filename> and
1199 <filename>do_install</filename> tasks.
1200 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
1201 variable defines the
1202 directory containing the source code, which is set to
1203 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'>
1204 WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build.
1205 <literallayout class='monospaced'>
1206 DESCRIPTION = "Simple helloworld application"
1207 SECTION = "examples"
1208 LICENSE = "MIT"
1209 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
1210 PR = "r0"
1211
1212 SRC_URI = "file://helloworld.c"
1213
1214 S = "${WORKDIR}"
1215
1216 do_compile() {
1217 ${CC} helloworld.c -o helloworld
1218 }
1219
1220 do_install() {
1221 install -d ${D}${bindir}
1222 install -m 0755 helloworld ${D}${bindir}
1223 }
1224 </literallayout>
1225 </para>
1226
1227 <para>
1228 By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
1229 and <filename>helloworld-dev</filename> packages are built.
1230 For information on how to customize the packaging process, see the
1231 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application
1232 into Multiple Packages</link>" section.
1233 </para>
1234 </section>
1235
1236 <section id='usingpoky-extend-addpkg-autotools'>
1237 <title>Autotooled Package</title>
1238 <para>
1239 Applications that use Autotools such as <filename>autoconf</filename> and
1240 <filename>automake</filename> require a recipe that has a source archive listed in
1241 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
1242 also inherits Autotools, which instructs BitBake to use the
1243 <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
1244 needed to build an Autotool-based application.
1245 The result of the build is automatically packaged.
1246 And, if the application uses NLS for localization, packages with local information are
1247 generated (one package per language).
1248 Following is one example: (<filename>hello_2.3.bb</filename>)
1249 <literallayout class='monospaced'>
1250 DESCRIPTION = "GNU Helloworld application"
1251 SECTION = "examples"
1252 LICENSE = "GPLv2+"
1253 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
1254 PR = "r0"
1255
1256 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
1257
1258 inherit autotools gettext
1259 </literallayout>
1260 </para>
1261
1262 <para>
1263 The variable
1264 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
1265 is used to track source license changes as described in the
1266 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
1267 You can quickly create Autotool-based recipes in a manner similar to the previous example.
1268 </para>
1269 </section>
1270
1271 <section id='usingpoky-extend-addpkg-makefile'>
1272 <title>Makefile-Based Package</title>
1273
1274 <para>
1275 Applications that use GNU <filename>make</filename> also require a recipe that has
1276 the source archive listed in
1277 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
1278 You do not need to add a <filename>do_compile</filename> step since by default BitBake
1279 starts the <filename>make</filename> command to compile the application.
1280 If you need additional <filename>make</filename> options, you should store them in the
1281 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
1282 variable.
1283 BitBake passes these options into the <filename>make</filename> GNU invocation.
1284 Note that a <filename>do_install</filename> task is still required.
1285 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
1286 </para>
1287
1288 <para>
1289 Some applications might require extra parameters to be passed to the compiler.
1290 For example, the application might need an additional header path.
1291 You can accomplish this by adding to the
1292 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
1293 The following example shows this:
1294 <literallayout class='monospaced'>
1295 CFLAGS_prepend = "-I ${S}/include "
1296 </literallayout>
1297 </para>
1298
1299 <para>
1300 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
1301 <literallayout class='monospaced'>
1302 DESCRIPTION = "Tools for managing memory technology devices."
1303 SECTION = "base"
1304 DEPENDS = "zlib lzo e2fsprogs util-linux"
1305 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
1306 LICENSE = "GPLv2+"
1307 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
1308 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
1309
1310 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
1311 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
1312
1313 S = "${WORKDIR}/git/"
1314
1315 PR = "r1"
1316
1317 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
1318 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
1319
1320 do_install () {
1321 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
1322 INCLUDEDIR=${includedir}
1323 install -d ${D}${includedir}/mtd/
1324 for f in ${S}/include/mtd/*.h; do
1325 install -m 0644 $f ${D}${includedir}/mtd/
1326 done
1327 }
1328
1329 PARALLEL_MAKE = ""
1330
1331 BBCLASSEXTEND = "native"
1332 </literallayout>
1333 </para>
1334
1335 <para>
1336 If your sources are available as a tarball instead of a Git repository, you
1337 will need to provide the URL to the tarball as well as an
1338 <filename>md5</filename> or <filename>sha256</filename> sum of
1339 the download.
1340 Here is an example:
1341 <literallayout class='monospaced'>
1342 SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
1343 SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
1344 </literallayout>
1345 You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
1346 by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
1347 with the target file as the only argument.
1348 Here is an example:
1349 <literallayout class='monospaced'>
1350 $ md5sum mtd-utils-1.4.9.tar.bz2
1351 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
1352 </literallayout>
1353 </para>
1354 </section>
1355
1356 <section id='splitting-an-application-into-multiple-packages'>
1357 <title>Splitting an Application into Multiple Packages</title>
1358
1359 <para>
1360 You can use the variables
1361 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
1362 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
1363 to split an application into multiple packages.
1364 </para>
1365
1366 <para>
1367 Following is an example that uses the <filename>libXpm</filename> recipe.
1368 By default, this recipe generates a single package that contains the library along
1369 with a few binaries.
1370 You can modify the recipe to split the binaries into separate packages:
1371 <literallayout class='monospaced'>
1372 require xorg-lib-common.inc
1373
1374 DESCRIPTION = "X11 Pixmap library"
1375 LICENSE = "X-BSD"
1376 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
1377 DEPENDS += "libxext libsm libxt"
1378 PR = "r3"
1379 PE = "1"
1380
1381 XORG_PN = "libXpm"
1382
1383 PACKAGES =+ "sxpm cxpm"
1384 FILES_cxpm = "${bindir}/cxpm"
1385 FILES_sxpm = "${bindir}/sxpm"
1386 </literallayout>
1387 </para>
1388
1389 <para>
1390 In the previous example, we want to ship the <filename>sxpm</filename>
1391 and <filename>cxpm</filename> binaries in separate packages.
1392 Since <filename>bindir</filename> would be packaged into the main
1393 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
1394 package by default, we prepend the <filename>PACKAGES</filename>
1395 variable so additional package names are added to the start of list.
1396 This results in the extra <filename>FILES_*</filename>
1397 variables then containing information that define which files and
1398 directories go into which packages.
1399 Files included by earlier packages are skipped by latter packages.
1400 Thus, the main <filename>PN</filename> package
1401 does not include the above listed files.
1402 </para>
1403 </section>
1404
1405 <section id='usingpoky-extend-addpkg-postinstalls'>
1406 <title>Post-Installation Scripts</title>
1407
1408 <para>
1409 To add a post-installation script to a package, add a
1410 <filename>pkg_postinst_PACKAGENAME()</filename> function to the
1411 <filename>.bb</filename> file and use
1412 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
1413 <filename>postinst</filename> script.
1414 Normally,
1415 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
1416 can be used, which automatically expands to <filename>PACKAGENAME</filename>.
1417 A post-installation function has the following structure:
1418 <literallayout class='monospaced'>
1419 pkg_postinst_PACKAGENAME () {
1420 #!/bin/sh -e
1421 # Commands to carry out
1422 }
1423 </literallayout>
1424 </para>
1425
1426 <para>
1427 The script defined in the post-installation function is called when the
1428 root filesystem is created.
1429 If the script succeeds, the package is marked as installed.
1430 If the script fails, the package is marked as unpacked and the script is
1431 executed when the image boots again.
1432 </para>
1433
1434 <para>
1435 Sometimes it is necessary for the execution of a post-installation
1436 script to be delayed until the first boot.
1437 For example, the script might need to be executed on the device itself.
1438 To delay script execution until boot time, use the following structure in the
1439 post-installation script:
1440 <literallayout class='monospaced'>
1441 pkg_postinst_PACKAGENAME () {
1442 #!/bin/sh -e
1443 if [ x"$D" = "x" ]; then
1444 # Actions to carry out on the device go here
1445 else
1446 exit 1
1447 fi
1448 }
1449 </literallayout>
1450 </para>
1451
1452 <para>
1453 The previous example delays execution until the image boots again because the
1454 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
1455 variable points
1456 to the directory containing the image when the root filesystem is created at build time but
1457 is unset when executed on the first boot.
1458 </para>
1459 </section>
1460 </section>
1461
1462 <section id="platdev-newmachine">
1463 <title>Adding a New Machine</title>
1464
1465 <para>
1466 Adding a new machine to the Yocto Project is a straightforward process.
1467 This section provides information that gives you an idea of the changes you must make.
1468 The information covers adding machines similar to those the Yocto Project already supports.
1469 Although well within the capabilities of the Yocto Project, adding a totally new architecture
1470 might require
1471 changes to <filename>gcc/eglibc</filename> and to the site information, which is
1472 beyond the scope of this manual.
1473 </para>
1474
1475 <para>
1476 For a complete example that shows how to add a new machine,
1477 see the
1478 "<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>"
1479 in the Yocto Project Board Support Package (BSP) Developer's Guide.
1480 </para>
1481
1482 <section id="platdev-newmachine-conffile">
1483 <title>Adding the Machine Configuration File</title>
1484
1485 <para>
1486 To add a machine configuration, you need to add a <filename>.conf</filename> file
1487 with details of the device being added to the <filename>conf/machine/</filename> file.
1488 The name of the file determines the name the OpenEmbedded build system
1489 uses to reference the new machine.
1490 </para>
1491
1492 <para>
1493 The most important variables to set in this file are as follows:
1494 <itemizedlist>
1495 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
1496 (e.g. "arm")</para></listitem>
1497 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
1498 (see below)</para></listitem>
1499 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
1500 (e.g. "apm screen wifi")</para></listitem>
1501 </itemizedlist>
1502 </para>
1503
1504 <para>
1505 You might also need these variables:
1506 <itemizedlist>
1507 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
1508 (e.g. "115200 ttyS0")</para></listitem>
1509 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
1510 (e.g. "zImage")</para></listitem>
1511 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
1512 (e.g. "tar.gz jffs2")</para></listitem>
1513 </itemizedlist>
1514 </para>
1515
1516 <para>
1517 You can find full details on these variables in the reference section.
1518 You can leverage many existing machine <filename>.conf</filename> files from
1519 <filename>meta/conf/machine/</filename>.
1520 </para>
1521 </section>
1522
1523 <section id="platdev-newmachine-kernel">
1524 <title>Adding a Kernel for the Machine</title>
1525
1526 <para>
1527 The OpenEmbedded build system needs to be able to build a kernel for the machine.
1528 You need to either create a new kernel recipe for this machine, or extend an
1529 existing recipe.
1530 You can find several kernel examples in the
1531 Source Directory at <filename>meta/recipes-kernel/linux</filename>
1532 that you can use as references.
1533 </para>
1534
1535 <para>
1536 If you are creating a new recipe, normal recipe-writing rules apply for setting
1537 up a
1538 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
1539 Thus, you need to specify any necessary patches and set
1540 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> to point at the source code.
1541 You need to create a <filename>configure</filename> task that configures the
1542 unpacked kernel with a defconfig.
1543 You can do this by using a <filename>make defconfig</filename> command or,
1544 more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running
1545 <filename>make oldconfig</filename>.
1546 By making use of <filename>inherit kernel</filename> and potentially some of the
1547 <filename>linux-*.inc</filename> files, most other functionality is
1548 centralized and the the defaults of the class normally work well.
1549 </para>
1550
1551 <para>
1552 If you are extending an existing kernel, it is usually a matter of adding a
1553 suitable defconfig file.
1554 The file needs to be added into a location similar to defconfig files
1555 used for other machines in a given kernel.
1556 A possible way to do this is by listing the file in the
1557 <filename>SRC_URI</filename> and adding the machine to the expression in
1558 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
1559 <literallayout class='monospaced'>
1560 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
1561 </literallayout>
1562 </para>
1563 </section>
1564
1565 <section id="platdev-newmachine-formfactor">
1566 <title>Adding a Formfactor Configuration File</title>
1567
1568 <para>
1569 A formfactor configuration file provides information about the
1570 target hardware for which the image is being built and information that
1571 the build system cannot obtain from other sources such as the kernel.
1572 Some examples of information contained in a formfactor configuration file include
1573 framebuffer orientation, whether or not the system has a keyboard,
1574 the positioning of the keyboard in relation to the screen, and
1575 the screen resolution.
1576 </para>
1577
1578 <para>
1579 The build system uses reasonable defaults in most cases.
1580 However, if customization is
1581 necessary, you need to create a <filename>machconfig</filename> file
1582 in the <filename>meta/recipes-bsp/formfactor/files</filename>
1583 directory.
1584 This directory contains directories for specific machines such as
1585 <filename>qemuarm</filename> and <filename>qemux86</filename>.
1586 For information about the settings available and the defaults, see the
1587 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
1588 same area.
1589 </para>
1590
1591 <para>
1592 Following is an example for qemuarm:
1593 <literallayout class='monospaced'>
1594 HAVE_TOUCHSCREEN=1
1595 HAVE_KEYBOARD=1
1596
1597 DISPLAY_CAN_ROTATE=0
1598 DISPLAY_ORIENTATION=0
1599 #DISPLAY_WIDTH_PIXELS=640
1600 #DISPLAY_HEIGHT_PIXELS=480
1601 #DISPLAY_BPP=16
1602 DISPLAY_DPI=150
1603 DISPLAY_SUBPIXEL_ORDER=vrgb
1604 </literallayout>
1605 </para>
1606 </section>
1607 </section>
1608
1609 <section id="platdev-working-with-libraries">
1610 <title>Working With Libraries</title>
1611
1612 <para>
1613 Libraries are an integral part of your system.
1614 This section describes some common practices you might find
1615 helpful when working with libraries to build your system:
1616 <itemizedlist>
1617 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
1618 </para></listitem>
1619 <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>
1620 </para></listitem>
1621 <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>
1622 </para></listitem>
1623 </itemizedlist>
1624 </para>
1625
1626 <section id='including-static-library-files'>
1627 <title>Including Static Library Files</title>
1628
1629 <para>
1630 If you are building a library and the library offers static linking, you can control
1631 which static library files (<filename>*.a</filename> files) get included in the
1632 built library.
1633 </para>
1634
1635 <para>
1636 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1637 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
1638 variables in the
1639 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
1640 by the <filename>do_install</filename> task are packaged.
1641 By default, the <filename>PACKAGES</filename> variable contains
1642 <filename>${PN}-staticdev</filename>, which includes all static library files.
1643 <note>
1644 Some previously released versions of the Yocto Project
1645 defined the static library files through
1646 <filename>${PN}-dev</filename>.
1647 </note>
1648 Following, is part of the BitBake configuration file.
1649 You can see where the static library files are defined:
1650 <literallayout class='monospaced'>
1651 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
1652 PACKAGES_DYNAMIC = "${PN}-locale-*"
1653 FILES = ""
1654
1655 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
1656 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
1657 ${base_bindir}/* ${base_sbindir}/* \
1658 ${base_libdir}/*${SOLIBS} \
1659 ${datadir}/${BPN} ${libdir}/${BPN}/* \
1660 ${datadir}/pixmaps ${datadir}/applications \
1661 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
1662 ${libdir}/bonobo/servers"
1663
1664 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
1665 ${datadir}/gnome/help"
1666 SECTION_${PN}-doc = "doc"
1667
1668 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
1669 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
1670 ${datadir}/aclocal ${base_libdir}/*.o"
1671 SECTION_${PN}-dev = "devel"
1672 ALLOW_EMPTY_${PN}-dev = "1"
1673 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
1674
1675 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
1676 SECTION_${PN}-staticdev = "devel"
1677 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
1678 </literallayout>
1679 </para>
1680 </section>
1681
1682 <section id="combining-multiple-versions-library-files-into-one-image">
1683 <title>Combining Multiple Versions of Library Files into One Image</title>
1684
1685 <para>
1686 The build system offers the ability to build libraries with different
1687 target optimizations or architecture formats and combine these together
1688 into one system image.
1689 You can link different binaries in the image
1690 against the different libraries as needed for specific use cases.
1691 This feature is called "Multilib."
1692 </para>
1693
1694 <para>
1695 An example would be where you have most of a system compiled in 32-bit
1696 mode using 32-bit libraries, but you have something large, like a database
1697 engine, that needs to be a 64-bit application and uses 64-bit libraries.
1698 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
1699 </para>
1700
1701 <para>
1702 While the Multilib feature is most commonly used for 32 and 64-bit differences,
1703 the approach the build system uses facilitates different target optimizations.
1704 You could compile some binaries to use one set of libraries and other binaries
1705 to use other different sets of libraries.
1706 The libraries could differ in architecture, compiler options, or other
1707 optimizations.
1708 </para>
1709
1710 <para>
1711 This section overviews the Multilib process only.
1712 For more details on how to implement Multilib, see the
1713 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
1714 page.
1715 </para>
1716
1717 <para>
1718 Aside from this wiki page, several examples exist in the
1719 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/tree/meta-skeleton'><filename>meta-skeleton</filename></ulink>
1720 layer found in the
1721 <link linkend='source-directory'>Source Directory</link>:
1722 <itemizedlist>
1723 <listitem><para><filename>conf/multilib-example.conf</filename>
1724 configuration file</para></listitem>
1725 <listitem><para><filename>conf/multilib-example2.conf</filename>
1726 configuration file</para></listitem>
1727 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
1728 recipe</para></listitem>
1729 </itemizedlist>
1730 </para>
1731
1732 <section id='preparing-to-use-multilib'>
1733 <title>Preparing to Use Multilib</title>
1734
1735 <para>
1736 User-specific requirements drive the Multilib feature.
1737 Consequently, there is no one "out-of-the-box" configuration that likely
1738 exists to meet your needs.
1739 </para>
1740
1741 <para>
1742 In order to enable Multilib, you first need to ensure your recipe is
1743 extended to support multiple libraries.
1744 Many standard recipes are already extended and support multiple libraries.
1745 You can check in the <filename>meta/conf/multilib.conf</filename>
1746 configuration file in the
1747 <link linkend='source-directory'>Source Directory</link> to see how this is
1748 done using the
1749 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
1750 variable.
1751 Eventually, all recipes will be covered and this list will be unneeded.
1752 </para>
1753
1754 <para>
1755 For the most part, the Multilib class extension works automatically to
1756 extend the package name from <filename>${PN}</filename> to
1757 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
1758 is the particular multilib (e.g. "lib32-" or "lib64-").
1759 Standard variables such as
1760 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
1761 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
1762 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
1763 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
1764 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
1765 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
1766 If you are extending any manual code in the recipe, you can use the
1767 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
1768 correctly.
1769 This automatic extension code resides in <filename>multilib.bbclass</filename>.
1770 </para>
1771 </section>
1772
1773 <section id='using-multilib'>
1774 <title>Using Multilib</title>
1775
1776 <para>
1777 After you have set up the recipes, you need to define the actual
1778 combination of multiple libraries you want to build.
1779 You accomplish this through your <filename>local.conf</filename>
1780 configuration file in the
1781 <link linkend='build-directory'>Build Directory</link>.
1782 An example configuration would be as follows:
1783 <literallayout class='monospaced'>
1784 MACHINE = "qemux86-64"
1785 require conf/multilib.conf
1786 MULTILIBS = "multilib:lib32"
1787 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
1788 IMAGE_INSTALL = "lib32-connman"
1789 </literallayout>
1790 This example enables an
1791 additional library named <filename>lib32</filename> alongside the
1792 normal target packages.
1793 When combining these "lib32" alternatives, the example uses "x86" for tuning.
1794 For information on this particular tuning, see
1795 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
1796 </para>
1797
1798 <para>
1799 The example then includes <filename>lib32-connman</filename>
1800 in all the images, which illustrates one method of including a
1801 multiple library dependency.
1802 You can use a normal image build to include this dependency,
1803 for example:
1804 <literallayout class='monospaced'>
1805 $ bitbake core-image-sato
1806 </literallayout>
1807 You can also build Multilib packages specifically with a command like this:
1808 <literallayout class='monospaced'>
1809 $ bitbake lib32-connman
1810 </literallayout>
1811 </para>
1812 </section>
1813
1814 <section id='additional-implementation-details'>
1815 <title>Additional Implementation Details</title>
1816
1817 <para>
1818 Different packaging systems have different levels of native Multilib
1819 support.
1820 For the RPM Package Management System, the following implementation details
1821 exist:
1822 <itemizedlist>
1823 <listitem><para>A unique architecture is defined for the Multilib packages,
1824 along with creating a unique deploy folder under
1825 <filename>tmp/deploy/rpm</filename> in the
1826 <link linkend='build-directory'>Build Directory</link>.
1827 For example, consider <filename>lib32</filename> in a
1828 <filename>qemux86-64</filename> image.
1829 The possible architectures in the system are "all", "qemux86_64",
1830 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
1831 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
1832 <filename>${PN}</filename> during RPM packaging.
1833 The naming for a normal RPM package and a Multilib RPM package in a
1834 <filename>qemux86-64</filename> system resolves to something similar to
1835 <filename>bash-4.1-r2.x86_64.rpm</filename> and
1836 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
1837 </para></listitem>
1838 <listitem><para>When installing a Multilib image, the RPM backend first
1839 installs the base image and then installs the Multilib libraries.
1840 </para></listitem>
1841 <listitem><para>The build system relies on RPM to resolve the identical files in the
1842 two (or more) Multilib packages.</para></listitem>
1843 </itemizedlist>
1844 </para>
1845
1846 <para>
1847 For the IPK Package Management System, the following implementation details exist:
1848 <itemizedlist>
1849 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
1850 <filename>${PN}</filename> during IPK packaging.
1851 The naming for a normal RPM package and a Multilib IPK package in a
1852 <filename>qemux86-64</filename> system resolves to something like
1853 <filename>bash_4.1-r2.x86_64.ipk</filename> and
1854 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
1855 </para></listitem>
1856 <listitem><para>The IPK deploy folder is not modified with
1857 <filename>${MLPREFIX}</filename> because packages with and without
1858 the Multilib feature can exist in the same folder due to the
1859 <filename>${PN}</filename> differences.</para></listitem>
1860 <listitem><para>IPK defines a sanity check for Multilib installation
1861 using certain rules for file comparison, overridden, etc.
1862 </para></listitem>
1863 </itemizedlist>
1864 </para>
1865 </section>
1866 </section>
1867
1868 <section id='installing-multiple-versions-of-the-same-library'>
1869 <title>Installing Multiple Versions of the Same Library</title>
1870
1871 <para>
1872 Situations can exist where you need to install and use
1873 multiple versions of the same library on the same system
1874 at the same time.
1875 These situations almost always exist when a library API
1876 changes and you have multiple pieces of software that
1877 depend on the separate versions of the library.
1878 To accommodate these situations, you can install multiple
1879 versions of the same library in parallel on the same system.
1880 </para>
1881
1882 <para>
1883 The process is straight forward as long as the libraries use
1884 proper versioning.
1885 With properly versioned libraries, all you need to do to
1886 individually specify the libraries is create separate,
1887 appropriately named recipes where the
1888 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
1889 name includes a portion that differentiates each library version
1890 (e.g.the major part of the version number).
1891 Thus, instead of having a single recipe that loads one version
1892 of a library (e.g. <filename>clutter</filename>), you provide
1893 multiple recipes that result in different versions
1894 of the libraries you want.
1895 As an example, the following two recipes would allow the
1896 two separate versions of the <filename>clutter</filename>
1897 library to co-exist on the same system:
1898 <literallayout class='monospaced'>
1899 clutter-1.6_1.6.20.bb
1900 clutter-1.8_1.8.4.bb
1901 </literallayout>
1902 Additionally, if you have other recipes that depend on a given
1903 library, you need to use the
1904 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1905 variable to create the dependency.
1906 Continuing with the same example, if you want to have a recipe
1907 depend on the 1.8 version of the <filename>clutter</filename>
1908 library, use the following in your recipe:
1909 <literallayout class='monospaced'>
1910 DEPENDS = "clutter-1.8"
1911 </literallayout>
1912 </para>
1913 </section>
1914 </section>
1915
1916 <section id='configuring-the-kernel'>
1917 <title>Configuring the Kernel</title>
1918
1919 <para>
1920 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
1921 file has all the right information in it for the image you are building.
1922 You can use the <filename>menuconfig</filename> tool and configuration fragments to
1923 make sure your <filename>.config</filename> file is just how you need it.
1924 This section describes how to use <filename>menuconfig</filename>, create and use
1925 configuration fragments, and how to interactively tweak your <filename>.config</filename>
1926 file to create the leanest kernel configuration file possible.
1927 </para>
1928
1929 <para>
1930 For more information on kernel configuration, see the
1931 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
1932 section in the Yocto Project Linux Kernel Development Manual.
1933 </para>
1934
1935 <section id='using-menuconfig'>
1936 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
1937
1938 <para>
1939 The easiest way to define kernel configurations is to set them through the
1940 <filename>menuconfig</filename> tool.
1941 This tool provides an interactive method with which
1942 to set kernel configurations.
1943 For general information on <filename>menuconfig</filename>, see
1944 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1945 </para>
1946
1947 <para>
1948 To use the <filename>menuconfig</filename> tool in the Yocto Project development
1949 environment, you must build the tool using BitBake.
1950 Thus, the environment must be set up using the
1951 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1952 or
1953 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
1954 script found in the
1955 <link linkend='build-directory'>Build Directory</link>.
1956 The following commands build and invoke <filename>menuconfig</filename> assuming the
1957 <link linkend='source-directory'>Source Directory</link>
1958 top-level folder is <filename>~/poky</filename>:
1959 <literallayout class='monospaced'>
1960 $ cd ~/poky
1961 $ source oe-init-build-env
1962 $ bitbake linux-yocto -c menuconfig
1963 </literallayout>
1964 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
1965 interactively examine and configure all the kernel configuration parameters.
1966 After making your changes, simply exit the tool and save your changes to
1967 create an updated version of the <filename>.config</filename> configuration file.
1968 </para>
1969
1970 <para>
1971 Consider an example that configures the <filename>linux-yocto-3.4</filename>
1972 kernel.
1973 The OpenEmbedded build system recognizes this kernel as
1974 <filename>linux-yocto</filename>.
1975 Thus, the following commands from the shell in which you previously sourced the
1976 environment initialization script cleans the shared state cache and the
1977 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
1978 directory and then builds and launches <filename>menuconfig</filename>:
1979 <literallayout class='monospaced'>
1980 $ bitbake linux-yocto -c menuconfig
1981 </literallayout>
1982 </para>
1983
1984 <para>
1985 Once <filename>menuconfig</filename> launches, use the interface
1986 to navigate through the selections to find the configuration settings in
1987 which you are interested.
1988 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
1989 You can find it at <filename>Processor Type and Features</filename> under
1990 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
1991 After highlighting the selection, use the arrow keys to select or deselect
1992 the setting.
1993 When you are finished with all your selections, exit out and save them.
1994 </para>
1995
1996 <para>
1997 Saving the selections updates the <filename>.config</filename> configuration file.
1998 This is the file that the OpenEmbedded build system uses to configure the
1999 kernel during the build.
2000 You can find and examine this file in the Build Directory in
2001 <filename>tmp/work/</filename>.
2002 The actual <filename>.config</filename> is located in the area where the
2003 specific kernel is built.
2004 For example, if you were building a Linux Yocto kernel based on the
2005 Linux 3.4 kernel and you were building a QEMU image targeted for
2006 <filename>x86</filename> architecture, the
2007 <filename>.config</filename> file would be located here:
2008 <literallayout class='monospaced'>
2009 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
2010 ...656ed30-r1/linux-qemux86-standard-build
2011 </literallayout>
2012 <note>
2013 The previous example directory is artificially split and many of the characters
2014 in the actual filename are omitted in order to make it more readable.
2015 Also, depending on the kernel you are using, the exact pathname
2016 for <filename>linux-yocto-3.4...</filename> might differ.
2017 </note>
2018 </para>
2019
2020 <para>
2021 Within the <filename>.config</filename> file, you can see the kernel settings.
2022 For example, the following entry shows that symmetric multi-processor support
2023 is not set:
2024 <literallayout class='monospaced'>
2025 # CONFIG_SMP is not set
2026 </literallayout>
2027 </para>
2028
2029 <para>
2030 A good method to isolate changed configurations is to use a combination of the
2031 <filename>menuconfig</filename> tool and simple shell commands.
2032 Before changing configurations with <filename>menuconfig</filename>, copy the
2033 existing <filename>.config</filename> and rename it to something else,
2034 use <filename>menuconfig</filename> to make
2035 as many changes an you want and save them, then compare the renamed configuration
2036 file against the newly created file.
2037 You can use the resulting differences as your base to create configuration fragments
2038 to permanently save in your kernel layer.
2039 <note>
2040 Be sure to make a copy of the <filename>.config</filename> and don't just
2041 rename it.
2042 The build system needs an existing <filename>.config</filename>
2043 from which to work.
2044 </note>
2045 </para>
2046 </section>
2047
2048 <section id='creating-config-fragments'>
2049 <title>Creating Configuration Fragments</title>
2050
2051 <para>
2052 Configuration fragments are simply kernel options that appear in a file
2053 placed where the OpenEmbedded build system can find and apply them.
2054 Syntactically, the configuration statement is identical to what would appear
2055 in the <filename>.config</filename> file, which is in the
2056 <link linkend='build-directory'>Build Directory</link> in
2057 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
2058 </para>
2059
2060 <para>
2061 It is simple to create a configuration fragment.
2062 For example, issuing the following from the shell creates a configuration fragment
2063 file named <filename>my_smp.cfg</filename> that enables multi-processor support
2064 within the kernel:
2065 <literallayout class='monospaced'>
2066 $ echo "CONFIG_SMP=y" >> my_smp.cfg
2067 </literallayout>
2068 <note>
2069 All configuration files must use the <filename>.cfg</filename> extension in order
2070 for the OpenEmbedded build system to recognize them as a configuration fragment.
2071 </note>
2072 </para>
2073
2074 <para>
2075 Where do you put your configuration files?
2076 You can place these configuration files in the same area pointed to by
2077 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
2078 The OpenEmbedded build system will pick up the configuration and add it to the
2079 kernel's configuration.
2080 For example, suppose you had a set of configuration options in a file called
2081 <filename>myconfig.cfg</filename>.
2082 If you put that file inside a directory named <filename>/linux-yocto</filename>
2083 that resides in the same directory as the kernel's append file and then add
2084 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
2085 those configuration options will be picked up and applied when the kernel is built.
2086 <literallayout class='monospaced'>
2087 SRC_URI += "file://myconfig.cfg"
2088 </literallayout>
2089 </para>
2090
2091 <para>
2092 As mentioned earlier, you can group related configurations into multiple files and
2093 name them all in the <filename>SRC_URI</filename> statement as well.
2094 For example, you could group separate configurations specifically for Ethernet and graphics
2095 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
2096 following in your append file:
2097 <literallayout class='monospaced'>
2098 SRC_URI += "file://myconfig.cfg \
2099 file://eth.cfg \
2100 file://gfx.cfg"
2101 </literallayout>
2102 </para>
2103 </section>
2104
2105 <section id='fine-tuning-the-kernel-configuration-file'>
2106 <title>Fine-Tuning the Kernel Configuration File</title>
2107
2108 <para>
2109 You can make sure the <filename>.config</filename> file is as lean or efficient as
2110 possible by reading the output of the kernel configuration fragment audit,
2111 noting any issues, making changes to correct the issues, and then repeating.
2112 </para>
2113
2114 <para>
2115 As part of the kernel build process, the
2116 <filename>kernel_configcheck</filename> task runs.
2117 This task validates the kernel configuration by checking the final
2118 <filename>.config</filename> file against the input files.
2119 During the check, the task produces warning messages for the following
2120 issues:
2121 <itemizedlist>
2122 <listitem><para>Requested options that did not make the final
2123 <filename>.config</filename> file.</para></listitem>
2124 <listitem><para>Configuration items that appear twice in the same
2125 configuration fragment.</para></listitem>
2126 <listitem><para>Configuration items tagged as "required" were overridden.
2127 </para></listitem>
2128 <listitem><para>A board overrides a non-board specific option.</para></listitem>
2129 <listitem><para>Listed options not valid for the kernel being processed.
2130 In other words, the option does not appear anywhere.</para></listitem>
2131 </itemizedlist>
2132 <note>
2133 The <filename>kernel_configcheck</filename> task can also optionally report
2134 if an option is overridden during processing.
2135 </note>
2136 </para>
2137
2138 <para>
2139 For each output warning, a message points to the file
2140 that contains a list of the options and a pointer to the config
2141 fragment that defines them.
2142 Collectively, the files are the key to streamlining the configuration.
2143 </para>
2144
2145 <para>
2146 To streamline the configuration, do the following:
2147 <orderedlist>
2148 <listitem><para>Start with a full configuration that you know
2149 works - it builds and boots successfully.
2150 This configuration file will be your baseline.</para></listitem>
2151 <listitem><para>Separately run the <filename>configme</filename> and
2152 <filename>kernel_configcheck</filename> tasks.</para></listitem>
2153 <listitem><para>Take the resulting list of files from the
2154 <filename>kernel_configcheck</filename> task warnings and do the following:
2155 <itemizedlist>
2156 <listitem><para>Drop values that are redefined in the fragment but do not
2157 change the final <filename>.config</filename> file.</para></listitem>
2158 <listitem><para>Analyze and potentially drop values from the
2159 <filename>.config</filename> file that override required
2160 configurations.</para></listitem>
2161 <listitem><para>Analyze and potentially remove non-board specific options.
2162 </para></listitem>
2163 <listitem><para>Remove repeated and invalid options.</para></listitem>
2164 </itemizedlist></para></listitem>
2165 <listitem><para>After you have worked through the output of the kernel configuration
2166 audit, you can re-run the <filename>configme</filename>
2167 and <filename>kernel_configcheck</filename> tasks to see the results of your
2168 changes.
2169 If you have more issues, you can deal with them as described in the
2170 previous step.</para></listitem>
2171 </orderedlist>
2172 </para>
2173
2174 <para>
2175 Iteratively working through steps two through four eventually yields
2176 a minimal, streamlined configuration file.
2177 Once you have the best <filename>.config</filename>, you can build the Linux
2178 Yocto kernel.
2179 </para>
2180 </section>
2181 </section>
2182
2183 <section id="patching-the-kernel">
2184 <title>Patching the Kernel</title>
2185
2186 <para>
2187 Patching the kernel involves changing or adding configurations to an existing kernel,
2188 changing or adding recipes to the kernel that are needed to support specific hardware features,
2189 or even altering the source code itself.
2190 <note>
2191 You can use the <filename>yocto-kernel</filename> script
2192 found in the <link linkend='source-directory'>Source Directory</link>
2193 under <filename>scripts</filename> to manage kernel patches and configuration.
2194 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>"
2195 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
2196 more information.</note>
2197 </para>
2198
2199 <para>
2200 This example creates a simple patch by adding some QEMU emulator console
2201 output at boot time through <filename>printk</filename> statements in the kernel's
2202 <filename>calibrate.c</filename> source code file.
2203 Applying the patch and booting the modified image causes the added
2204 messages to appear on the emulator's console.
2205 </para>
2206
2207 <para>
2208 The example assumes a clean build exists for the <filename>qemux86</filename>
2209 machine in a Source Directory named <filename>poky</filename>.
2210 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
2211 <filename>build</filename> and is located in <filename>poky</filename> and
2212 the kernel is based on the Linux 3.4 kernel.
2213 For general information on how to configure the most efficient build, see the
2214 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
2215 in the Yocto Project Quick Start.
2216 </para>
2217
2218 <para>
2219 Also, for more information on patching the kernel, see the
2220 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
2221 section in the Yocto Project Linux Kernel Development Manual.
2222 </para>
2223
2224 <section id='create-a-layer-for-your-changes'>
2225 <title>Create a Layer for your Changes</title>
2226
2227 <para>
2228 The first step is to create a layer so you can isolate your changes:
2229 <literallayout class='monospaced'>
2230 $cd ~/poky
2231 $mkdir meta-mylayer
2232 </literallayout>
2233 Creating a directory that follows the Yocto Project layer naming
2234 conventions sets up the layer for your changes.
2235 The layer is where you place your configuration files, append
2236 files, and patch files.
2237 To learn more about creating a layer and filling it with the
2238 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
2239 and Creating Layers</link>" section.
2240 </para>
2241 </section>
2242
2243 <section id='finding-the-kernel-source-code'>
2244 <title>Finding the Kernel Source Code</title>
2245
2246 <para>
2247 Each time you build a kernel image, the kernel source code is fetched
2248 and unpacked into the following directory:
2249 <literallayout class='monospaced'>
2250 ${S}/linux
2251 </literallayout>
2252 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
2253 section and the
2254 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
2255 for more information about where source is kept during a build.
2256 </para>
2257
2258 <para>
2259 For this example, we are going to patch the
2260 <filename>init/calibrate.c</filename> file
2261 by adding some simple console <filename>printk</filename> statements that we can
2262 see when we boot the image using QEMU.
2263 </para>
2264 </section>
2265
2266 <section id='creating-the-patch'>
2267 <title>Creating the Patch</title>
2268
2269 <para>
2270 Two methods exist by which you can create the patch:
2271 <link linkend='using-a-git-workflow'>Git workflow</link> and
2272 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
2273 For kernel patches, the Git workflow is more appropriate.
2274 This section assumes the Git workflow and shows the steps specific to
2275 this example.
2276 <orderedlist>
2277 <listitem><para><emphasis>Change the working directory</emphasis>:
2278 Change to where the kernel source code is before making
2279 your edits to the <filename>calibrate.c</filename> file:
2280 <literallayout class='monospaced'>
2281 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
2282 </literallayout>
2283 Because you are working in an established Git repository,
2284 you must be in this directory in order to commit your changes
2285 and create the patch file.
2286 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
2287 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
2288 represent the version and revision for the
2289 <filename>linux-yocto</filename> recipe.
2290 The <filename>PV</filename> variable includes the Git meta and machine
2291 hashes, which make the directory name longer than you might
2292 expect.
2293 </note></para></listitem>
2294 <listitem><para><emphasis>Edit the source file</emphasis>:
2295 Edit the <filename>init/calibrate.c</filename> file to have the
2296 following changes:
2297 <literallayout class='monospaced'>
2298 void __cpuinit calibrate_delay(void)
2299 {
2300 unsigned long lpj;
2301 static bool printed;
2302 int this_cpu = smp_processor_id();
2303
2304 printk("*************************************\n");
2305 printk("* *\n");
2306 printk("* HELLO YOCTO KERNEL *\n");
2307 printk("* *\n");
2308 printk("*************************************\n");
2309
2310 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
2311 .
2312 .
2313 .
2314 </literallayout></para></listitem>
2315 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
2316 These Git commands display the modified file, stage it, and then
2317 commit the file:
2318 <literallayout class='monospaced'>
2319 $ git status
2320 $ git add init/calibrate.c
2321 $ git commit -m "calibrate: Add printk example"
2322 </literallayout></para></listitem>
2323 <listitem><para><emphasis>Generate the patch file</emphasis>:
2324 This Git command creates the a patch file named
2325 <filename>0001-calibrate-Add-printk-example.patch</filename>
2326 in the current directory.
2327 <literallayout class='monospaced'>
2328 $ git format-patch -1
2329 </literallayout>
2330 </para></listitem>
2331 </orderedlist>
2332 </para>
2333 </section>
2334
2335 <section id='set-up-your-layer-for-the-build'>
2336 <title>Set Up Your Layer for the Build</title>
2337
2338 <para>These steps get your layer set up for the build:
2339 <orderedlist>
2340 <listitem><para><emphasis>Create additional structure</emphasis>:
2341 Create the additional layer structure:
2342 <literallayout class='monospaced'>
2343 $ cd ~/poky/meta-mylayer
2344 $ mkdir conf
2345 $ mkdir recipes-kernel
2346 $ mkdir recipes-kernel/linux
2347 $ mkdir recipes-kernel/linux/linux-yocto
2348 </literallayout>
2349 The <filename>conf</filename> directory holds your configuration files, while the
2350 <filename>recipes-kernel</filename> directory holds your append file and
2351 your patch file.</para></listitem>
2352 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
2353 Move to the <filename>meta-mylayer/conf</filename> directory and create
2354 the <filename>layer.conf</filename> file as follows:
2355 <literallayout class='monospaced'>
2356 # We have a conf and classes directory, add to BBPATH
2357 BBPATH .= ":${LAYERDIR}"
2358
2359 # We have recipes-* directories, add to BBFILES
2360 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
2361 ${LAYERDIR}/recipes-*/*/*.bbappend"
2362
2363 BBFILE_COLLECTIONS += "mylayer"
2364 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
2365 BBFILE_PRIORITY_mylayer = "5"
2366 </literallayout>
2367 Notice <filename>mylayer</filename> as part of the last three
2368 statements.</para></listitem>
2369 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
2370 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
2371 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
2372 <literallayout class='monospaced'>
2373 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2374
2375 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
2376
2377 PRINC := "${@int(PRINC) + 1}"
2378 </literallayout>
2379 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
2380 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2381 statements enable the OpenEmbedded build system to find the patch file.
2382 For more information on using append files, see the
2383 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
2384 section.
2385 </para></listitem>
2386 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
2387 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
2388 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
2389 directory.</para></listitem>
2390 </orderedlist>
2391 </para>
2392 </section>
2393
2394 <section id='set-up-for-the-build'>
2395 <title>Set Up for the Build</title>
2396
2397 <para>
2398 Do the following to make sure the build parameters are set up for the example.
2399 Once you set up these build parameters, they do not have to change unless you
2400 change the target architecture of the machine you are building:
2401 <itemizedlist>
2402 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
2403 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2404 definition within the <filename>local.conf</filename> file in the
2405 <link linkend='build-directory'>Build Directory</link>
2406 specifies the target architecture used when building the Linux kernel.
2407 By default, <filename>MACHINE</filename> is set to
2408 <filename>qemux86</filename>, which specifies a 32-bit
2409 <trademark class='registered'>Intel</trademark> Architecture
2410 target machine suitable for the QEMU emulator.</para></listitem>
2411 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
2412 layer:</emphasis> The
2413 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
2414 variable in the
2415 <filename>bblayers.conf</filename> file found in the
2416 <filename>poky/build/conf</filename> directory needs to have the path to your local
2417 <filename>meta-mylayer</filename> layer.
2418 By default, the <filename>BBLAYERS</filename> variable contains paths to
2419 <filename>meta</filename>, <filename>meta-yocto</filename>, and
2420 <filename>meta-yocto-bsp</filename> in the
2421 <filename>poky</filename> Git repository.
2422 Add the path to your <filename>meta-mylayer</filename> location:
2423 <literallayout class='monospaced'>
2424 BBLAYERS ?= " \
2425 $HOME/poky/meta \
2426 $HOME/poky/meta-yocto \
2427 $HOME/poky/meta-yocto-bsp \
2428 $HOME/poky/meta-mylayer \
2429 "
2430
2431 BBLAYERS_NON_REMOVABLE ?= " \
2432 $HOME/poky/meta \
2433 $HOME/poky/meta-yocto \
2434 "
2435 </literallayout></para></listitem>
2436 </itemizedlist>
2437 </para>
2438 </section>
2439
2440 <section id='build-the-modified-qemu-kernel-image'>
2441 <title>Build the Modified QEMU Kernel Image</title>
2442
2443 <para>
2444 The following steps build your modified kernel image:
2445 <orderedlist>
2446 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
2447 Your environment should be set up since you previously sourced
2448 the
2449 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
2450 script.
2451 If it is not, source the script again from <filename>poky</filename>.
2452 <literallayout class='monospaced'>
2453 $ cd ~/poky
2454 $ source &OE_INIT_FILE;
2455 </literallayout>
2456 </para></listitem>
2457 <listitem><para><emphasis>Clean up</emphasis>:
2458 Be sure to clean the shared state out by running the
2459 <filename>cleansstate</filename> BitBake task as follows from your Build Directory:
2460 <literallayout class='monospaced'>
2461 $ bitbake -c cleansstate linux-yocto
2462 </literallayout></para>
2463 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
2464 directory inside the
2465 <link linkend='build-directory'>Build Directory</link>.
2466 Always use the various BitBake clean tasks to clear out previous
2467 build artifacts.
2468 </note></para></listitem>
2469 <listitem><para><emphasis>Build the image</emphasis>:
2470 Next, build the kernel image using this command:
2471 <literallayout class='monospaced'>
2472 $ bitbake -k linux-yocto
2473 </literallayout></para></listitem>
2474 </orderedlist>
2475 </para>
2476 </section>
2477
2478 <section id='boot-the-image-and-verify-your-changes'>
2479 <title>Boot the Image and Verify Your Changes</title>
2480
2481 <para>
2482 These steps boot the image and allow you to see the changes
2483 <orderedlist>
2484 <listitem><para><emphasis>Boot the image</emphasis>:
2485 Boot the modified image in the QEMU emulator
2486 using this command:
2487 <literallayout class='monospaced'>
2488 $ runqemu qemux86
2489 </literallayout></para></listitem>
2490 <listitem><para><emphasis>Verify the changes</emphasis>:
2491 Log into the machine using <filename>root</filename> with no password and then
2492 use the following shell command to scroll through the console's boot output.
2493 <literallayout class='monospaced'>
2494 # dmesg | less
2495 </literallayout>
2496 You should see the results of your <filename>printk</filename> statements
2497 as part of the output.</para></listitem>
2498 </orderedlist>
2499 </para>
2500 </section>
2501 </section>
2502
2503 <section id='creating-your-own-distribution'>
2504 <title>Creating Your Own Distribution</title>
2505
2506 <para>
2507 When you build an image using the Yocto Project and
2508 do not alter any distribution
2509 <link linkend='metadata'>Metadata</link>, you are creating a
2510 Poky distribution.
2511 If you wish to gain more control over package alternative
2512 selections, compile-time options, and other low-level
2513 configurations, you can create your own distribution.
2514 </para>
2515
2516 <para>
2517 To create your own distribution, the basic steps consist of
2518 creating your own distribution layer, creating your own
2519 distribution configuration file, and then adding any needed
2520 code and Metadata to the layer.
2521 The following steps provide some more detail:
2522 <itemizedlist>
2523 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
2524 Create your distribution layer so that you can keep your
2525 Metadata and code for the distribution separate.
2526 It is strongly recommended that you create and use your own
2527 layer for configuration and code.
2528 Using your own layer as compared to just placing
2529 configurations in a <filename>local.conf</filename>
2530 configuration file makes it easier to reproduce the same
2531 build configuration when using multiple build machines.
2532 See the
2533 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
2534 section for information on how to quickly set up a layer.
2535 </para></listitem>
2536 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
2537 The distribution configuration file needs to be created in
2538 the <filename>conf/distro</filename> directory of your
2539 layer.
2540 You need to name it using your distribution name
2541 (e.g. <filename>mydistro.conf</filename>).</para>
2542 <para>You can split out parts of your configuration file
2543 into include files and then "require" them from within
2544 your distribution configuration file.
2545 Be sure to place the include files in the
2546 <filename>conf/distro/include</filename> directory of
2547 your layer.
2548 A common example usage of include files would be to
2549 separate out the selection of desired version and revisions
2550 for individual recipes.
2551</para>
2552 <para>Your configuration file needs to set the following
2553 required variables:
2554 <literallayout class='monospaced'>
2555 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> [required]
2556 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink> [required]
2557 </literallayout>
2558 These following variables are optional and you typically
2559 set them from the distribution configuration file:
2560 <literallayout class='monospaced'>
2561 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> [optional]
2562 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink> [optional]
2563 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink> [optional]
2564 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink> [optional]
2565 </literallayout>
2566 <tip>
2567 If you want to base your distribution configuration file
2568 on the very basic configuration from OE-Core, you
2569 can use
2570 <filename>conf/distro/defaultsetup.conf</filename> as
2571 a reference and just include variables that differ
2572 as compared to <filename>defaultsetup.conf</filename>.
2573 Alternatively, you can create a distribution
2574 configuration file from scratch using the
2575 <filename>defaultsetup.conf</filename> file
2576 or configuration files from other distributions
2577 such as Poky or Angstrom as references.
2578 </tip></para></listitem>
2579 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
2580 Be sure to define any other variables for which you want to
2581 create a default or enforce as part of the distribution
2582 configuration.
2583 You can include nearly any variable from the
2584 <filename>local.conf</filename> file.
2585 The variables you use are not limited to the list in the
2586 previous bulleted item.</para></listitem>
2587 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
2588 In your <filename>local.conf</filename> file in the
2589 <link linkend='build-directory'>Build Directory</link>,
2590 set your
2591 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
2592 variable to point to your distribution's configuration file.
2593 For example, if your distribution's configuration file is
2594 named <filename>mydistro.conf</filename>, then you point
2595 to it as follows:
2596 <literallayout class='monospaced'>
2597 DISTRO = "mydistro"
2598 </literallayout></para></listitem>
2599 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
2600 Use your layer to hold other information needed for the
2601 distribution:
2602 <itemizedlist>
2603 <listitem><para>Add recipes for installing
2604 distro-specific configuration files that are not
2605 already installed by another recipe.
2606 If you have distro-specific configuration files
2607 that are included by an existing recipe, you should
2608 add a <filename>.bbappend</filename> for those.
2609 For general information and recommendations
2610 on how to add recipes to your layer, see the
2611 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
2612 and
2613 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
2614 sections.</para></listitem>
2615 <listitem><para>Add any image recipes that are specific
2616 to your distribution.</para></listitem>
2617 <listitem><para>Add a <filename>psplash</filename>
2618 append file for a branded splash screen.
2619 For information on append files, see the
2620 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
2621 section.</para></listitem>
2622 <listitem><para>Add any other append files to make
2623 custom changes that are specific to individual
2624 recipes.</para></listitem>
2625 </itemizedlist></para></listitem>
2626 </itemizedlist>
2627 </para>
2628 </section>
2629
2630 <section id='building-a-tiny-system'>
2631 <title>Building a Tiny System</title>
2632
2633 <para>
2634 Very small distributions have some significant advantages such
2635 as requiring less on-die or in-package memory (cheaper), better
2636 performance through efficient cache usage, lower power requirements
2637 due to less memory, faster boot times, and reduced development
2638 overhead.
2639 Some real-world examples where a very small distribution gives
2640 you distinct advantages are digital cameras, medical devices,
2641 and small headless systems.
2642 </para>
2643
2644 <para>
2645 This section presents information that shows you how you can
2646 trim your distribution to even smaller sizes than the
2647 <filename>poky-tiny</filename> distribution, which is around
2648 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
2649 </para>
2650
2651 <section id='tiny-system-overview'>
2652 <title>Overview</title>
2653
2654 <para>
2655 The following list presents the overall steps you need to
2656 consider and perform to create distributions with smaller
2657 root filesystems, faster boot times, maintain your critical
2658 functionality, and avoid initial RAM disks:
2659 <itemizedlist>
2660 <listitem><para>Determine your goals and guiding
2661 principles.</para></listitem>
2662 <listitem><para>Understand what gives your image size.
2663 </para></listitem>
2664 <listitem><para>Reduce the size of the root filesystem.
2665 </para></listitem>
2666 <listitem><para>Reduce the size of the kernel.
2667 </para></listitem>
2668 <listitem><para>Eliminate packaging requirements.
2669 </para></listitem>
2670 <listitem><para>Look for other ways to minimize size.
2671 </para></listitem>
2672 <listitem><para>Iterate on the process.</para></listitem>
2673 </itemizedlist>
2674 </para>
2675 </section>
2676
2677 <section id='goals-and-guiding-principles'>
2678 <title>Goals and Guiding Principles</title>
2679
2680 <para>
2681 Before you can reach your destination, you need to know
2682 where you are going.
2683 Here is an example list that you can use as a guide when
2684 creating very small distributions:
2685 <itemizedlist>
2686 <listitem><para>Determine how much space you need
2687 (e.g. a kernel that is 1 Mbyte or less and
2688 a root filesystem that is 3 Mbytes or less).
2689 </para></listitem>
2690 <listitem><para>Find the areas that are currently
2691 taking 90% of the space and concentrate on reducing
2692 those areas.
2693 </para></listitem>
2694 <listitem><para>Do not create any difficult "hacks"
2695 to achieve your goals.</para></listitem>
2696 <listitem><para>Leverage the device-specific
2697 options.</para></listitem>
2698 <listitem><para>Work in a separate layer so that you
2699 keep changes isolated.
2700 For information on how to create layers, see
2701 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
2702 </para></listitem>
2703 </itemizedlist>
2704 </para>
2705 </section>
2706
2707 <section id='understand-what-gives-your-image-size'>
2708 <title>Understand What Gives Your Image Size</title>
2709
2710 <para>
2711 It is easiest to have something to start with when creating
2712 your own distribution.
2713 You can use the Yocto Project out-of-the-box to create the
2714 <filename>poky-tiny</filename> distribution.
2715 Ultimately, you will want to make changes in your own
2716 distribution that are likely modeled after
2717 <filename>poky-tiny</filename>.
2718 <note>
2719 To use <filename>poky-tiny</filename> in your build,
2720 set the
2721 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
2722 variable in your
2723 <filename>local.conf</filename> file to "poky-tiny"
2724 as described in the
2725 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
2726 section.
2727 </note>
2728 </para>
2729
2730 <para>
2731 Understanding some memory concepts will help you reduce the
2732 system size.
2733 Memory consists of static, dynamic, and temporary memory.
2734 Static memory is the TEXT (code), DATA (initialized data
2735 in the code), and BSS (uninitialized data) sections.
2736 Dynamic memory contains memory that is allocated at runtime,
2737 stacks, hash tables, and so forth.
2738 Temporary memory is recovered after the boot process.
2739 This memory consists of memory used for decompressing
2740 the kernel and for the <filename>__init__</filename>
2741 functions.
2742 </para>
2743
2744 <para>
2745 To help you see where you currently are with kernel and root
2746 filesystem sizes, you can use two tools found in the
2747 <link linkend='source-directory'>Source Directory</link> in
2748 the <filename>scripts</filename> directory:
2749 <itemizedlist>
2750 <listitem><para><filename>ksize.py</filename>: Reports
2751 component sizes for the kernel build objects.
2752 </para></listitem>
2753 <listitem><para><filename>dirsize.py</filename>: Reports
2754 component sizes for the root filesystem.</para></listitem>
2755 </itemizedlist>
2756 This next tool and command helps you organize configuration
2757 fragments and view file dependencies in a human-readable form:
2758 <itemizedlist>
2759 <listitem><para><filename>merge_config.sh</filename>:
2760 Helps you manage configuration files and fragments
2761 within the kernel.
2762 With this tool, you can merge individual configuration
2763 fragments together.
2764 The tool allows you to make overrides and warns you
2765 of any missing configuration options.
2766 The tool is ideal for allowing you to iterate on
2767 configurations, create minimal configurations, and
2768 create configuration files for different machines
2769 without having to duplicate your process.</para>
2770 <para>The <filename>merge_config.sh</filename> script is
2771 part of the Linux Yocto kernel Git repository in the
2772 <filename>scripts/kconfig</filename> directory.</para>
2773 <para>For more information on configuration fragments,
2774 see the
2775 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
2776 section of the Yocto Project Linux Kernel Development
2777 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
2778 section, which is in this manual.</para></listitem>
2779 <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
2780 Using the BitBake command with these options brings up
2781 a Dependency Explorer from which you can view file
2782 dependencies.
2783 Understanding these dependencies allows you to make
2784 informed decisions when cutting out various pieces of the
2785 kernel and root filesystem.</para></listitem>
2786 </itemizedlist>
2787 </para>
2788 </section>
2789
2790 <section id='trim-the-root-filesystem'>
2791 <title>Trim the Root Filesystem</title>
2792
2793 <para>
2794 The root filesystem is made up of packages for booting,
2795 libraries, and applications.
2796 To change things, you can configure how the packaging happens,
2797 which changes the way you build them.
2798 You can also tweak the filesystem itself or select a different
2799 filesystem.
2800 </para>
2801
2802 <para>
2803 First, find out what is hogging your root filesystem by running the
2804 <filename>dirsize.py</filename> script from your root directory:
2805 <literallayout class='monospaced'>
2806 $ cd &lt;root-directory-of-image&gt;
2807 $ dirsize.py 100000 > dirsize-100k.log
2808 $ cat dirsize-100k.log
2809 </literallayout>
2810 You can apply a filter to the script to ignore files under
2811 a certain size.
2812 This example filters out anything below 100 Kbytes.
2813 The sizes reported by the tool are uncompressed and thus,
2814 will be smaller by a relatively constant factor in a
2815 compressed root filesystem.
2816 When you examine your log file, you can focus on areas of the
2817 root filesystem that take up large amounts of memory.
2818 </para>
2819
2820 <para>
2821 You need to be sure that what you eliminate does not cripple
2822 the functionality you need.
2823 One way to see how packages relate to each other is by using
2824 the Dependency Explorer UI with the BitBake command:
2825 <literallayout class='monospaced'>
2826 $ cd &lt;image-directory&gt;
2827 $ bitbake -u depexp -g &lt;image&gt;
2828 </literallayout>
2829 Use the interface to select potential packages you wish to
2830 eliminate and see their dependency relationships.
2831 </para>
2832
2833 <para>
2834 When deciding how to reduce the size, get rid of packages that
2835 result in minimal impact on the feature set.
2836 For example, you might not need a VGA display.
2837 Or, you might be able to get by with <filename>devtmpfs</filename>
2838 and <filename>mdev</filename> instead of
2839 <filename>udev</filename>.
2840 </para>
2841
2842 <para>
2843 Use the <filename>local.conf</filename> file to make changes.
2844 For example, to eliminate <filename>udev</filename> and
2845 <filename>glib</filename>, set the following in the
2846 local configuration file:
2847 <literallayout class='monospaced'>
2848 VIRTUAL-RUNTIME_dev_manager = ""
2849 </literallayout>
2850 </para>
2851
2852 <para>
2853 Finally, you should consider exactly the type of root
2854 filesystem you need to meet your needs while also reducing
2855 its size.
2856 For example, consider <filename>cramfs</filename>,
2857 <filename>squashfs</filename>, <filename>ubifs</filename>,
2858 <filename>ext2</filename>, or an <filename>initramfs</filename>
2859 using <filename>initramfs</filename>.
2860 Be aware that <filename>ext3</filename> requires a 1 Mbyte
2861 journal.
2862 If you are okay with running read-only you do not need this
2863 journal.
2864 </para>
2865
2866 <note>
2867 After each round of elimination, you need to rebuild your
2868 system and then use the tools to see the effects of your
2869 reductions.
2870 </note>
2871
2872
2873 </section>
2874
2875 <section id='trim-the-kernel'>
2876 <title>Trim the Kernel</title>
2877
2878 <para>
2879 The kernel is built by including policies for hardware-independent
2880 aspects.
2881 What subsystems do you enable?
2882 For what architecture are you building?
2883 Which drivers do you build by default.
2884 <note>You can modify the kernel source if you want to help
2885 with boot time.
2886 </note>
2887 </para>
2888
2889 <para>
2890 Run the <filename>ksize.py</filename> script from the top-level
2891 Linux build directory to get an idea of what is making up
2892 the kernel:
2893 <literallayout class='monospaced'>
2894 $ cd &lt;top-level-linux-build-directory&gt;
2895 $ ksize.py > ksize.log
2896 $ cat ksize.log
2897 </literallayout>
2898 When you examine the log, you will see how much space is
2899 taken up with the built-in <filename>.o</filename> files for
2900 drivers, networking, core kernel files, filesystem, sound,
2901 and so forth.
2902 The sizes reported by the tool are uncompressed and thus,
2903 will be smaller by a relatively constant factor in a compressed
2904 kernel image.
2905 Look to reduce the areas that are large and taking up around
2906 the "90% rule."
2907 </para>
2908
2909 <para>
2910 To examine, or drill down, into any particular area, use the
2911 <filename>-d</filename> option with the script:
2912 <literallayout class='monospaced'>
2913 $ ksize.py -d > ksize.log
2914 </literallayout>
2915 Using this option breaks out the individual file information
2916 for each area of the kernel (e.g. drivers, networking, and
2917 so forth).
2918 </para>
2919
2920 <para>
2921 Use your log file to see what you can eliminate from the kernel
2922 based on features you can let go.
2923 For example, if you are not going to need sound, you do not
2924 need any drivers that support sound.
2925 </para>
2926
2927 <para>
2928 After figuring out what to eliminate, you need to reconfigure
2929 the kernel to reflect those changes during the next build.
2930 You could run <filename>menuconfig</filename> and make all your
2931 changes at once.
2932 However, that makes it difficult to see the effects of your
2933 individual eliminations and also makes it difficult to replicate
2934 the changes for perhaps another target device.
2935 A better method is to start with no configurations using
2936 <filename>allnoconfig</filename>, create configuration
2937 fragments for individual changes, and then manage the
2938 fragments into a single configuration file using
2939 <filename>merge_config.sh</filename>.
2940 The tool makes it easy for you to iterate using the
2941 configuration change and build cycle.
2942 </para>
2943
2944 <para>
2945 Each time you make configuration changes, you need to rebuild
2946 the kernel and check to see what impact your changes had on
2947 the overall size.
2948 </para>
2949 </section>
2950
2951 <section id='remove-package-management-requirements'>
2952 <title>Remove Package Management Requirements</title>
2953
2954 <para>
2955 Packaging requirements add size to the image.
2956 One way to reduce the size of the image is to remove all the
2957 packaging requirements from the image.
2958 This reduction includes both removing the package manager
2959 and its unique dependencies as well as removing the package
2960 management data itself.
2961 </para>
2962
2963 <para>
2964 To eliminate all the packaging requirements for an image,
2965 follow these steps:
2966 <orderedlist>
2967 <listitem><para>Put the following line in your main
2968 recipe for the image to remove package management
2969 data files:
2970 <literallayout class='monospaced'>
2971 ROOTFS_POSTPROCESS_COMMAND += "remove_packaging_data_files ;
2972 </literallayout>
2973 For example, the recipe for the
2974 <filename>core-image-minimal</filename> image contains
2975 this line.
2976 You can also add the line to the
2977 <filename>local.conf</filename> configuration file.
2978 </para></listitem>
2979 <listitem><para>Be sure that "package-management" is not
2980 part of your
2981 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
2982 statement for the image.
2983 When you remove this feature, you are removing the
2984 package manager as well as its dependencies
2985 from the root filesystem.
2986 </para></listitem>
2987 </orderedlist>
2988 </para>
2989 </section>
2990
2991 <section id='look-for-other-ways-to-minimize-size'>
2992 <title>Look for Other Ways to Minimize Size</title>
2993
2994 <para>
2995 Depending on your particular circumstances, other areas that you
2996 can trim likely exist.
2997 The key to finding these areas is through tools and methods
2998 described here combined with experimentation and iteration.
2999 Here are a couple of areas to experiment with:
3000 <itemizedlist>
3001 <listitem><para><filename>eglibc</filename>:
3002 In general, follow this process:
3003 <orderedlist>
3004 <listitem><para>Remove <filename>eglibc</filename>
3005 features from
3006 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3007 that you think you do not need.</para></listitem>
3008 <listitem><para>Build your distribution.
3009 </para></listitem>
3010 <listitem><para>If the build fails due to missing
3011 symbols in a package, determine if you can
3012 reconfigure the package to not need those
3013 features.
3014 For example, change the configuration to not
3015 support wide character support as is done for
3016 <filename>ncurses</filename>.
3017 Or, if support for those characters is needed,
3018 determine what <filename>eglibc</filename>
3019 features provide the support and restore the
3020 configuration.
3021 </para></listitem>
3022 <listitem><para>Rebuild and repeat the process.
3023 </para></listitem>
3024 </orderedlist></para></listitem>
3025 <listitem><para><filename>busybox</filename>:
3026 For BusyBox, use a process similar as described for
3027 <filename>eglibc</filename>.
3028 A difference is you will need to boot the resulting
3029 system to see if you are able to do everything you
3030 expect from the running system.
3031 You need to be sure to integrate configuration fragments
3032 into Busybox because BusyBox handles its own core
3033 features and then allows you to add configuration
3034 fragments on top.
3035 </para></listitem>
3036 </itemizedlist>
3037 </para>
3038 </section>
3039
3040 <section id='iterate-on-the-process'>
3041 <title>Iterate on the Process</title>
3042
3043 <para>
3044 If you have not reached your goals on system size, you need
3045 to iterate on the process.
3046 The process is the same.
3047 Use the tools and see just what is taking up 90% of the root
3048 filesystem and the kernel.
3049 Decide what you can eliminate without limiting your device
3050 beyond what you need.
3051 </para>
3052
3053 <para>
3054 Depending on your system, a good place to look might be
3055 Busybox, which provides a stripped down
3056 version of Unix tools in a single, executable file.
3057 You might be able to drop virtual terminal services or perhaps
3058 ipv6.
3059 </para>
3060 </section>
3061 </section>
3062
3063 <section id='working-with-packages'>
3064 <title>Working with Packages</title>
3065
3066 <para>
3067 This section describes a few tasks that involve packages:
3068 <itemizedlist>
3069 <listitem><para>Excluding packages from an image
3070 </para></listitem>
3071 <listitem><para>Incrementing a package revision number
3072 </para></listitem>
3073 <listitem><para>Handling a package name alias
3074 </para></listitem>
3075 <listitem><para>Handling optional module packaging
3076 </para></listitem>
3077 <listitem><para>Using Runtime Package Management
3078 </para></listitem>
3079 <listitem><para>Setting up and running package test
3080 (ptest)
3081 </para></listitem>
3082 </itemizedlist>
3083 </para>
3084
3085 <section id='excluding-packages-from-an-image'>
3086 <title>Excluding Packages from an Image</title>
3087
3088 <para>
3089 You might find it necessary to prevent specific packages
3090 from being installed into an image.
3091 If so, you can use several variables to direct the build
3092 system to essentially ignore installing recommended packages
3093 or to not install a package at all.
3094 </para>
3095
3096 <para>
3097 The following list introduces variables you can use to
3098 prevent packages from being installed into your image.
3099 Each of these variables only works with IPK and RPM
3100 package types.
3101 Support for Debian packages does not exist.
3102 Also, you can use these variables from your
3103 <filename>local.conf</filename> file or attach them to a
3104 specific image recipe by using a recipe name override.
3105 For more detail on the variables, see the descriptions in the
3106 Yocto Project Reference Manual's glossary chapter.
3107 <itemizedlist>
3108 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
3109 Use this variable to specify "recommended-only"
3110 packages that you do not want installed.
3111 </para></listitem>
3112 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
3113 Use this variable to prevent all "recommended-only"
3114 packages from being installed.
3115 </para></listitem>
3116 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
3117 Use this variable to prevent specific packages from
3118 being installed regardless of whether they are
3119 "recommended-only" or not.
3120 You need to realize that the build process could
3121 fail with an error when you
3122 prevent the installation of a package whose presence
3123 is required by an installed package.
3124 </para></listitem>
3125 </itemizedlist>
3126 </para>
3127 </section>
3128
3129 <section id='incrementing-a-package-revision-number'>
3130 <title>Incrementing a Package Revision Number</title>
3131
3132 <para>
3133 If a committed change results in changing the package output,
3134 then the value of the
3135 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
3136 variable needs to be increased (or "bumped").
3137 Increasing <filename>PR</filename> occurs one of two ways:
3138 <itemizedlist>
3139 <listitem><para>Automatically using a Package Revision
3140 Service (PR Service).</para></listitem>
3141 <listitem><para>Manually incrementing the
3142 <filename>PR</filename> variable.</para></listitem>
3143 </itemizedlist>
3144 </para>
3145
3146 <para>
3147 Given that one of the challenges any build system and its
3148 users face is how to maintain a package feed that is compatible
3149 with existing package manager applications such as
3150 RPM, APT, and OPKG, using an automated system is much
3151 preferred over a manual system.
3152 In either system, the main requirement is that version
3153 numbering increases in a linear fashion and that a number of
3154 version components exist that support that linear progression.
3155 </para>
3156
3157 <para>
3158 The following two sections provide information on the PR Service
3159 and on manual <filename>PR</filename> bumping.
3160 </para>
3161
3162 <section id='working-with-a-pr-service'>
3163 <title>Working With a PR Service</title>
3164
3165 <para>
3166 As mentioned, attempting to maintain revision numbers in the
3167 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
3168 is error prone, inaccurate and causes problems for people
3169 submitting recipes.
3170 Conversely, the PR Service automatically generates
3171 increasing numbers, particularly the revision field,
3172 which removes the human element.
3173 <note>
3174 For additional information on using a PR Service, you
3175 can see the
3176 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
3177 wiki page.
3178 </note>
3179 </para>
3180
3181 <para>
3182 The Yocto Project uses variables in order of
3183 decreasing priority to facilitate revision numbering (i.e.
3184 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
3185 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
3186 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
3187 for epoch, version and revision, respectively).
3188 The values are highly dependent on the policies and
3189 procedures of a given distribution and package feed.
3190 </para>
3191
3192 <para>
3193 Because the OpenEmbedded build system uses
3194 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
3195 which are unique to a given build, the build system
3196 knows when to rebuild packages.
3197 All the inputs into a given task are represented by a
3198 signature, which can trigger a rebuild when different.
3199 Thus, the build system itself does not rely on the
3200 <filename>PR</filename> numbers to trigger a rebuild.
3201 The signatures, however, can be used to generate
3202 <filename>PR</filename> values.
3203 </para>
3204
3205 <para>
3206 The PR Service works with both
3207 <filename>OEBasic</filename> and
3208 <filename>OEBasicHash</filename> generators.
3209 The value of <filename>PR</filename> bumps when the
3210 checksum changes and the different generator mechanisms
3211 change signatures under different circumstances.
3212 </para>
3213
3214 <para>
3215 As implemented, the build system includes values from
3216 the PR Service into the <filename>PR</filename> field as
3217 an addition using the form "<filename>.x</filename>" so
3218 <filename>r0</filename> becomes <filename>r0.1</filename>,
3219 <filename>r0.2</filename> and so forth.
3220 This scheme allows existing <filename>PR</filename> values
3221 to be used for whatever reasons, which include manual
3222 <filename>PR</filename> bumps should it be necessary.
3223 </para>
3224
3225 <para>
3226 By default, the PR Service is not enabled or running.
3227 Thus, the packages generated are just "self consistent".
3228 The build system adds and removes packages and
3229 there are no guarantees about upgrade paths but images
3230 will be consistent and correct with the latest changes.
3231 </para>
3232
3233 <para>
3234 The simplest form for a PR Service is for it to exist
3235 for a single host development system that builds the
3236 package feed (building system).
3237 For this scenario, you can enable the PR Service by adding
3238 the following to your <filename>local.conf</filename>
3239 file in the
3240 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
3241 <literallayout class='monospaced'>
3242 PRSERV_HOST = "localhost:0"
3243 </literallayout>
3244 Once the service is started, packages will automatically
3245 get increasing <filename>PR</filename> values and
3246 BitBake will take care of starting and stopping the server.
3247 </para>
3248
3249 <para>
3250 If you have a more complex setup where multiple host
3251 development systems work against a common, shared package
3252 feed, you have a single PR Service running and it is
3253 connected to each building system.
3254 For this scenario, you need to start the PR Service using
3255 the <filename>bitbake-prserv</filename> command:
3256 <literallayout class='monospaced'>
3257 bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
3258 </literallayout>
3259 In addition to hand-starting the service, you need to
3260 update the <filename>local.conf</filename> file of each
3261 building system as described earlier so each system
3262 points to the server and port.
3263 </para>
3264
3265 <para>
3266 It is also recommended you use Build History, which adds
3267 some sanity checks to package versions, in conjunction with
3268 the server that is running the PR Service.
3269 To enable build history, add the following to each building
3270 system's <filename>local.conf</filename> file:
3271 <literallayout class='monospaced'>
3272 # It is recommended to activate "buildhistory" for testing the PR service
3273 INHERIT += "buildhistory"
3274 BUILDHISTORY_COMMIT = "1"
3275 </literallayout>
3276 For information on Build History, see the
3277 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
3278 section in the Yocto Project Reference Manual.
3279 </para>
3280
3281 <note>
3282 <para>The OpenEmbedded build system does not maintain
3283 <filename>PR</filename> information as part of the
3284 shared state (sstate) packages.
3285 If you maintain an sstate feed, its expected that either
3286 all your building systems that contribute to the sstate
3287 feed use a shared PR Service, or you do not run a PR
3288 Service on any of your building systems.
3289 Having some systems use a PR Service while others do
3290 not leads to obvious problems.</para>
3291 <para>For more information on shared state, see the
3292 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
3293 section in the Yocto Project Reference Manual.</para>
3294 </note>
3295 </section>
3296
3297 <section id='manually-bumping-pr'>
3298 <title>Manually Bumping PR</title>
3299
3300 <para>
3301 The alternative to setting up a PR Service is to manually
3302 bump the
3303 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
3304 variable.
3305 </para>
3306
3307 <para>
3308 If a committed change results in changing the package output,
3309 then the value of the PR variable needs to be increased
3310 (or "bumped") as part of that commit.
3311 For new recipes you should add the <filename>PR</filename>
3312 variable and set its initial value equal to "r0", which is the default.
3313 Even though the default value is "r0", the practice of adding it to a new recipe makes
3314 it harder to forget to bump the variable when you make changes
3315 to the recipe in future.
3316 </para>
3317
3318 <para>
3319 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
3320 you can also use the
3321 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
3322 variable to ensure that
3323 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
3324 <filename>.inc</filename> file itself is changed.
3325 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
3326 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
3327 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
3328 If the <filename>.inc</filename> file is changed then its
3329 <filename>INC_PR</filename> should be incremented.
3330 </para>
3331
3332 <para>
3333 When upgrading the version of a package, assuming the
3334 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
3335 changes, the <filename>PR</filename> variable should be
3336 reset to "r0" (or "$(INC_PR).0" if you are using
3337 <filename>INC_PR</filename>).
3338 </para>
3339
3340 <para>
3341 Usually, version increases occur only to packages.
3342 However, if for some reason <filename>PV</filename> changes but does not
3343 increase, you can increase the
3344 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
3345 variable (Package Epoch).
3346 The <filename>PE</filename> variable defaults to "0".
3347 </para>
3348
3349 <para>
3350 Version numbering strives to follow the
3351 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
3352 Debian Version Field Policy Guidelines</ulink>.
3353 These guidelines define how versions are compared and what "increasing" a version means.
3354 </para>
3355 </section>
3356 </section>
3357
3358 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
3359 <title>Handling a Package Name Alias</title>
3360 <para>
3361 Sometimes a package name you are using might exist under an alias or as a similarly named
3362 package in a different distribution.
3363 The OpenEmbedded build system implements a <filename>distro_check</filename>
3364 task that automatically connects to major distributions
3365 and checks for these situations.
3366 If the package exists under a different name in a different distribution, you get a
3367 <filename>distro_check</filename> mismatch.
3368 You can resolve this problem by defining a per-distro recipe name alias using the
3369 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
3370 variable.
3371 </para>
3372
3373 <para>
3374 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
3375 variable:
3376 <literallayout class='monospaced'>
3377 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
3378 distro2=package_name_alias2 \
3379 distro3=package_name_alias3 \
3380 ..."
3381 </literallayout>
3382 </para>
3383
3384 <para>
3385 If you have more than one distribution alias, separate them with a space.
3386 Note that the build system currently automatically checks the
3387 Fedora, OpenSUSE, Debian, Ubuntu,
3388 and Mandriva distributions for source package recipes without having to specify them
3389 using the <filename>DISTRO_PN_ALIAS</filename> variable.
3390 For example, the following command generates a report that lists the Linux distributions
3391 that include the sources for each of the recipes.
3392 <literallayout class='monospaced'>
3393 $ bitbake world -f -c distro_check
3394 </literallayout>
3395 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
3396 file found in the
3397 <link linkend='source-directory'>Source Directory</link>.
3398 </para>
3399 </section>
3400
3401 <section id='handling-optional-module-packaging'>
3402 <title>Handling Optional Module Packaging</title>
3403
3404 <para>
3405 Many pieces of software split functionality into optional
3406 modules (or plug-ins) and the plug-ins that are built
3407 might depend on configuration options.
3408 To avoid having to duplicate the logic that determines what
3409 modules are available in your recipe or to avoid having
3410 to package each module by hand, the OpenEmbedded build system
3411 provides functionality to handle module packaging dynamically.
3412 </para>
3413
3414 <para>
3415 To handle optional module packaging, you need to do two things:
3416 <itemizedlist>
3417 <listitem><para>Ensure the module packaging is actually
3418 done</para></listitem>
3419 <listitem><para>Ensure that any dependencies on optional
3420 modules from other recipes are satisfied by your recipe
3421 </para></listitem>
3422 </itemizedlist>
3423 </para>
3424
3425 <section id='making-sure-the-packaging-is-done'>
3426 <title>Making Sure the Packaging is Done</title>
3427
3428 <para>
3429 To ensure the module packaging actually gets done, you use
3430 the <filename>do_split_packages</filename> function within
3431 the <filename>populate_packages</filename> Python function
3432 in your recipe.
3433 The <filename>do_split_packages</filename> function
3434 searches for a pattern of files or directories under a
3435 specified path and creates a package for each one it finds
3436 by appending to the
3437 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
3438 variable and setting the appropriate values for
3439 <filename>FILES_packagename</filename>,
3440 <filename>RDEPENDS_packagename</filename>,
3441 <filename>DESCRIPTION_packagename</filename>, and so forth.
3442 Here is an example from the <filename>lighttpd</filename>
3443 recipe:
3444 <literallayout class='monospaced'>
3445 python populate_packages_prepend () {
3446 lighttpd_libdir = d.expand('${libdir}')
3447 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
3448 'lighttpd-module-%s', 'Lighttpd module for %s',
3449 extra_depends='')
3450 }
3451 </literallayout>
3452 The previous example specifies a number of things in the
3453 call to <filename>do_split_packages</filename>.
3454 <itemizedlist>
3455 <listitem><para>A directory within the files installed
3456 by your recipe through <filename>do_install</filename>
3457 in which to search.</para></listitem>
3458 <listitem><para>A regular expression to match module
3459 files in that directory.
3460 In the example, note the parentheses () that mark
3461 the part of the expression from which the module
3462 name should be derived.</para></listitem>
3463 <listitem><para>A pattern to use for the package names.
3464 </para></listitem>
3465 <listitem><para>A description for each package.
3466 </para></listitem>
3467 <listitem><para>An empty string for
3468 <filename>extra_depends</filename>, which disables
3469 the default dependency on the main
3470 <filename>lighttpd</filename> package.
3471 Thus, if a file in <filename>${libdir}</filename>
3472 called <filename>mod_alias.so</filename> is found,
3473 a package called <filename>lighttpd-module-alias</filename>
3474 is created for it and the
3475 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
3476 is set to "Lighttpd module for alias".</para></listitem>
3477 </itemizedlist>
3478 </para>
3479
3480 <para>
3481 Often, packaging modules is as simple as the previous
3482 example.
3483 However, more advanced options exist that you can use
3484 within <filename>do_split_packages</filename> to modify its
3485 behavior.
3486 And, if you need to, you can add more logic by specifying
3487 a hook function that is called for each package.
3488 It is also perfectly acceptable to call
3489 <filename>do_split_packages</filename> multiple times if
3490 you have more than one set of modules to package.
3491 </para>
3492
3493 <para>
3494 For more examples that show how to use
3495 <filename>do_split_packages</filename>, see the
3496 <filename>connman.inc</filename> file in the
3497 <filename>meta/recipes-connectivity/connman/</filename>
3498 directory of the <filename>poky</filename>
3499 <link linkend='yocto-project-repositories'>source repository</link>.
3500 You can also find examples in
3501 <filename>meta/classes/kernel.bbclass</filename>.
3502 </para>
3503
3504 <para>
3505 Following is a reference that shows
3506 <filename>do_split_packages</filename> mandatory and
3507 optional arguments:
3508 <literallayout class='monospaced'>
3509 Mandatory arguments
3510
3511 root
3512 The path in which to search
3513 file_regex
3514 Regular expression to match searched files.
3515 Use parentheses () to mark the part of this
3516 expression that should be used to derive the
3517 module name (to be substituted where %s is
3518 used in other function arguments as noted below)
3519 output_pattern
3520 Pattern to use for the package names. Must
3521 include %s.
3522 description
3523 Description to set for each package. Must
3524 include %s.
3525
3526 Optional arguments
3527
3528 postinst
3529 Postinstall script to use for all packages
3530 (as a string)
3531 recursive
3532 True to perform a recursive search - default
3533 False
3534 hook
3535 A hook function to be called for every match.
3536 The function will be called with the following
3537 arguments (in the order listed):
3538
3539 f
3540 Full path to the file/directory match
3541 pkg
3542 The package name
3543 file_regex
3544 As above
3545 output_pattern
3546 As above
3547 modulename
3548 The module name derived using file_regex
3549
3550 extra_depends
3551 Extra runtime dependencies (RDEPENDS) to be
3552 set for all packages. The default value of None
3553 causes a dependency on the main package
3554 (${PN}) - if you do not want this, pass empty
3555 string '' for this parameter.
3556 aux_files_pattern
3557 Extra item(s) to be added to FILES for each
3558 package. Can be a single string item or a list
3559 of strings for multiple items. Must include %s.
3560 postrm
3561 postrm script to use for all packages (as a
3562 string)
3563 allow_dirs
3564 True to allow directories to be matched -
3565 default False
3566 prepend
3567 If True, prepend created packages to PACKAGES
3568 instead of the default False which appends them
3569 match_path
3570 match file_regex on the whole relative path to
3571 the root rather than just the file name
3572 aux_files_pattern_verbatim
3573 Extra item(s) to be added to FILES for each
3574 package, using the actual derived module name
3575 rather than converting it to something legal
3576 for a package name. Can be a single string item
3577 or a list of strings for multiple items. Must
3578 include %s.
3579 allow_links
3580 True to allow symlinks to be matched - default
3581 False
3582 </literallayout>
3583 </para>
3584 </section>
3585
3586 <section id='satisfying-dependencies'>
3587 <title>Satisfying Dependencies</title>
3588
3589 <para>
3590 The second part for handling optional module packaging
3591 is to ensure that any dependencies on optional modules
3592 from other recipes are satisfied by your recipe.
3593 You can be sure these dependencies are satisfied by
3594 using the
3595 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
3596 Here is an example that continues with the
3597 <filename>lighttpd</filename> recipe shown earlier:
3598 <literallayout class='monospaced'>
3599 PACKAGES_DYNAMIC = "lighttpd-module-.*"
3600 </literallayout>
3601 The name specified in the regular expression can of
3602 course be anything.
3603 In this example, it is <filename>lighttpd-module-</filename>
3604 and is specified as the prefix to ensure that any
3605 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
3606 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
3607 on a package name starting with the prefix are satisfied
3608 during build time.
3609 If you are using <filename>do_split_packages</filename>
3610 as described in the previous section, the value you put in
3611 <filename>PACKAGES_DYNAMIC</filename> should correspond to
3612 the name pattern specified in the call to
3613 <filename>do_split_packages</filename>.
3614 </para>
3615 </section>
3616 </section>
3617
3618 <section id='using-runtime-package-management'>
3619 <title>Using Runtime Package Management</title>
3620
3621 <para>
3622 During a build, BitBake always transforms a recipe into one or
3623 more packages.
3624 For example, BitBake takes the <filename>bash</filename> recipe
3625 and currently produces the <filename>bash-dbg</filename>,
3626 <filename>bash-staticdev</filename>,
3627 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
3628 <filename>bash-locale</filename>, and
3629 <filename>bash</filename> packages.
3630 Not all generated packages are included in an image.
3631 </para>
3632
3633 <para>
3634 In several situations, you might need to update, add, remove,
3635 or query the packages on a target device at runtime
3636 (i.e. without having to generate a new image).
3637 Examples of such situations include:
3638 <itemizedlist>
3639 <listitem><para>
3640 You want to provide in-the-field updates to deployed
3641 devices (e.g. security updates).
3642 </para></listitem>
3643 <listitem><para>
3644 You want to have a fast turn-around development cycle
3645 for one or more applications that run on your device.
3646 </para></listitem>
3647 <listitem><para>
3648 You want to temporarily install the "debug" packages
3649 of various applications on your device so that
3650 debugging can be greatly improved by allowing
3651 access to symbols and source debugging.
3652 </para></listitem>
3653 <listitem><para>
3654 You want to deploy a more minimal package selection of
3655 your device but allow in-the-field updates to add a
3656 larger selection for customization.
3657 </para></listitem>
3658 </itemizedlist>
3659 </para>
3660
3661 <para>
3662 In all these situations, you have something similar to a more
3663 traditional Linux distribution in that in-field devices
3664 are able to receive pre-compiled packages from a server for
3665 installation or update.
3666 Being able to install these packages on a running,
3667 in-field device is what is termed "runtime package
3668 management".
3669 </para>
3670
3671 <para>
3672 In order to use runtime package management, you
3673 need a host/server machine that serves up the pre-compiled
3674 packages plus the required metadata.
3675 You also need package manipulation tools on the target.
3676 The build machine is a likely candidate to act as the server.
3677 However, that machine does not necessarily have to be the
3678 package server.
3679 The build machine could push its artifacts to another machine
3680 that acts as the server (e.g. Internet-facing).
3681 </para>
3682
3683 <para>
3684 A simple build that targets just one device produces
3685 more than one package database.
3686 In other words, the packages produced by a build are separated
3687 out into a couple of different package groupings based on
3688 criteria such as the target's CPU architecture, the target
3689 board, or the C library used on the target.
3690 For example, a build targeting the <filename>qemuarm</filename>
3691 device produces the following three package databases:
3692 <filename>all</filename>, <filename>armv5te</filename>, and
3693 <filename>qemuarm</filename>.
3694 If you wanted your <filename>qemuarm</filename> device to be
3695 aware of all the packages that were available to it,
3696 you would need to point it to each of these databases
3697 individually.
3698 In a similar way, a traditional Linux distribution usually is
3699 configured to be aware of a number of software repositories
3700 from which it retrieves packages.
3701 </para>
3702
3703 <para>
3704 Using runtime package management is completely optional and
3705 not required for a successful build or deployment in any
3706 way.
3707 But if you want to make use of runtime package management,
3708 you need to do a couple things above and beyond the basics.
3709 The remainder of this section describes what you need to do.
3710 </para>
3711
3712 <section id='runtime-package-management-build'>
3713 <title>Build Considerations</title>
3714
3715 <para>
3716 This section describes build considerations that you need
3717 to be aware of in order to provide support for runtime
3718 package management.
3719 </para>
3720
3721 <para>
3722 When BitBake generates packages it needs to know
3723 what format(s) to use.
3724 In your configuration, you use the
3725 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
3726 variable to specify the format.
3727 <note>
3728 You can choose to have more than one format but you must
3729 provide at least one.
3730 </note>
3731 </para>
3732
3733 <para>
3734 If you would like your image to start off with a basic
3735 package database of the packages in your current build
3736 as well as have the relevant tools available on the
3737 target for runtime package management, you can include
3738 "package-management" in the
3739 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
3740 variable.
3741 Including "package-management" in this
3742 configuration variable ensures that when the image
3743 is assembled for your target, the image includes
3744 the currently-known package databases as well as
3745 the target-specific tools required for runtime
3746 package management to be performed on the target.
3747 However, this is not strictly necessary.
3748 You could start your image off without any databases
3749 but only include the required on-target package
3750 tool(s).
3751 As an example, you could include "opkg" in your
3752 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
3753 variable if you are using the IPK package format.
3754 You can then initialize your target's package database(s)
3755 later once your image is up and running.
3756 </para>
3757
3758 <para>
3759 Whenever you perform any sort of build step that can
3760 potentially generate a package or modify an existing
3761 package, it is always a good idea to re-generate the
3762 package index with:
3763 <literallayout class='monospaced'>
3764 $ bitbake package-index
3765 </literallayout>
3766 Realize that it is not sufficient to simply do the
3767 following:
3768 <literallayout class='monospaced'>
3769 $ bitbake &lt;some-package&gt; package-index
3770 </literallayout>
3771 This is because BitBake does not properly schedule the
3772 <filename>package-index</filename> target fully after any
3773 other target has completed.
3774 Thus, be sure to run the package update step separately.
3775 </para>
3776
3777 <para>
3778 As described below in the
3779 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
3780 section, if you are using IPK as your package format, you
3781 can make use of the
3782 <filename>distro-feed-configs</filename> recipe provided
3783 by <filename>meta-oe</filename> in order to configure your
3784 target to use your IPK databases.
3785 </para>
3786
3787 <para>
3788 When your build is complete, your packages reside in the
3789 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
3790 directory.
3791 For example, if <filename>${TMPDIR}</filename>
3792 is <filename>tmp</filename> and your selected package type
3793 is IPK, then your IPK packages are available in
3794 <filename>tmp/deploy/ipk</filename>.
3795 </para>
3796 </section>
3797
3798 <section id='runtime-package-management-server'>
3799 <title>Host or Server Machine Setup</title>
3800
3801 <para>
3802 Typically, packages are served from a server using
3803 HTTP.
3804 However, other protocols are possible.
3805 If you want to use HTTP, then setup and configure a
3806 web server, such as Apache 2 or lighttpd, on the machine
3807 serving the packages.
3808 </para>
3809
3810 <para>
3811 As previously mentioned, the build machine can act as the
3812 package server.
3813 In the following sections that describe server machine
3814 setups, the build machine is assumed to also be the server.
3815 </para>
3816
3817 <section id='package-server-apache'>
3818 <title>Serving Packages via Apache 2</title>
3819
3820 <para>
3821 This example assumes you are using the Apache 2
3822 server:
3823 <orderedlist>
3824 <listitem><para>
3825 Add the directory to your Apache
3826 configuration, which you can find at
3827 <filename>/etc/httpd/conf/httpd.conf</filename>.
3828 Use commands similar to these on the
3829 development system.
3830 These example commands assume a top-level
3831 <link linkend='source-directory'>Source Directory</link>
3832 named <filename>poky</filename> in your home
3833 directory.
3834 The example also assumes an RPM package type.
3835 If you are using a different package type, such
3836 as IPK, use "ipk" in the pathnames:
3837 <literallayout class='monospaced'>
3838 &lt;VirtualHost *:80&gt;
3839 ....
3840 Alias /rpm ~/poky/build/tmp/deploy/rpm
3841 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
3842 Options +Indexes
3843 &lt;/Directory&gt;
3844 &lt;/VirtualHost&gt;
3845 </literallayout></para></listitem>
3846 <listitem><para>
3847 Reload the Apache configuration as described
3848 in this step.
3849 For all commands, be sure you have root
3850 privileges.
3851 </para>
3852
3853 <para>
3854 If your development system is using Fedora or
3855 CentOS, use the following:
3856 <literallayout class='monospaced'>
3857 # service httpd reload
3858 </literallayout>
3859 For Ubuntu and Debian, use the following:
3860 <literallayout class='monospaced'>
3861 # /etc/init.d/apache2 reload
3862 </literallayout>
3863 For OpenSUSE, use the following:
3864 <literallayout class='monospaced'>
3865 # /etc/init.d/apache2 reload
3866 </literallayout></para></listitem>
3867 <listitem><para>
3868 If you are using Security-Enhanced Linux
3869 (SELinux), you need to label the files as
3870 being accessible through Apache.
3871 Use the following command from the development
3872 host.
3873 This example assumes RPM package types:
3874 <literallayout class='monospaced'>
3875 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
3876 </literallayout></para></listitem>
3877 </orderedlist>
3878 </para>
3879 </section>
3880
3881 <section id='package-server-lighttpd'>
3882 <title>Serving Packages via lighttpd</title>
3883
3884 <para>
3885 If you are using lighttpd, all you need
3886 to do is to provide a link from your
3887 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
3888 directory to lighttpd's document-root.
3889 You can determine the specifics of your lighttpd
3890 installation by looking through its configuration file,
3891 which is usually found at:
3892 <filename>/etc/lighttpd/lighttpd.conf</filename>.
3893 </para>
3894
3895 <para>
3896 For example, if you are using IPK, lighttpd's
3897 document-root is set to
3898 <filename>/var/www/lighttpd</filename>, and you had
3899 packages for a target named "BOARD",
3900 then you might create a link from your build location
3901 to lighttpd's document-root as follows:
3902 <literallayout class='monospaced'>
3903 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
3904 </literallayout>
3905 </para>
3906
3907 <para>
3908 At this point, you need to start the lighttpd server.
3909 The method used to start the server varies by
3910 distribution.
3911 However, one basic method that starts it by hand is:
3912 <literallayout class='monospaced'>
3913 # lighttpd -f /etc/lighttpd/lighttpd.conf
3914 </literallayout>
3915 </para>
3916 </section>
3917 </section>
3918
3919 <section id='runtime-package-management-target'>
3920 <title>Target Setup</title>
3921
3922 <para>
3923 Setting up the target differs depending on the
3924 package management system.
3925 This section provides information for RPM and IPK.
3926 </para>
3927
3928 <section id='runtime-package-management-target-rpm'>
3929 <title>Using RPM</title>
3930
3931 <para>
3932 The application for performing runtime package
3933 management of RPM packages on the target is called
3934 <filename>smart</filename>.
3935 </para>
3936
3937 <para>
3938 On the target machine, you need to inform
3939 <filename>smart</filename> of every package database
3940 you want to use.
3941 As an example, suppose your target device can use the
3942 following three package databases from a server named
3943 <filename>server.name</filename>:
3944 <filename>all</filename>, <filename>i586</filename>,
3945 and <filename>qemux86</filename>.
3946 Given this example, issue the following commands on the
3947 target:
3948 <literallayout class='monospaced'>
3949 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
3950 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
3951 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
3952 </literallayout>
3953 Also from the target machine, fetch the repository
3954 information using this command:
3955 <literallayout class='monospaced'>
3956 # smart update
3957 </literallayout>
3958 You can now use the <filename>smart query</filename>
3959 and <filename>smart install</filename> commands to
3960 find and install packages from the repositories.
3961 </para>
3962 </section>
3963
3964 <section id='runtime-package-management-target-ipk'>
3965 <title>Using IPK</title>
3966
3967 <para>
3968 The application for performing runtime package
3969 management of IPK packages on the target is called
3970 <filename>opkg</filename>.
3971 </para>
3972
3973 <para>
3974 In order to inform <filename>opkg</filename> of the
3975 package databases you want to use, simply create one
3976 or more <filename>*.conf</filename> files in the
3977 <filename>/etc/opkg</filename> directory on the target.
3978 The <filename>opkg</filename> application uses them
3979 to find its available package databases.
3980 As an example, suppose you configured your HTTP server
3981 on your machine named
3982 <filename>www.mysite.com</filename> to serve files
3983 from a <filename>BOARD-dir</filename> directory under
3984 its document-root.
3985 In this case, you might create a configuration
3986 file on the target called
3987 <filename>/etc/opkg/base-feeds.conf</filename> that
3988 contains:
3989 <literallayout class='monospaced'>
3990 src/gz all http://www.mysite.com/BOARD-dir/all
3991 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
3992 src/gz beagleboard http://www.mysite.com/BOARD-dir/beagleboard
3993 </literallayout>
3994 </para>
3995
3996 <para>
3997 As a way of making it easier to generate and make
3998 these IPK configuration files available on your
3999 target, the <filename>meta-oe</filename> layer
4000 provides a recipe called
4001 <filename>distro-feed-configs</filename>, which
4002 provides a package by the same name.
4003 When you include this package into your image, it will
4004 automatically generate and include a set of
4005 <filename>*.conf</filename> files in the image's
4006 <filename>/etc/opkg</filename> directory that will
4007 provide your target's <filename>opkg</filename>
4008 tool with any and all package databases your build will
4009 generate.
4010 The only catch is that this recipe cannot possibly
4011 imagine your server's DNS name/IP address.
4012 Consequently, somewhere in your configuration you need
4013 to set a variable called
4014 <filename>DISTRO_FEED_URI</filename> to point
4015 to your server and the location within the
4016 document-root that contains the databases.
4017 For example: if you are serving your packages over HTTP,
4018 your server's IP address is 192.168.7.1, and your
4019 databases are located in a directory called
4020 <filename>BOARD-dir</filename> underneath your HTTP
4021 server's document-root, you need to set
4022 <filename>DISTRO_FEED_URI</filename> to
4023 <filename>http://192.168.7.1/BOARD-dir</filename>.
4024 </para>
4025
4026 <para>
4027 On the target machine, fetch (or refresh) the
4028 repository information using this command:
4029 <literallayout class='monospaced'>
4030 # opkg update
4031 </literallayout>
4032 You can now use the <filename>opkg list</filename> and
4033 <filename>opkg install</filename> commands to find and
4034 install packages from the repositories.
4035 </para>
4036 </section>
4037 </section>
4038 </section>
4039
4040 <section id='testing-packages-with-ptest'>
4041 <title>Testing Packages With ptest</title>
4042
4043 <para>
4044 A Package Test (ptest) runs tests against packages built
4045 by the OpenEmbedded build system on the target machine.
4046 A ptest contains at least two items: the actual test, and
4047 a shell script (<filename>run-ptest</filename>) that starts
4048 the test.
4049 The shell script that starts the test must not contain
4050 the actual test, the script only starts it.
4051 On the other hand, the test can be anything from a simple
4052 shell script that runs a binary and checks the output to
4053 an elaborate system of test binaries and data files.
4054 </para>
4055
4056 <para>
4057 The test generates output in the format used by
4058 Automake:
4059 <literallayout class='monospaced'>
4060 &lt;result&gt;: &lt;testname&gt;
4061 </literallayout>
4062 where the result can be <filename>PASS</filename>,
4063 <filename>FAIL</filename>, or <filename>SKIP</filename>,
4064 and the testname can be any identifying string.
4065 </para>
4066
4067 <note>
4068 With this release of the Yocto Project, three recipes exist
4069 that are "ptest-enabled": <filename>bash</filename>,
4070 <filename>glib-2.0</filename>, and
4071 <filename>dbus</filename>.
4072 These three recipes are Autotool-enabled.
4073 </note>
4074
4075 <section id='adding-ptest-to-your-build'>
4076 <title>Adding ptest to Your Build</title>
4077
4078 <para>
4079 To add package testing to your build, add the
4080 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4081 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
4082 variables to your <filename>local.conf</filename> file,
4083 which is found in the
4084 <link linkend='build-directory'>Build Directory</link>:
4085 <literallayout class='monospaced'>
4086 DISTRO_FEATURES_append = " ptest"
4087 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
4088 </literallayout>
4089 Once your build is complete, the ptest files are installed
4090 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
4091 directory within the image, where
4092 <filename>&lt;package&gt;</filename> is the name of the
4093 package.
4094 </para>
4095 </section>
4096
4097 <section id='running-ptest'>
4098 <title>Running ptest</title>
4099
4100 <para>
4101 The <filename>ptest-runner</filename> package installs a
4102 shell script that loops through all installed ptest test
4103 suites and runs them in sequence.
4104 Consequently, you might want to add this package to
4105 your image.
4106 </para>
4107 </section>
4108
4109 <section id='getting-your-package-ready'>
4110 <title>Getting Your Package Ready</title>
4111
4112 <para>
4113 In order to enable a recipe to run installed ptests
4114 on target hardware,
4115 you need to prepare the recipes that build the packages
4116 you want to test.
4117 Here is what you have to do for each recipe:
4118 <itemizedlist>
4119 <listitem><para><emphasis>Be sure the recipe
4120 inherits ptest:</emphasis>
4121 Include the following line in each recipe:
4122 <literallayout class='monospaced'>
4123 inherit ptest
4124 </literallayout>
4125 </para></listitem>
4126 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
4127 This script starts your test.
4128 Locate the script where you will refer to it
4129 using
4130 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
4131 Here is an example that starts a test for
4132 <filename>dbus</filename>:
4133 <literallayout class='monospaced'>
4134 #!/bin/sh
4135 cd test
4136 make -k runtest-TESTS
4137 </literallayout>
4138 </para></listitem>
4139 <listitem><para><emphasis>Ensure dependencies are
4140 met:</emphasis>
4141 If the test adds build or runtime dependencies
4142 that normally do not exist for the package
4143 (such as requiring "make" to run the test suite),
4144 use the
4145 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
4146 and
4147 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
4148 variables in your recipe in order for the package
4149 to meet the dependencies.
4150 Here is an example where the package has a runtime
4151 dependency on "make":
4152 <literallayout class='monospaced'>
4153 RDEPENDS_${PN}-ptest += "make"
4154 </literallayout>
4155 </para></listitem>
4156 <listitem><para><emphasis>Add a function to build the
4157 test suite:</emphasis>
4158 Not many packages support cross-compilation of
4159 their test suites.
4160 Consequently, you usually need to add a
4161 cross-compilation function to the package.
4162 </para>
4163 <para>Many packages based on Automake compile and
4164 run the test suite by using a single command
4165 such as <filename>make check</filename>.
4166 However, the native <filename>make check</filename>
4167 builds and runs on the same computer, while
4168 cross-compiling requires that the package is built
4169 on the host but executed on the target.
4170 The built version of Automake that ships with the
4171 Yocto Project includes a patch that separates
4172 building and execution.
4173 Consequently, packages that use the unaltered,
4174 patched version of <filename>make check</filename>
4175 automatically cross-compiles.</para>
4176 <para>However, you still must add a
4177 <filename>do_compile_ptest</filename> function to
4178 build the test suite.
4179 Add a function similar to the following to your
4180 recipe:
4181 <literallayout class='monospaced'>
4182 do_compile_ptest() {
4183 oe_runmake buildtest-TESTS
4184 }
4185 </literallayout>
4186 </para></listitem>
4187 <listitem><para><emphasis>Ensure special configurations
4188 are set:</emphasis>
4189 If the package requires special configurations
4190 prior to compiling the test code, you must
4191 insert a <filename>do_configure_ptest</filename>
4192 function into the recipe.
4193 </para></listitem>
4194 <listitem><para><emphasis>Install the test
4195 suite:</emphasis>
4196 The <filename>ptest.bbclass</filename> class
4197 automatically copies the file
4198 <filename>run-ptest</filename> to the target and
4199 then runs make <filename>install-ptest</filename>
4200 to run the tests.
4201 If this is not enough, you need to create a
4202 <filename>do_install_ptest</filename> function and
4203 make sure it gets called after the
4204 "make install-ptest" completes.
4205 </para></listitem>
4206 </itemizedlist>
4207 </para>
4208 </section>
4209 </section>
4210 </section>
4211
4212 <section id="building-software-from-an-external-source">
4213 <title>Building Software from an External Source</title>
4214
4215 <para>
4216 By default, the OpenEmbedded build system uses the
4217 <link linkend='build-directory'>Build Directory</link> to
4218 build source code.
4219 The build process involves fetching the source files, unpacking
4220 them, and then patching them if necessary before the build takes
4221 place.
4222 </para>
4223
4224 <para>
4225 Situations exist where you might want to build software from source
4226 files that are external to and thus outside of the
4227 OpenEmbedded build system.
4228 For example, suppose you have a project that includes a new BSP with
4229 a heavily customized kernel.
4230 And, you want to minimize exposing the build system to the
4231 development team so that they can focus on their project and
4232 maintain everyone's workflow as much as possible.
4233 In this case, you want a kernel source directory on the development
4234 machine where the development occurs.
4235 You want the recipe's
4236 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
4237 variable to point to the external directory and use it as is, not
4238 copy it.
4239 </para>
4240
4241 <para>
4242 To build from software that comes from an external source, all you
4243 need to do is inherit
4244 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>
4245 and then set the
4246 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
4247 variable to point to your external source code.
4248 Here are the statements to put in your
4249 <filename>local.conf</filename> file:
4250 <literallayout class='monospaced'>
4251 INHERIT += "externalsrc"
4252 EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
4253 </literallayout>
4254 </para>
4255
4256 <para>
4257 By default, <filename>externalsrc.bbclass</filename> builds
4258 the source code in a directory separate from the external source
4259 directory as specified by
4260 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
4261 If you need to have the source built in the same directory in
4262 which it resides, or some other nominated directory, you can set
4263 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
4264 to point to that directory:
4265 <literallayout class='monospaced'>
4266 EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
4267 </literallayout>
4268 </para>
4269 </section>
4270
4271 <section id="selecting-an-initialization-manager">
4272 <title>Selecting an Initialization Manager</title>
4273
4274 <para>
4275 By default, the Yocto Project uses
4276 <filename>SysVinit</filename> as the initialization manager.
4277 However, support also exists for <filename>systemd</filename>,
4278 which is a full replacement for <filename>init</filename> with
4279 parallel starting of services, reduced shell overhead and other
4280 features that are used by many distributions.
4281 </para>
4282
4283 <para>
4284 If you want to use <filename>sysvinit</filename>, you do
4285 not have to do anything.
4286 But, if you want to use <filename>systemd</filename>, you must
4287 take some steps as described in the following sections.
4288 </para>
4289
4290<!--
4291 <note>
4292 It is recommended that you create your own distribution configuration
4293 file to hold these settings instead of using your
4294 <filename>local.conf</filename> file.
4295 For information on creating your own distribution, see the
4296 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
4297 section.
4298 </note>
4299-->
4300
4301 <section id='using-systemd-exclusively'>
4302 <title>Using systemd Exclusively</title>
4303
4304 <para>
4305 Set the following variables in your distribution configuration
4306 file as follows:
4307 <literallayout class='monospaced'>
4308 DISTRO_FEATURES_append = " systemd"
4309 VIRTUAL-RUNTIME_init_manager = "systemd"
4310 </literallayout>
4311 You can also prevent the <filename>sysvinit</filename>
4312 distribution feature from
4313 being automatically enabled as follows:
4314 <literallayout class='monospaced'>
4315 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
4316 </literallayout>
4317 Doing so removes any redundant <filename>sysvinit</filename>
4318 scripts.
4319 </para>
4320
4321 <para>
4322 For information on the backfill variable, see
4323 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>
4324 in the Yocto Project Reference Manual.
4325 </para>
4326 </section>
4327
4328 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
4329 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
4330
4331 <para>
4332 Set the following variables in your distribution configuration
4333 file as follows:
4334 <literallayout class='monospaced'>
4335 DISTRO_FEATURES_append = " systemd"
4336 VIRTUAL-RUNTIME_init_manager = "systemd"
4337 </literallayout>
4338 Doing so causes your main image to use the
4339 <filename>packagegroup-core-boot.bb</filename> recipe and
4340 <filename>systemd</filename>.
4341 The rescue/minimal image cannot use this package group.
4342 However, it can install <filename>sysvinit</filename>
4343 and the appropriate packages will have support for both
4344 <filename>systemd</filename> and <filename>sysvinit</filename>.
4345 </para>
4346 </section>
4347 </section>
4348
4349 <section id='excluding-recipes-from-the-build'>
4350 <title>Excluding Recipes From the Build</title>
4351
4352 <para>
4353 You might find that there are groups of recipes or append files
4354 that you want to filter out of the build process.
4355 Usually, this is not necessary.
4356 However, on rare occasions where you might want to use a
4357 layer but exclude parts that are causing problems, such
4358 as introducing a different version of a recipe, you can
4359 use
4360 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink>
4361 to exclude the recipe.
4362 </para>
4363
4364 <para>
4365 It is possible to filter or mask out <filename>.bb</filename> and
4366 <filename>.bbappend</filename> files.
4367 You can do this by providing an expression with the
4368 <filename>BBMASK</filename> variable.
4369 Here is an example:
4370 <literallayout class='monospaced'>
4371 BBMASK = "/meta-mymachine/recipes-maybe/"
4372 </literallayout>
4373 Here, all <filename>.bb</filename> and
4374 <filename>.bbappend</filename> files in the directory that match
4375 the expression are ignored during the build process.
4376 </para>
4377
4378 <note>
4379 The value you provide is passed to Python's regular expression
4380 compiler.
4381 The expression is compared against the full paths to the files.
4382 For complete syntax information, see Python's documentation at
4383 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
4384 </note>
4385 </section>
4386
4387 <section id="platdev-appdev-srcrev">
4388 <title>Using an External SCM</title>
4389
4390 <para>
4391 If you're working on a recipe that pulls from an external Source Code Manager (SCM), it
4392 is possible to have the OpenEmbedded build system notice new recipe changes added to the
4393 SCM and then build the resulting package that depends on the new recipes by using the latest
4394 versions.
4395 This only works for SCMs from which it is possible to get a sensible revision number for changes.
4396 Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
4397 </para>
4398
4399 <para>
4400 To enable this behavior, simply add the following to the <filename>local.conf</filename>
4401 configuration file found in the
4402 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4403 <literallayout class='monospaced'>
4404 SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
4405 </literallayout>
4406 where <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
4407 is the name of the recipe for which you want to enable automatic source
4408 revision updating.
4409 </para>
4410 </section>
4411
4412 <section id='creating-a-read-only-root-filesystem'>
4413 <title>Creating a Read-Only Root Filesystem</title>
4414
4415 <para>
4416 Suppose, for security reasons, you need to disable
4417 your target device's root filesystem's write permissions
4418 (i.e. you need a read-only root filesystem).
4419 Or, perhaps you are running the device's operating system
4420 from a read-only storage device.
4421 For either case, you can customize your image for
4422 that behavior.
4423 </para>
4424
4425 <note>
4426 Supporting a read-only root filesystem requires that the system and
4427 applications do not try to write to the root filesystem.
4428 You must configure all parts of the target system to write
4429 elsewhere, or to gracefully fail in the event of failing to
4430 write to the root filesystem.
4431 </note>
4432
4433 <section id='creating-the-root-filesystem'>
4434 <title>Creating the Root Filesystem</title>
4435
4436 <para>
4437 To create the read-only root filesystem, simply add the
4438 <filename>read-only-rootfs</filename> feature to your image.
4439 Using either of the following statements in your
4440 image recipe or from within the
4441 <filename>local.conf</filename> file found in the
4442 <link linkend='build-directory'>Build Directory</link>
4443 causes the build system to create a read-only root filesystem:
4444 <literallayout class='monospaced'>
4445 IMAGE_FEATURES = "read-only-rootfs"
4446 </literallayout>
4447 or
4448 <literallayout class='monospaced'>
4449 EXTRA_IMAGE_FEATURES = "read-only-rootfs"
4450 </literallayout>
4451 </para>
4452
4453 <para>
4454 For more information on how to use these variables, see the
4455 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
4456 section.
4457 For information on the variables, see
4458 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4459 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
4460 </para>
4461 </section>
4462
4463 <section id='post-installation-scripts'>
4464 <title>Post-Installation Scripts</title>
4465
4466 <para>
4467 It is very important that you make sure all
4468 post-Installation (<filename>pkg_postinst</filename>) scripts
4469 for packages that are installed into the image can be run
4470 at the time when the root filesystem is created during the
4471 build on the host system.
4472 These scripts cannot attempt to run during first-boot on the
4473 target device.
4474 With the <filename>read-only-rootfs</filename> feature enabled,
4475 the build system checks during root filesystem creation to make
4476 sure all post-installation scripts succeed.
4477 If any of these scripts still need to be run after the root
4478 filesystem is created, the build immediately fails.
4479 These checks during build time ensure that the build fails
4480 rather than the target device fails later during its
4481 initial boot operation.
4482 </para>
4483
4484 <para>
4485 Most of the common post-installation scripts generated by the
4486 build system for the out-of-the-box Yocto Project are engineered
4487 so that they can run during root filesystem creation
4488 (e.g. post-installation scripts for caching fonts).
4489 However, if you create and add custom scripts, you need
4490 to be sure they can be run during file system creation.
4491 </para>
4492
4493 <para>
4494 Here are some common problems that prevent
4495 post-installation scripts from running during root filesystem
4496 creation:
4497 <itemizedlist>
4498 <listitem><para><emphasis>Not using $D in front of absolute paths:</emphasis>
4499 The build system defines
4500 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
4501 at root filesystem creation time, and
4502 it is blank when run on the target device.
4503 This implies two purposes for <filename>$D</filename>:
4504 ensuring paths are valid in both the host and target
4505 environments, and checking to determine which
4506 environment is being used as a method for taking
4507 appropriate actions.
4508 </para></listitem>
4509 <listitem><para><emphasis>Attempting to run processes that are
4510 specific to or dependent on the target
4511 architecture:</emphasis>
4512 You can work around these attempts by using native
4513 tools to accomplish the same tasks, or
4514 by alternatively running the processes under QEMU,
4515 which has the <filename>qemu_run_binary</filename>
4516 function.
4517 For more information, see the
4518 <filename>meta/classes/qemu.bbclass</filename>
4519 class in the
4520 <link linkend='source-directory'>Source Directory</link>.
4521 </para></listitem>
4522 </itemizedlist>
4523 </para>
4524 </section>
4525
4526 <section id='areas-with-write-access'>
4527 <title>Areas With Write Access</title>
4528
4529 <para>
4530 With the <filename>read-only-rootfs</filename> feature enabled,
4531 any attempt by the target to write to the root filesystem at
4532 runtime fails.
4533 Consequently, you must make sure that you configure processes
4534 and applications that attempt these types of writes do so
4535 to directories with write access (e.g.
4536 <filename>/tmp</filename> or <filename>/var/run</filename>).
4537 </para>
4538 </section>
4539 </section>
4540
4541 <section id="performing-automated-runtime-testing">
4542 <title>Performing Automated Runtime Testing</title>
4543
4544 <para>
4545 The OpenEmbedded build system makes available a series of automated
4546 tests for images to verify runtime functionality.
4547 <note>
4548 Currently, there is only support for running these tests
4549 under QEMU.
4550 </note>
4551 These tests are written in Python making use of the
4552 <filename>unittest</filename> module, and the majority of them
4553 run commands on the target system over
4554 <filename>ssh</filename>.
4555 This section describes how you set up the environment to use these
4556 tests, run available tests, and write and add your own tests.
4557 </para>
4558
4559 <section id="qemu-image-enabling-tests">
4560 <title>Enabling Tests</title>
4561
4562 <para>
4563 In order to run tests, you need to do the following:
4564 <itemizedlist>
4565 <listitem><para><emphasis>Set up to avoid interaction
4566 with <filename>sudo</filename> for networking:</emphasis>
4567 To accomplish this, you must do one of the
4568 following:
4569 <itemizedlist>
4570 <listitem><para>Add
4571 <filename>NOPASSWD</filename> for your user
4572 in <filename>/etc/sudoers</filename> either for
4573 ALL commands or just for
4574 <filename>runqemu-ifup</filename>.
4575 You must provide the full path as that can
4576 change if you are using multiple clones of the
4577 source repository.
4578 <note>
4579 On some distributions, you also need to
4580 comment out "Defaults requiretty" in
4581 <filename>/etc/sudoers</filename>.
4582 </note></para></listitem>
4583 <listitem><para>Manually configure a tap interface
4584 for your system.</para></listitem>
4585 <listitem><para>Run as root the script in
4586 <filename>scripts/runqemu-gen-tapdevs</filename>,
4587 which should generate a list of tap devices.
4588 This is the option typically chosen for
4589 Autobuilder-type environments.
4590 </para></listitem>
4591 </itemizedlist></para></listitem>
4592 <listitem><para><emphasis>Set the
4593 <filename>DISPLAY</filename> variable:</emphasis>
4594 You need to set this variable so that you have an X
4595 server available (e.g. start
4596 <filename>vncserver</filename> for a headless machine).
4597 </para></listitem>
4598 <listitem><para><emphasis>Be sure your host's firewall
4599 accepts incoming connections from
4600 192.168.7.0/24:</emphasis>
4601 Some of the tests (in particular smart tests) start a
4602 HTTP server on a random high number port, which is
4603 used to serve files to the target.
4604 The smart module serves
4605 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
4606 smart channel commands. That means your host's firewall
4607 must accept incoming connections from 192.168.7.0/24,
4608 which is the default IP range used for tap devices
4609 by <filename>runqemu</filename>.</para></listitem>
4610 </itemizedlist>
4611 </para>
4612
4613 <note>
4614 Regardless of how you initiate the tests, if you built your
4615 image using <filename>rm_work</filename>,
4616 most of the tests will fail with errors because they rely on
4617 <filename>${WORKDIR}/installed_pkgs.txt</filename>.
4618 </note>
4619 </section>
4620
4621 <section id="qemu-image-running-tests">
4622 <title>Running Tests</title>
4623
4624 <para>
4625 You can start the tests automatically or manually:
4626 <itemizedlist>
4627 <listitem><para><emphasis>Automatically Running Tests:</emphasis>
4628 To run the tests automatically after the
4629 OpenEmbedded build system successfully creates an image,
4630 first set the
4631 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
4632 variable to "1" in your <filename>local.conf</filename>
4633 file in the
4634 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4635 <literallayout class='monospaced'>
4636 TEST_IMAGE = "1"
4637 </literallayout>
4638 Next, simply build your image.
4639 If the image successfully builds, the tests will be
4640 run:
4641 <literallayout class='monospaced'>
4642 bitbake core-image-sato
4643 </literallayout></para></listitem>
4644 <listitem><para><emphasis>Manually Running Tests:</emphasis>
4645 To manually run the tests, first globally inherit
4646 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage.class</filename></ulink>
4647 by editing your <filename>local.conf</filename> file:
4648 <literallayout class='monospaced'>
4649 INHERIT += "testimage"
4650 </literallayout>
4651 Next, use BitBake to run the tests:
4652 <literallayout class='monospaced'>
4653 bitbake -c testimage &lt;image&gt;
4654 </literallayout></para></listitem>
4655 </itemizedlist>
4656 </para>
4657
4658 <para>
4659 Regardless of how you run the tests, once they start, the
4660 following happens:
4661 <itemizedlist>
4662 <listitem><para>A copy of the root filesystem is written
4663 to <filename>${WORKDIR}/testimage</filename>.
4664 </para></listitem>
4665 <listitem><para>The image is booted under QEMU using the
4666 standard <filename>runqemu</filename> script.
4667 </para></listitem>
4668 <listitem><para>A default timeout of 500 seconds occurs
4669 to allow for the boot process to reach the login prompt.
4670 You can change the timeout period by setting
4671 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
4672 in the <filename>local.conf</filename> file.
4673 </para></listitem>
4674 <listitem><para>Once the boot process is reached and the
4675 login prompt appears, the tests run.
4676 The full boot log is written to
4677 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
4678 </para></listitem>
4679 <listitem><para>Each test module loads in the order found
4680 in <filename>TEST_SUITES</filename>.
4681 You can find the full output of the commands run over
4682 <filename>ssh</filename> in
4683 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
4684 </para></listitem>
4685 <listitem><para>If no failures occur, the task running the
4686 tests ends successfully.
4687 You can find the output from the
4688 <filename>unittest</filename> in the task log at
4689 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
4690 </para></listitem>
4691 </itemizedlist>
4692 </para>
4693
4694 <para>
4695 All test files reside in
4696 <filename>meta/lib/oeqa/runtime</filename> in the
4697 <link linkend='source-directory'>Source Directory</link>.
4698 A test name maps directly to a Python module.
4699 Each test module may contain a number of individual tests.
4700 Tests are usually grouped together by the area
4701 tested (e.g tests for <filename>systemd</filename> reside in
4702 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
4703 </para>
4704
4705 <para>
4706 You can add tests to any layer provided you place them in the
4707 proper area and you extend
4708 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
4709 in the <filename>local.conf</filename> file as normal.
4710 Be sure that tests reside in
4711 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
4712 <note>
4713 Be sure that module names do not collide with module names
4714 used in the default set of test modules in
4715 <filename>meta/lib/oeqa/runtime</filename>.
4716 </note>
4717 </para>
4718
4719 <para>
4720 You can change the set of tests run by appending or overriding
4721 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
4722 variable in <filename>local.conf</filename>.
4723 Each name in <filename>TEST_SUITES</filename> represents a
4724 required test for the image.
4725 Test modules named within <filename>TEST_SUITES</filename>
4726 cannot be skipped even if a test is not suitable for an image
4727 (e.g. running the rpm tests on an image without
4728 <filename>rpm</filename>).
4729 Appending "auto" to <filename>TEST_SUITES</filename> causes the
4730 build system to try to run all tests that are suitable for the
4731 image (i.e. each test module may elect to skip itself).
4732 </para>
4733
4734 <para>
4735 The order you list tests in <filename>TEST_SUITES</filename>
4736 is important.
4737 The order influences test dependencies.
4738 Consequently, tests that depend on other tests should be added
4739 after the test on which they depend.
4740 For example, since <filename>ssh</filename> depends on the
4741 <filename>ping</filename> test, <filename>ssh</filename>
4742 needs to come after <filename>ping</filename> in the list.
4743 The test class provides no re-ordering or dependency handling.
4744 <note>
4745 Each module can have multiple classes with multiple test
4746 methods.
4747 And, Python <filename>unittest</filename> rules apply.
4748 </note>
4749 </para>
4750
4751 <para>
4752 Here are some things to keep in mind when running tests:
4753 <itemizedlist>
4754 <listitem><para>The default tests for the image are defined
4755 as:
4756 <literallayout class='monospaced'>
4757 DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
4758 </literallayout></para></listitem>
4759 <listitem><para>Add your own test to the list of the
4760 by using the following:
4761 <literallayout class='monospaced'>
4762 TEST_SUITES_append = " mytest"
4763 </literallayout></para></listitem>
4764 <listitem><para>Run a specific list of tests as follows:
4765 <literallayout class='monospaced'>
4766 TEST_SUITES = "test1 test2 test3"
4767 </literallayout>
4768 Remember, order is important.
4769 Be sure to place a test that is dependent on another test
4770 later in the order.</para></listitem>
4771 </itemizedlist>
4772 </para>
4773 </section>
4774
4775 <section id="qemu-image-writing-new-tests">
4776 <title>Writing New Tests</title>
4777
4778 <para>
4779 As mentioned previously, all new test files need to be in the
4780 proper place for the build system to find them.
4781 New tests for additional functionality outside of the core
4782 should be added to the layer that adds the functionality, in
4783 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
4784 long as
4785 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
4786 is extended in the layer's
4787 <filename>layer.conf</filename> file as normal).
4788 Just remember that filenames need to map directly to test
4789 (module) names and that you do not use module names that
4790 collide with existing core tests.
4791 </para>
4792
4793 <para>
4794 To create a new test, start by copying an existing module
4795 (e.g. <filename>syslog.py</filename> or
4796 <filename>gcc.py</filename> are good ones to use).
4797 Test modules can use code from
4798 <filename>meta/lib/oeqa/utils</filename>, which are helper
4799 classes.
4800 </para>
4801
4802 <note>
4803 Structure shell commands such that you rely on them and they
4804 return a single code for success.
4805 Be aware that sometimes you will need to parse the output.
4806 See the <filename>df.py</filename> and
4807 <filename>date.py</filename> modules for examples.
4808 </note>
4809
4810 <para>
4811 You will notice that all test classes inherit
4812 <filename>oeRuntimeTest</filename>, which is found in
4813 <filename>meta/lib/oetest.py</filename>.
4814 This base class offers some helper attributes, which are
4815 described in the following sections:
4816 </para>
4817
4818 <section id='qemu-image-writing-tests-class-methods'>
4819 <title>Class Methods</title>
4820
4821 <para>
4822 Class methods are as follows:
4823 <itemizedlist>
4824 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
4825 Returns "True" if <filename>pkg</filename> is in the
4826 installed package list of the image, which is based
4827 on
4828 <filename>${WORKDIR}/installed_pkgs.txt</filename>
4829 that is generated during the
4830 <filename>do.rootfs</filename> task.
4831 </para></listitem>
4832 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
4833 Returns "True" if the feature is in
4834 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4835 or
4836 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
4837 </para></listitem>
4838 <listitem><para><emphasis><filename>restartTarget(params)</filename>:</emphasis>
4839 Restarts the QEMU image optionally passing
4840 <filename>params</filename> to the
4841 <filename>runqemu</filename> script's
4842 <filename>qemuparams</filename> list (e.g "-m 1024" for
4843 more memory).</para></listitem>
4844 </itemizedlist>
4845 </para>
4846 </section>
4847
4848 <section id='qemu-image-writing-tests-class-attributes'>
4849 <title>Class Attributes</title>
4850
4851 <para>
4852 Class attributes are as follows:
4853 <itemizedlist>
4854 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
4855 Equals "ps -ef" if <filename>procps</filename> is
4856 installed in the image.
4857 Otherwise, <filename>pscmd</filename> equals
4858 "ps" (busybox).
4859 </para></listitem>
4860 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
4861 The called text context, which gives access to the
4862 following attributes:
4863 <itemizedlist>
4864 <listitem><para><emphasis><filename>d</filename>:</emphasis>
4865 The BitBake data store, which allows you to
4866 use stuff such as
4867 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
4868 </para></listitem>
4869 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
4870 Used internally.
4871 The tests do not need these.
4872 </para></listitem>
4873 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
4874 The absolute path to
4875 <filename>meta/lib/oeqa/runtime/files</filename>,
4876 which contains helper files for tests meant
4877 for copying on the target such as small
4878 files written in C for compilation.
4879 </para></listitem>
4880 <listitem><para><emphasis><filename>qemu</filename>:</emphasis>
4881 Provides access to the
4882 <filename>QemuRunner</filename> object,
4883 which is the class that boots the image.
4884 The <filename>qemu</filename> attribute
4885 provides the following useful attributes:
4886 <itemizedlist>
4887 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
4888 The machine's IP address.
4889 </para></listitem>
4890 <listitem><para><emphasis><filename>host_ip</filename>:</emphasis>
4891 The host IP address, which is only
4892 used by smart tests.
4893 </para></listitem>
4894 </itemizedlist></para></listitem>
4895 <listitem><para><emphasis><filename>target</filename>:</emphasis>
4896 The <filename>SSHControl</filename> object,
4897 which is used for running the following
4898 commands on the image:
4899 <itemizedlist>
4900 <listitem><para><emphasis><filename>host</filename>:</emphasis>
4901 Used internally.
4902 The tests do not use this command.
4903 </para></listitem>
4904 <listitem><para><emphasis><filename>timeout</filename>:</emphasis>
4905 A global timeout for commands run on
4906 the target for the instance of a
4907 test.
4908 The default is 300 seconds.
4909 </para></listitem>
4910 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
4911 The single, most used method.
4912 This command is a wrapper for:
4913 <filename>ssh root@host "cmd"</filename>.
4914 The command returns a tuple:
4915 (status, output), which are what
4916 their names imply - the return code
4917 of 'cmd' and whatever output
4918 it produces.
4919 The optional timeout argument
4920 represents the number of seconds the
4921 test should wait for 'cmd' to
4922 return.
4923 If the argument is "None", the
4924 test uses the default instance's
4925 timeout period, which is 300
4926 seconds.
4927 If the argument is "0", the test
4928 runs until the command returns.
4929 </para></listitem>
4930 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
4931 <filename>scp localpath root@ip:remotepath</filename>.
4932 </para></listitem>
4933 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
4934 <filename>scp root@host:remotepath localpath</filename>.
4935 </para></listitem>
4936 </itemizedlist></para></listitem>
4937 </itemizedlist></para></listitem>
4938 </itemizedlist>
4939 </para>
4940 </section>
4941
4942 <section id='qemu-image-writing-tests-instance-attributes'>
4943 <title>Instance Attributes</title>
4944
4945 <para>
4946 A single instance attribute exists, which is
4947 <filename>target</filename>.
4948 The <filename>target</filename> instance attribute is
4949 identical to the class attribute of the same name, which
4950 is described in the previous section.
4951 This attribute exists as both an instance and class
4952 attribute so tests can use
4953 <filename>self.target.run(cmd)</filename> in instance
4954 methods instead of
4955 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
4956 </para>
4957 </section>
4958 </section>
4959 </section>
4960
4961 <section id="platdev-gdb-remotedebug">
4962 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
4963
4964 <para>
4965 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
4966 It also allows you to perform post-mortem style analysis of program crashes.
4967 GDB is available as a package within the Yocto Project and is
4968 installed in SDK images by default.
4969 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
4970 in the Yocto Project Reference Manual for a description of these images.
4971 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
4972 </para>
4973
4974 <tip>
4975 For best results, install <filename>-dbg</filename> packages for
4976 the applications you are going to debug.
4977 Doing so makes extra debug symbols available that give you more
4978 meaningful output.
4979 </tip>
4980
4981 <para>
4982 Sometimes, due to memory or disk space constraints, it is not possible
4983 to use GDB directly on the remote target to debug applications.
4984 These constraints arise because GDB needs to load the debugging information and the
4985 binaries of the process being debugged.
4986 Additionally, GDB needs to perform many computations to locate information such as function
4987 names, variable names and values, stack traces and so forth - even before starting the
4988 debugging process.
4989 These extra computations place more load on the target system and can alter the
4990 characteristics of the program being debugged.
4991 </para>
4992
4993 <para>
4994 To help get past the previously mentioned constraints, you can use Gdbserver.
4995 Gdbserver runs on the remote target and does not load any debugging information
4996 from the debugged process.
4997 Instead, a GDB instance processes the debugging information that is run on a
4998 remote computer - the host GDB.
4999 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
5000 program, as well as read or write memory regions of that debugged program.
5001 All the debugging information loaded and processed as well
5002 as all the heavy debugging is done by the host GDB.
5003 Offloading these processes gives the Gdbserver running on the target a chance to remain
5004 small and fast.
5005 </para>
5006
5007 <para>
5008 Because the host GDB is responsible for loading the debugging information and
5009 for doing the necessary processing to make actual debugging happen, the
5010 user has to make sure the host can access the unstripped binaries complete
5011 with their debugging information and also be sure the target is compiled with no optimizations.
5012 The host GDB must also have local access to all the libraries used by the
5013 debugged program.
5014 Because Gdbserver does not need any local debugging information, the binaries on
5015 the remote target can remain stripped.
5016 However, the binaries must also be compiled without optimization
5017 so they match the host's binaries.
5018 </para>
5019
5020 <para>
5021 To remain consistent with GDB documentation and terminology, the binary being debugged
5022 on the remote target machine is referred to as the "inferior" binary.
5023 For documentation on GDB see the
5024 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
5025 </para>
5026
5027 <para>
5028 The remainder of this section describes the steps you need to take
5029 to debug using the GNU project debugger.
5030 </para>
5031
5032 <section id='platdev-gdb-remotedebug-setup'>
5033 <title>Set Up the Cross-Development Debugging Environment</title>
5034
5035 <para>
5036 Before you can initiate a remote debugging session, you need
5037 to be sure you have set up the cross-development environment,
5038 toolchain, and sysroot.
5039 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
5040 chapter of the Yocto Project Application Developer's Guide
5041 describes this process.
5042 Be sure you have read that chapter and have set up
5043 your environment.
5044 </para>
5045 </section>
5046
5047 <section id="platdev-gdb-remotedebug-launch-gdbserver">
5048 <title>Launch Gdbserver on the Target</title>
5049
5050 <para>
5051 Make sure Gdbserver is installed on the target.
5052 If it is not, install the package
5053 <filename>gdbserver</filename>, which needs the
5054 <filename>libthread-db1</filename> package.
5055 </para>
5056
5057 <para>
5058 Here is an example that when entered from the host
5059 connects to the target and launches Gdbserver in order to
5060 "debug" a binary named <filename>helloworld</filename>:
5061 <literallayout class='monospaced'>
5062 $ gdbserver localhost:2345 /usr/bin/helloworld
5063 </literallayout>
5064 Gdbserver should now be listening on port 2345 for debugging
5065 commands coming from a remote GDB process that is running on
5066 the host computer.
5067 Communication between Gdbserver and the host GDB are done
5068 using TCP.
5069 To use other communication protocols, please refer to the
5070 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
5071 </para>
5072 </section>
5073
5074 <section id="platdev-gdb-remotedebug-launch-gdb">
5075 <title>Launch GDB on the Host Computer</title>
5076
5077 <para>
5078 Running GDB on the host computer takes a number of stages, which
5079 this section describes.
5080 </para>
5081
5082 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
5083 <title>Build the Cross-GDB Package</title>
5084 <para>
5085 A suitable GDB cross-binary is required that runs on your
5086 host computer but also knows about the the ABI of the
5087 remote target.
5088 You can get this binary from the
5089 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
5090 Here is an example where the toolchain has been installed
5091 in the default directory
5092 <filename>/opt/poky/&DISTRO;</filename>:
5093 <literallayout class='monospaced'>
5094 /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
5095 </literallayout>
5096 where <filename>arm</filename> is the target architecture
5097 and <filename>linux-gnueabi</filename> is the target ABI.
5098 </para>
5099
5100 <para>
5101 Alternatively, you can use BitBake to build the
5102 <filename>gdb-cross</filename> binary.
5103 Here is an example:
5104 <literallayout class='monospaced'>
5105 $ bitbake gdb-cross
5106 </literallayout>
5107 Once the binary is built, you can find it here:
5108 <literallayout class='monospaced'>
5109 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
5110 </literallayout>
5111 </para>
5112 </section>
5113
5114 <section id='create-the-gdb-initialization-file'>
5115 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
5116
5117 <para>
5118 Aside from the GDB cross-binary, you also need a GDB
5119 initialization file in the same top directory in which
5120 your binary resides.
5121 When you start GDB on your host development system, GDB
5122 finds this initialization file and executes all the
5123 commands within.
5124 For information on the <filename>.gdbinit</filename>, see
5125 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
5126 which is maintained by
5127 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
5128 </para>
5129
5130 <para>
5131 You need to add a statement in the
5132 <filename>.gdbinit</filename> file that points to your
5133 root filesystem.
5134 Here is an example that points to the root filesystem for
5135 an ARM-based target device:
5136 <literallayout class='monospaced'>
5137 set sysroot /home/jzhang/sysroot_arm
5138 </literallayout>
5139 </para>
5140 </section>
5141
5142 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
5143 <title>Launch the Host GDB</title>
5144
5145 <para>
5146 Before launching the host GDB, you need to be sure
5147 you have sourced the cross-debugging environment script,
5148 which if you installed the root filesystem in the default
5149 location is at <filename>/opt/poky/&DISTRO;</filename>
5150 and begins with the string "environment-setup".
5151 For more information, see the
5152 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
5153 section in the Yocto Project Application Developer's
5154 Guide.
5155 </para>
5156
5157 <para>
5158 Finally, switch to the directory where the binary resides
5159 and run the <filename>cross-gdb</filename> binary.
5160 Provide the binary file you are going to debug.
5161 For example, the following command continues with the
5162 example used in the previous section by loading
5163 the <filename>helloworld</filename> binary as well as the
5164 debugging information:
5165 <literallayout class='monospaced'>
5166 $ arm-poky-linux-gnuabi-gdb helloworld
5167 </literallayout>
5168 The commands in your <filename>.gdbinit</filename> execute
5169 and the GDB prompt appears.
5170 </para>
5171 </section>
5172 </section>
5173
5174 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
5175 <title>Connect to the Remote GDB Server</title>
5176
5177 <para>
5178 From the target, you need to connect to the remote GDB
5179 server that is running on the host.
5180 You need to specify the remote host and port.
5181 Here is the command continuing with the example:
5182 <literallayout class='monospaced'>
5183 target remote 192.168.7.2:2345
5184 </literallayout>
5185 </para>
5186 </section>
5187
5188 <section id="platdev-gdb-remotedebug-launch-gdb-using">
5189 <title>Use the Debugger</title>
5190
5191 <para>
5192 You can now proceed with debugging as normal - as if you were debugging
5193 on the local machine.
5194 For example, to instruct GDB to break in the "main" function and then
5195 continue with execution of the inferior binary use the following commands
5196 from within GDB:
5197 <literallayout class='monospaced'>
5198 (gdb) break main
5199 (gdb) continue
5200 </literallayout>
5201 </para>
5202
5203 <para>
5204 For more information about using GDB, see the project's online documentation at
5205 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
5206 </para>
5207 </section>
5208 </section>
5209
5210 <section id="examining-builds-using-toaster">
5211 <title>Examining Builds Using the Toaster API</title>
5212
5213 <para>
5214 Toaster is an Application Programming Interface (API) and
5215 web-based interface to the OpenEmbedded build system, which uses
5216 BitBake.
5217 Both interfaces are based on a Representational State Transfer
5218 (REST) API that queries for and returns build information using
5219 <filename>GET</filename> and <filename>JSON</filename>.
5220 These types of search operations retrieve sets of objects from
5221 a data store used to collect build information.
5222 The results contain all the data for the objects being returned.
5223 You can order the results of the search by key and the search
5224 parameters are consistent for all object types.
5225 </para>
5226
5227 <para>
5228 Using the interfaces you can do the following:
5229 <itemizedlist>
5230 <listitem><para>See information about the tasks executed
5231 and reused during the build.</para></listitem>
5232 <listitem><para>See what is built (recipes and
5233 packages) and what packages were installed into the final
5234 image.</para></listitem>
5235 <listitem><para>See performance-related information such
5236 as build time, CPU usage, and disk I/O.</para></listitem>
5237 <listitem><para>Examine error, warning and trace messages
5238 to aid in debugging.</para></listitem>
5239 </itemizedlist>
5240 </para>
5241
5242 <note>
5243 <para>This release of Toaster provides you with information
5244 about a BitBake run.
5245 The tool does not allow you to configure and launch a build.
5246 However, future development includes plans to integrate the
5247 configuration and build launching capabilities of
5248 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
5249 </para>
5250 <para>For more information on using Hob to build an image,
5251 see the
5252 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
5253 section.</para>
5254 </note>
5255
5256 <para>
5257 The remainder of this section describes what you need to have in
5258 place to use Toaster, how to start it, use it, and stop it.
5259 For additional information on installing and running Toaster, see the
5260 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
5261 section of the "Toaster" wiki page.
5262 For complete information on the API and its search operation
5263 URI, parameters, and responses, see the
5264 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
5265 Wiki page.
5266 </para>
5267
5268 <section id='starting-toaster'>
5269 <title>Starting Toaster</title>
5270
5271 <para>
5272 Getting set up to use and start Toaster is simple.
5273 First, be sure you have met the following requirements:
5274 <itemizedlist>
5275 <listitem><para>You have set up your
5276 <link linkend='source-directory'>Source Directory</link>
5277 by cloning the upstream <filename>poky</filename>
5278 repository.
5279 See the
5280 <link linkend='local-yp-release'>Yocto Project Release</link>
5281 item for information on how to set up the Source
5282 Directory.</para></listitem>
5283 <listitem><para>You have checked out the
5284 <filename>dora-toaster</filename> branch:
5285 <literallayout class='monospaced'>
5286 $ cd ~/poky
5287 $ git checkout -b dora-toaster origin/dora-toaster
5288 </literallayout></para></listitem>
5289 <listitem><para>Be sure your build machine has
5290 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
5291 version 1.4.5 installed.</para></listitem>
5292 <listitem><para>Make sure that port 8000 and 8200 are
5293 free (i.e. they have no servers on them).
5294 </para></listitem>
5295 </itemizedlist>
5296 </para>
5297
5298 <para>
5299 Once you have met the requirements, follow these steps to
5300 start Toaster running in the background of your shell:
5301 <orderedlist>
5302 <listitem><para><emphasis>Set up your build environment:</emphasis>
5303 Source a build environment script (i.e.
5304 <filename>oe-init-build-env</filename> or
5305 <filename>oe-init-build-env-memres</filename>).
5306 </para></listitem>
5307 <listitem><para><emphasis>Prepare your local configuration file:</emphasis>
5308 Toaster needs the Toaster class enabled
5309 in Bitbake in order to record target image package
5310 information.
5311 You can enable it by adding the following line to your
5312 <filename>conf/local.conf</filename> file:
5313 <literallayout class='monospaced'>
5314 INHERIT += "toaster"
5315 </literallayout>
5316 Toaster also needs Build History enabled in Bitbake in
5317 order to record target image package information.
5318 You can enable this by adding the following two lines
5319 to your <filename>conf/local.conf</filename> file:
5320 <literallayout class='monospaced'>
5321 INHERIT += "buildhistory"
5322 BUILDHISTORY_COMMIT = "1"
5323 </literallayout></para></listitem>
5324 <listitem><para><emphasis>Start Toaster:</emphasis>
5325 Start the Toaster service using this
5326 command from within your build directory:
5327 <literallayout class='monospaced'>
5328 $ source toaster start
5329 </literallayout></para></listitem>
5330 <note>
5331 The Toaster must be started and running in order
5332 for it to collect data.
5333 </note>
5334 </orderedlist>
5335 </para>
5336
5337 <para>
5338 When Toaster starts, it creates some additional files in your
5339 Build Directory.
5340 Deleting these files will cause you to lose data or interrupt
5341 Toaster:
5342 <itemizedlist>
5343 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
5344 Toaster's database file.</para></listitem>
5345 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
5346 The log file of the web server.</para></listitem>
5347 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
5348 The log file of the user interface component.
5349 </para></listitem>
5350 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
5351 The PID of the web server.</para></listitem>
5352 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
5353 The PID of the DSI data bridge.</para></listitem>
5354 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
5355 The BitBake server's log file.</para></listitem>
5356 </itemizedlist>
5357 </para>
5358 </section>
5359
5360 <section id='using-toaster'>
5361 <title>Using Toaster</title>
5362
5363 <para>
5364 Once Toaster is running, it logs information for any BitBake
5365 run from your Build Directory.
5366 This logging is automatic.
5367 All you need to do is access and use the information.
5368 </para>
5369
5370 <para>
5371 You access the information one of two ways:
5372 <itemizedlist>
5373 <listitem><para>Open a Browser and type enter in the
5374 <filename>http://localhost:8000</filename> URL.
5375 </para></listitem>
5376 <listitem><para>Use the <filename>xdg-open</filename>
5377 tool from the shell and pass it the same URL.
5378 </para></listitem>
5379 </itemizedlist>
5380 Either method opens the home page for the Toaster interface,
5381 which is temporary for this release.
5382 </para>
5383 </section>
5384
5385 <section id='examining-toaster-data'>
5386 <title>Examining Toaster Data</title>
5387
5388 <para>
5389 The Toaster database is persistent regardless of whether you
5390 start or stop the service.
5391 </para>
5392
5393 <para>
5394 Toaster's interface shows you a list of builds
5395 (successful and unsuccessful) for which it has data.
5396 You can click on any build to see related information.
5397 This information includes configuration details, information
5398 about tasks, all recipes and packages built and their
5399 dependencies, packages installed in your final image,
5400 execution time, CPU usage and disk I/O per task.
5401 </para>
5402 </section>
5403
5404 <section id='stopping-toaster'>
5405 <title>Stopping Toaster</title>
5406
5407 <para>
5408 Stop the Toaster service with the following command:
5409 <literallayout class='monospaced'>
5410 $ source toaster stop
5411 </literallayout>
5412 The service stops but the Toaster database remains persistent.
5413 </para>
5414 </section>
5415 </section>
5416
5417 <section id="platdev-oprofile">
5418 <title>Profiling with OProfile</title>
5419
5420 <para>
5421 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
5422 statistical profiler well suited for finding performance
5423 bottlenecks in both user-space software and in the kernel.
5424 This profiler provides answers to questions like "Which functions does my application spend
5425 the most time in when doing X?"
5426 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
5427 applications on target hardware straightforward.
5428 <note>
5429 For more information on how to set up and run OProfile, see the
5430 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
5431 section in the Yocto Project Profiling and Tracing Manual.
5432 </note>
5433 </para>
5434
5435 <para>
5436 To use OProfile, you need an image that has OProfile installed.
5437 The easiest way to do this is with <filename>tools-profile</filename> in the
5438 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
5439 You also need debugging symbols to be available on the system where the analysis
5440 takes place.
5441 You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
5442 <filename>IMAGE_FEATURES</filename> variable or by
5443 installing the appropriate <filename>-dbg</filename> packages.
5444 </para>
5445
5446 <para>
5447 For successful call graph analysis, the binaries must preserve the frame
5448 pointer register and should also be compiled with the
5449 <filename>-fno-omit-framepointer</filename> flag.
5450 You can achieve this by setting the
5451 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
5452 variable with the following options:
5453 <literallayout class='monospaced'>
5454 -fexpensive-optimizations
5455 -fno-omit-framepointer
5456 -frename-registers
5457 -O2
5458 </literallayout>
5459 You can also achieve it by setting the
5460 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
5461 variable to "1" in the <filename>local.conf</filename> configuration file.
5462 If you use the <filename>DEBUG_BUILD</filename> variable,
5463 you also add extra debugging information that can make the debug
5464 packages large.
5465 </para>
5466
5467 <section id="platdev-oprofile-target">
5468 <title>Profiling on the Target</title>
5469
5470 <para>
5471 Using OProfile you can perform all the profiling work on the target device.
5472 A simple OProfile session might look like the following:
5473 </para>
5474
5475 <para>
5476 <literallayout class='monospaced'>
5477 # opcontrol --reset
5478 # opcontrol --start --separate=lib --no-vmlinux -c 5
5479 .
5480 .
5481 [do whatever is being profiled]
5482 .
5483 .
5484 # opcontrol --stop
5485 $ opreport -cl
5486 </literallayout>
5487 </para>
5488
5489 <para>
5490 In this example, the <filename>reset</filename> command clears any previously profiled data.
5491 The next command starts OProfile.
5492 The options used when starting the profiler separate dynamic library data
5493 within applications, disable kernel profiling, and enable callgraphing up to
5494 five levels deep.
5495 <note>
5496 To profile the kernel, you would specify the
5497 <filename>--vmlinux=/path/to/vmlinux</filename> option.
5498 The <filename>vmlinux</filename> file is usually in the source directory in the
5499 <filename>/boot/</filename> directory and must match the running kernel.
5500 </note>
5501 </para>
5502
5503 <para>
5504 After you perform your profiling tasks, the next command stops the profiler.
5505 After that, you can view results with the <filename>opreport</filename> command with options
5506 to see the separate library symbols and callgraph information.
5507 </para>
5508
5509 <para>
5510 Callgraphing logs information about time spent in functions and about a function's
5511 calling function (parent) and called functions (children).
5512 The higher the callgraphing depth, the more accurate the results.
5513 However, higher depths also increase the logging overhead.
5514 Consequently, you should take care when setting the callgraphing depth.
5515 <note>
5516 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
5517 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
5518 with <filename>gcc</filename>.
5519 </note>
5520 </para>
5521
5522 <para>
5523 For more information on using OProfile, see the OProfile
5524 online documentation at
5525 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
5526 </para>
5527 </section>
5528
5529 <section id="platdev-oprofile-oprofileui">
5530 <title>Using OProfileUI</title>
5531
5532 <para>
5533 A graphical user interface for OProfile is also available.
5534 You can download and build this interface from the Yocto Project at
5535 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
5536 If the "tools-profile" image feature is selected, all necessary binaries
5537 are installed onto the target device for OProfileUI interaction.
5538 For a list of image features that ship with the Yocto Project,
5539 see the
5540 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Images</ulink>"
5541 section in the Yocto Project Reference Manual.
5542 </para>
5543
5544 <para>
5545 Even though the source directory usually includes all needed patches on the target device, you
5546 might find you need other OProfile patches for recent OProfileUI features.
5547 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
5548 OProfileUI README</ulink> for the most recent information.
5549 </para>
5550
5551 <section id="platdev-oprofile-oprofileui-online">
5552 <title>Online Mode</title>
5553
5554 <para>
5555 Using OProfile in online mode assumes a working network connection with the target
5556 hardware.
5557 With this connection, you just need to run "oprofile-server" on the device.
5558 By default, OProfile listens on port 4224.
5559 <note>
5560 You can change the port using the <filename>--port</filename> command-line
5561 option.
5562 </note>
5563 </para>
5564
5565 <para>
5566 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
5567 straightforward.
5568 You access key functionality through the buttons on the toolbar, which
5569 are duplicated in the menus.
5570 Here are the buttons:
5571 <itemizedlist>
5572 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
5573 You can also supply the IP address or hostname.</para></listitem>
5574 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
5575 </para></listitem>
5576 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
5577 </para></listitem>
5578 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
5579 downloads the data to the local host.
5580 Stopping the profiler generates the profile and displays it in the viewer.
5581 </para></listitem>
5582 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
5583 target and generates the profile, which appears in the viewer.</para></listitem>
5584 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
5585 Resetting the data removes sample information collected from previous
5586 sampling runs.
5587 Be sure you reset the data if you do not want to include old sample information.
5588 </para></listitem>
5589 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
5590 target to another directory for later examination.</para></listitem>
5591 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
5592 </para></listitem>
5593 </itemizedlist>
5594 </para>
5595
5596 <para>
5597 The client downloads the complete 'profile archive' from
5598 the target to the host for processing.
5599 This archive is a directory that contains the sample data, the object files,
5600 and the debug information for the object files.
5601 The archive is then converted using the <filename>oparchconv</filename> script, which is
5602 included in this distribution.
5603 The script uses <filename>opimport</filename> to convert the archive from
5604 the target to something that can be processed on the host.
5605 </para>
5606
5607 <para>
5608 Downloaded archives reside in the
5609 <link linkend='build-directory'>Build Directory</link> in
5610 <filename>/tmp</filename> and are cleared up when they are no longer in use.
5611 </para>
5612
5613 <para>
5614 If you wish to perform kernel profiling, you need to be sure
5615 a <filename>vmlinux</filename> file that matches the running kernel is available.
5616 In the source directory, that file is usually located in
5617 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
5618 <filename>KERNEL-version</filename> is the version of the kernel.
5619 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
5620 packages for each kernel it builds.
5621 Thus, it should just be a question of making sure a matching package is
5622 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
5623 The files are automatically installed into development and profiling images
5624 alongside OProfile.
5625 A configuration option exists within the OProfileUI settings page that you can use to
5626 enter the location of the <filename>vmlinux</filename> file.
5627 </para>
5628
5629 <para>
5630 Waiting for debug symbols to transfer from the device can be slow, and it
5631 is not always necessary to actually have them on the device for OProfile use.
5632 All that is needed is a copy of the filesystem with the debug symbols present
5633 on the viewer system.
5634 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
5635 section covers how to create such a directory with
5636 the <link linkend='source-directory'>Source Directory</link>
5637 and how to use the OProfileUI Settings Dialog to specify the location.
5638 If you specify the directory, it will be used when the file checksums
5639 match those on the system you are profiling.
5640 </para>
5641 </section>
5642
5643 <section id="platdev-oprofile-oprofileui-offline">
5644 <title>Offline Mode</title>
5645
5646 <para>
5647 If network access to the target is unavailable, you can generate
5648 an archive for processing in <filename>oprofile-viewer</filename> as follows:
5649 <literallayout class='monospaced'>
5650 # opcontrol --reset
5651 # opcontrol --start --separate=lib --no-vmlinux -c 5
5652 .
5653 .
5654 [do whatever is being profiled]
5655 .
5656 .
5657 # opcontrol --stop
5658 # oparchive -o my_archive
5659 </literallayout>
5660 </para>
5661
5662 <para>
5663 In the above example, <filename>my_archive</filename> is the name of the
5664 archive directory where you would like the profile archive to be kept.
5665 After the directory is created, you can copy it to another host and load it
5666 using <filename>oprofile-viewer</filename> open functionality.
5667 If necessary, the archive is converted.
5668 </para>
5669 </section>
5670 </section>
5671 </section>
5672
5673 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
5674 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
5675
5676 <para>
5677 One of the concerns for a development organization using open source
5678 software is how to maintain compliance with various open source
5679 licensing during the lifecycle of the product.
5680 While this section does not provide legal advice or
5681 comprehensively cover all scenarios, it does
5682 present methods that you can use to
5683 assist you in meeting the compliance requirements during a software
5684 release.
5685 </para>
5686
5687 <para>
5688 With hundreds of different open source licenses that the Yocto
5689 Project tracks, it is difficult to know the requirements of each
5690 and every license.
5691 However, we can begin to cover the requirements of the major FLOSS licenses, by
5692 assuming that there are three main areas of concern:
5693 <itemizedlist>
5694 <listitem><para>Source code must be provided.</para></listitem>
5695 <listitem><para>License text for the software must be
5696 provided.</para></listitem>
5697 <listitem><para>Compilation scripts and modifications to the
5698 source code must be provided.
5699 </para></listitem>
5700 </itemizedlist>
5701 There are other requirements beyond the scope of these
5702 three and the methods described in this section
5703 (e.g. the mechanism through which source code is distributed).
5704 </para>
5705
5706 <para>
5707 As different organizations have different methods of complying with
5708 open source licensing, this section is not meant to imply that
5709 there is only one single way to meet your compliance obligations,
5710 but rather to describe one method of achieving compliance.
5711 The remainder of this section describes methods supported to meet the
5712 previously mentioned three requirements.
5713 Once you take steps to meet these requirements,
5714 and prior to releasing images, sources, and the build system,
5715 you should audit all artifacts to ensure completeness.
5716 <note>
5717 The Yocto Project generates a license manifest during
5718 image creation that is located
5719 in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
5720 to assist with any audits.
5721 </note>
5722 </para>
5723
5724 <section id='providing-the-source-code'>
5725 <title>Providing the Source Code</title>
5726
5727 <para>
5728 Compliance activities should begin before you generate the
5729 final image.
5730 The first thing you should look at is the requirement that
5731 tops the list for most compliance groups - providing
5732 the source.
5733 The Yocto Project has a few ways of meeting this
5734 requirement.
5735 </para>
5736
5737 <para>
5738 One of the easiest ways to meet this requirement is
5739 to provide the entire
5740 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
5741 used by the build.
5742 This method, however, has a few issues.
5743 The most obvious is the size of the directory since it includes
5744 all sources used in the build and not just the source used in
5745 the released image.
5746 It will include toolchain source, and other artifacts, which
5747 you would not generally release.
5748 However, the more serious issue for most companies is accidental
5749 release of proprietary software.
5750 The Yocto Project provides an archiver class to help avoid
5751 some of these concerns.
5752 See the
5753 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'>Archiving Sources - <filename>archive*.bbclass</filename></ulink>"
5754 section in the Yocto Project Reference Manual for information
5755 on this class.
5756 </para>
5757
5758 <para>
5759 Before you employ <filename>DL_DIR</filename> or the
5760 archiver class, you need to decide how you choose to
5761 provide source.
5762 The source archiver class can generate tarballs and SRPMs
5763 and can create them with various levels of compliance in mind.
5764 One way of doing this (but certainly not the only way) is to
5765 release just the original source as a tarball.
5766 You can do this by adding the following to the
5767 <filename>local.conf</filename> file found in the
5768 <link linkend='build-directory'>Build Directory</link>:
5769 <literallayout class='monospaced'>
5770 ARCHIVER_MODE ?= "original"
5771 ARCHIVER_CLASS = "${@'archive-${ARCHIVER_MODE}-source' if
5772 ARCHIVER_MODE != 'none' else ''}"
5773 INHERIT += "${ARCHIVER_CLASS}"
5774 SOURCE_ARCHIVE_PACKAGE_TYPE = "tar"
5775 </literallayout>
5776 During the creation of your image, the source from all
5777 recipes that deploy packages to the image is placed within
5778 subdirectories of
5779 <filename>DEPLOY_DIR/sources</filename> based on the
5780 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
5781 for each recipe.
5782 Releasing the entire directory enables you to comply with
5783 requirements concerning providing the unmodified source.
5784 It is important to note that the size of the directory can
5785 get large.
5786 </para>
5787
5788 <para>
5789 A way to help mitigate the size issue is to only release
5790 tarballs for licenses that require the release of
5791 source.
5792 Let's assume you are only concerned with GPL code as
5793 identified with the following:
5794 <literallayout class='monospaced'>
5795 $ cd poky/build/tmp/deploy/sources
5796 $ mkdir ~/gpl_source_release
5797 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
5798 </literallayout>
5799 At this point, you could create a tarball from the
5800 <filename>gpl_source_release</filename> directory and
5801 provide that to the end user.
5802 This method would be a step toward achieving compliance
5803 with section 3a of GPLv2 and with section 6 of GPLv3.
5804 </para>
5805 </section>
5806
5807 <section id='providing-license-text'>
5808 <title>Providing License Text</title>
5809
5810 <para>
5811 One requirement that is often overlooked is inclusion
5812 of license text.
5813 This requirement also needs to be dealt with prior to
5814 generating the final image.
5815 Some licenses require the license text to accompany
5816 the binary.
5817 You can achieve this by adding the following to your
5818 <filename>local.conf</filename> file:
5819 <literallayout class='monospaced'>
5820 COPY_LIC_MANIFEST = "1"
5821 COPY_LIC_DIRS = "1"
5822 </literallayout>
5823 Adding these statements to the configuration file ensures
5824 that the licenses collected during package generation
5825 are included on your image.
5826 As the source archiver has already archived the original
5827 unmodified source that contains the license files,
5828 you would have already met the requirements for inclusion
5829 of the license information with source as defined by the GPL
5830 and other open source licenses.
5831 </para>
5832 </section>
5833
5834 <section id='providing-compilation-scripts-and-source-code-modifications'>
5835 <title>Providing Compilation Scripts and Source Code Modifications</title>
5836
5837 <para>
5838 At this point, we have addressed all we need to address
5839 prior to generating the image.
5840 The next two requirements are addressed during the final
5841 packaging of the release.
5842 </para>
5843
5844 <para>
5845 By releasing the version of the OpenEmbedded build system
5846 and the layers used during the build, you will be providing both
5847 compilation scripts and the source code modifications in one
5848 step.
5849 </para>
5850
5851 <para>
5852 If the deployment team has a
5853 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
5854 and a distro layer, and those those layers are used to patch,
5855 compile, package, or modify (in any way) any open source
5856 software included in your released images, you
5857 may be required to to release those layers under section 3 of
5858 GPLv2 or section 1 of GPLv3.
5859 One way of doing that is with a clean
5860 checkout of the version of the Yocto Project and layers used
5861 during your build.
5862 Here is an example:
5863 <literallayout class='monospaced'>
5864 # We built using the &DISTRO_NAME; branch of the poky repo
5865 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
5866 $ cd poky
5867 # We built using the release_branch for our layers
5868 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
5869 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
5870 # clean up the .git repos
5871 $ find . -name ".git" -type d -exec rm -rf {} \;
5872 </literallayout>
5873 One thing a development organization might want to consider
5874 for end-user convenience is to modify
5875 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
5876 ensure that when the end user utilizes the released build
5877 system to build an image, the development organization's
5878 layers are included in the <filename>bblayers.conf</filename>
5879 file automatically:
5880 <literallayout class='monospaced'>
5881 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
5882 # changes incompatibly
5883 LCONF_VERSION = "6"
5884
5885 BBPATH = "${TOPDIR}"
5886 BBFILES ?= ""
5887
5888 BBLAYERS ?= " \
5889 ##OEROOT##/meta \
5890 ##OEROOT##/meta-yocto \
5891 ##OEROOT##/meta-yocto-bsp \
5892 ##OEROOT##/meta-mylayer \
5893 "
5894
5895 BBLAYERS_NON_REMOVABLE ?= " \
5896 ##OEROOT##/meta \
5897 ##OEROOT##/meta-yocto \
5898 "
5899 </literallayout>
5900 Creating and providing an archive of the
5901 <link linkend='metadata'>Metadata</link> layers
5902 (recipes, configuration files, and so forth)
5903 enables you to meet your
5904 requirements to include the scripts to control compilation
5905 as well as any modifications to the original source.
5906 </para>
5907 </section>
5908 </section>
5909</chapter>
5910
5911<!--
5912vim: expandtab tw=80 ts=4
5913-->
diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl
new file mode 100644
index 0000000000..8969605989
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-customization.xsl
@@ -0,0 +1,10 @@
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/current/xhtml/docbook.xsl" />
5
6 <xsl:param name="html.stylesheet" select="'dev-style.css'" />
7 <xsl:param name="chapter.autolabel" select="1" />
8 <xsl:param name="section.autolabel" select="1" />
9 <xsl:param name="section.label.includes.component.label" select="1" />
10</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..8923a1d2fb
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -0,0 +1,210 @@
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 Wind River Linux, Mentor Embedded Linux, and ENEA Linux.
44 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
45 section for more information.
46 </note>
47 </section>
48
49 <section id='what-this-manual-provides'>
50 <title>What This Manual Provides</title>
51
52 <para>
53 The following list describes what you can get from this manual:
54 <itemizedlist>
55 <listitem><para>Information that lets you get set
56 up to develop using the Yocto Project.</para></listitem>
57 <listitem><para>Information to help developers who are new to
58 the open source environment and to the distributed revision
59 control system Git, which the Yocto Project uses.
60 </para></listitem>
61 <listitem><para>An understanding of common end-to-end
62 development models and tasks.</para></listitem>
63 <listitem><para>Information about common development tasks
64 generally used during image development for
65 embedded devices.
66 </para></listitem>
67 <listitem><para>Many references to other sources of related
68 information.</para></listitem>
69 </itemizedlist>
70 </para>
71 </section>
72
73 <section id='what-this-manual-does-not-provide'>
74 <title>What this Manual Does Not Provide</title>
75
76 <para>
77 This manual will not give you the following:
78 <itemizedlist>
79 <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto
80 Project documentation:</emphasis>
81 For example, the Yocto Project Application Developer's Guide contains detailed
82 instructions on how to run the
83 <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>ADT Installer</ulink>,
84 which is used to set up a cross-development environment.</para></listitem>
85 <listitem><para><emphasis>Reference material:</emphasis>
86 This type of material resides in an appropriate reference manual.
87 For example, system variables are documented in the
88 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
89 <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis>
90 For example, exhaustive information on how to use Git is covered better through the
91 Internet than in this manual.</para></listitem>
92 </itemizedlist>
93 </para>
94 </section>
95
96 <section id='other-information'>
97 <title>Other Information</title>
98
99 <para>
100 Because this manual presents overview information for many different
101 topics, supplemental information is recommended for full
102 comprehension.
103 The following list presents other sources of information you might find helpful:
104 <itemizedlist>
105 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
106 </emphasis> The home page for the Yocto Project provides lots of information on the project
107 as well as links to software and documentation.</para></listitem>
108 <listitem><para><emphasis>
109 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
110 with the Yocto Project and quickly begin building an image.</para></listitem>
111 <listitem><para><emphasis>
112 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
113 guide to the OpenEmbedded build system, which is based on BitBake.
114 The build system is sometimes referred to as "Poky".
115 </para></listitem>
116 <listitem><para><emphasis>
117 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
118 This guide provides information that lets you get going with the Application
119 Development Toolkit (ADT) and stand-alone cross-development toolchains to
120 develop projects using the Yocto Project.</para></listitem>
121 <listitem><para><emphasis>
122 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
123 This guide defines the structure for BSP components.
124 Having a commonly understood structure encourages standardization.</para></listitem>
125 <listitem><para><emphasis>
126 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:</emphasis>
127 This manual describes how to work with Linux Yocto kernels as well as provides a bit
128 of conceptual information on the construction of the Yocto Linux kernel tree.
129 </para></listitem>
130 <listitem><para><emphasis>
131 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:</emphasis>
132 This manual presents a set of common and generally useful tracing and
133 profiling schemes along with their applications (as appropriate) to each tool.
134 </para></listitem>
135 <listitem><para><emphasis>
136 <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
137 Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that
138 demonstrates how an application developer uses Yocto Plug-in features within
139 the Eclipse IDE.</para></listitem>
140 <listitem><para><emphasis>
141 <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
142 A list of commonly asked questions and their answers.</para></listitem>
143 <listitem><para><emphasis>
144 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:</emphasis>
145 Features, updates and known issues for the current
146 release of the Yocto Project.</para></listitem>
147 <listitem><para><emphasis>
148 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>
149 Hob</ulink>:</emphasis> A graphical user interface for BitBake.
150 Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem>
151 <listitem><para><emphasis>
152 <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'>
153 Build Appliance</ulink>:</emphasis> A virtual machine that
154 enables you to build and boot a custom embedded Linux image
155 with the Yocto Project using a non-Linux development system.
156 For more information, see the
157 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance-manual'>Build Appliance</ulink>
158 page.
159 </para></listitem>
160 <listitem><para><emphasis>
161 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
162 The bug tracking application the Yocto Project uses.
163 If you find problems with the Yocto Project, you should report them using this
164 application.</para></listitem>
165 <listitem><para><emphasis>
166 Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
167 lists, click on the following URLs and follow the instructions:
168 <itemizedlist>
169 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
170 Yocto Project Discussions mailing list.</para></listitem>
171 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
172 Yocto Project Discussions mailing list about the
173 OpenEmbedded build system (Poky).
174 </para></listitem>
175 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
176 for a mailing list to receive official Yocto Project announcements
177 as well as Yocto Project milestones.</para></listitem>
178 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a
179 listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>.
180 </para></listitem>
181 </itemizedlist></para></listitem>
182 <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
183 Two IRC channels on freenode are available
184 for Yocto Project and Poky discussions: <filename>#yocto</filename> and
185 <filename>#poky</filename>, respectively.</para></listitem>
186 <listitem><para><emphasis>
187 <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
188 The build system used by the Yocto Project.
189 This project is the upstream, generic, embedded distribution that the Yocto
190 Project derives its build system (Poky) from and to which it contributes.</para></listitem>
191 <listitem><para><emphasis>
192 <ulink url='http://developer.berlios.de/projects/bitbake/'>
193 BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
194 to process project metadata.</para></listitem>
195 <listitem><para><emphasis>
196 BitBake User Manual:</emphasis>
197 A comprehensive guide to the BitBake tool.
198 If you want information on BitBake, see the user manual included in the
199 <filename>bitbake/doc/manual</filename> directory of the
200 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
201 <listitem><para><emphasis>
202 <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
203 </emphasis> An open-source machine emulator and virtualizer.</para></listitem>
204 </itemizedlist>
205 </para>
206 </section>
207</chapter>
208<!--
209vim: expandtab tw=80 ts=4
210-->
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
new file mode 100644
index 0000000000..cb09627d6e
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -0,0 +1,2058 @@
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
22 Development Manual</ulink>.
23 </para></listitem>
24 <listitem><para><emphasis>User Application Development:</emphasis>
25 User Application Development covers development of applications that you intend
26 to run on target hardware.
27 For information on how to set up your host development system for user-space
28 application development, see the
29 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
30 For a simple example of user-space application development using the
31 <trademark class='trade'>Eclipse</trademark> IDE, see the
32 "<link linkend='application-development-workflow'>Application
33 Development Workflow</link>" section.
34 </para></listitem>
35 <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
36 Direct modification of temporary source code is a convenient development model
37 to quickly iterate and develop towards a solution.
38 Once you implement the solution, you should of course take steps to
39 get the changes upstream and applied in the affected recipes.</para></listitem>
40 <listitem><para><emphasis>Image Development using Hob:</emphasis>
41 You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build
42 custom operating system images within the build environment.
43 Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
44 <listitem><para><emphasis>Using a Development Shell:</emphasis>
45 You can use a <filename>devshell</filename> to efficiently debug commands or simply
46 edit packages.
47 Working inside a development shell is a quick way to set up the OpenEmbedded build
48 environment to work on parts of a project.</para></listitem>
49 </itemizedlist>
50</para>
51
52<section id='system-development-model'>
53 <title>System Development Workflow</title>
54
55 <para>
56 System development involves modification or creation of an image that you want to run on
57 a specific hardware target.
58 Usually, when you want to create an image that runs on embedded hardware, the image does
59 not require the same number of features that a full-fledged Linux distribution provides.
60 Thus, you can create a much smaller image that is designed to use only the
61 features for your particular hardware.
62 </para>
63
64 <para>
65 To help you understand how system development works in the Yocto Project, this section
66 covers two types of image development: BSP creation and kernel modification or
67 configuration.
68 </para>
69
70 <section id='developing-a-board-support-package-bsp'>
71 <title>Developing a Board Support Package (BSP)</title>
72
73 <para>
74 A BSP is a package of recipes that, when applied during a build, results in
75 an image that you can run on a particular board.
76 Thus, the package when compiled into the new image, supports the operation of the board.
77 </para>
78
79 <note>
80 For a brief list of terms used when describing the development process in the Yocto Project,
81 see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
82 </note>
83
84 <para>
85 The remainder of this section presents the basic
86 steps used to create a BSP using the Yocto Project's
87 <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>.
88 Although not required for BSP creation, the
89 <filename>meta-intel</filename> repository, which contains
90 many BSPs supported by the Yocto Project, is part of the example.
91 </para>
92
93 <para>
94 For an example that shows how to create a new layer using the tools, see the
95 "<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>"
96 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
97 </para>
98
99 <para>
100 The following illustration and list summarize the BSP creation general workflow.
101 </para>
102
103 <para>
104 <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
105 </para>
106
107 <para>
108 <orderedlist>
109 <listitem><para><emphasis>Set up your host development system to support
110 development using the Yocto Project</emphasis>: See the
111 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
112 and the
113 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
114 in the Yocto Project Quick Start for requirements.</para></listitem>
115 <listitem><para><emphasis>Establish a local copy of the project files on your
116 system</emphasis>: You need this <link linkend='source-directory'>Source
117 Directory</link> available on your host system.
118 Having these files on your system gives you access to the build
119 process and to the tools you need.
120 For information on how to set up the Source Directory,
121 see the
122 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
123 <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
124 repository on your system</emphasis>: Having local copies
125 of these supported BSP layers on your system gives you
126 access to layers you might be able to build on or modify
127 to create your BSP.
128 For information on how to get these files, see the
129 "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
130 <listitem><para><emphasis>Create your own BSP layer using the
131 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
132 Layers are ideal for
133 isolating and storing work for a given piece of hardware.
134 A layer is really just a location or area in which you place
135 the recipes and configurations for your BSP.
136 In fact, a BSP is, in itself, a special type of layer.
137 The simplest way to create a new BSP layer that is compliant with the
138 Yocto Project is to use the <filename>yocto-bsp</filename> script.
139 For information about that script, see the
140 "<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>"
141 section in the Yocto Project Board Support (BSP) Developer's Guide.
142 </para>
143 <para>
144 Another example that illustrates a layer is an application.
145 Suppose you are creating an application that has library or other dependencies in
146 order for it to compile and run.
147 The layer, in this case, would be where all the recipes that define those dependencies
148 are kept.
149 The key point for a layer is that it is an isolated area that contains
150 all the relevant information for the project that the OpenEmbedded build
151 system knows about.
152 For more information on layers, see the
153 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
154 section.
155 For more information on BSP layers, see the
156 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the
157 Yocto Project Board Support Package (BSP) Developer's Guide.</para>
158 <note>Four BSPs exist that are part of the
159 Yocto Project release: <filename>genericx86</filename>, <filename>beagleboard</filename>,
160 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
161 The recipes and configurations for these four BSPs are located and dispersed
162 within the <link linkend='source-directory'>Source Directory</link>.
163 On the other hand, BSP layers for Chief River, Crown Bay,
164 Crystal Forest, Emenlow, Fish River Island 2, Jasper Forest, N450, NUC DC3217IYE,
165 Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers
166 within the larger <filename>meta-intel</filename> layer.</note>
167 <para>When you set up a layer for a new BSP, you should follow a standard layout.
168 This layout is described in the
169 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
170 section of the Board Support Package (BSP) Development Guide.
171 In the standard layout, you will notice a suggested structure for recipes and
172 configuration information.
173 You can see the standard layout for a BSP by examining
174 any supported BSP found in the <filename>meta-intel</filename> layer inside
175 the Source Directory.</para></listitem>
176 <listitem><para><emphasis>Make configuration changes to your new BSP
177 layer</emphasis>: The standard BSP layer structure organizes the files you need
178 to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
179 directories within the BSP layer.
180 Configuration changes identify where your new layer is on the local system
181 and identify which kernel you are going to use.
182 When you run the <filename>yocto-bsp</filename> script, you are able to interactively
183 configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
184 </para></listitem>
185 <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
186 changes include altering recipes (<filename>.bb</filename> files), removing
187 recipes you don't use, and adding new recipes or append files
188 (<filename>.bbappend</filename>) that you need to support your hardware.
189 </para></listitem>
190 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
191 changes to your BSP layer, there remains a few things
192 you need to do for the OpenEmbedded build system in order for it to create your image.
193 You need to get the build environment ready by sourcing an environment setup script
194 and you need to be sure two key configuration files are configured appropriately:
195 the <filename>conf/local.conf</filename> and the
196 <filename>conf/bblayers.conf</filename> file.
197 You must make the OpenEmbedded build system aware of your new layer.
198 See the
199 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
200 for information on how to let the build system know about your new layer.</para>
201 <para>The entire process for building an image is overviewed in the section
202 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
203 of the Yocto Project Quick Start.
204 You might want to reference this information.</para></listitem>
205 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
206 uses the BitBake tool to build images based on the type of image you want to create.
207 You can find more information about BitBake in the user manual, which is found in the
208 <filename>bitbake/doc/manual</filename> directory of the
209 <link linkend='source-directory'>Source Directory</link>.</para>
210 <para>The build process supports several types of images to satisfy different needs.
211 See the
212 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
213 in the Yocto Project Reference Manual for information on
214 supported images.</para></listitem>
215 </orderedlist>
216 </para>
217
218 <para>
219 You can view a video presentation on "Building Custom Embedded Images with Yocto"
220 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
221 You can also find supplemental information in
222 <ulink url='&YOCTO_DOCS_BSP_URL;'>
223 The Board Support Package (BSP) Development Guide</ulink>.
224 Finally, there is wiki page write up of the example also located
225 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
226 here</ulink> that you might find helpful.
227 </para>
228 </section>
229
230 <section id='modifying-the-kernel'>
231 <title><anchor id='kernel-spot' />Modifying the Kernel</title>
232
233 <para>
234 Kernel modification involves changing the Yocto Project kernel, which could involve changing
235 configuration options as well as adding new kernel recipes.
236 Configuration changes can be added in the form of configuration fragments, while recipe
237 modification comes through the kernel's <filename>recipes-kernel</filename> area
238 in a kernel layer you create.
239 </para>
240
241 <para>
242 The remainder of this section presents a high-level overview of the Yocto Project
243 kernel architecture and the steps to modify the kernel.
244 You can reference the
245 "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
246 for an example that changes the source code of the kernel.
247 For information on how to configure the kernel, see the
248 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
249 For more information on the kernel and on modifying the kernel, see the
250 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
251 </para>
252
253 <section id='kernel-overview'>
254 <title>Kernel Overview</title>
255
256 <para>
257 Traditionally, when one thinks of a patched kernel, they think of a base kernel
258 source tree and a fixed structure that contains kernel patches.
259 The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
260 generator.
261 By the end of this section, this analogy will become clearer.
262 </para>
263
264 <para>
265 You can find a web interface to the Yocto Project kernel source repositories at
266 <ulink url='&YOCTO_GIT_URL;'></ulink>.
267 If you look at the interface, you will see to the left a grouping of
268 Git repositories titled "Yocto Linux Kernel."
269 Within this group, you will find several kernels supported by
270 the Yocto Project:
271 <itemizedlist>
272 <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The
273 stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel
274 is based on the Linux 3.4 released kernel.</para></listitem>
275 <listitem><para><emphasis><filename>linux-yocto-3.8</filename></emphasis> - The
276 stable Yocto Project kernel to use with the Yocto Project Release 1.4. This kernel
277 is based on the Linux 3.8 released kernel.</para></listitem>
278 <listitem><para><emphasis><filename>linux-yocto-3.10</filename></emphasis> - The
279 stable Yocto Project kernel to use with the Yocto Project Release 1.5. This kernel
280 is based on the Linux 3.10 released kernel.</para></listitem>
281 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
282 kernel based on the latest upstream release candidate available.</para></listitem>
283 </itemizedlist>
284 </para>
285
286 <para>
287 The kernels are maintained using the Git revision control system
288 that structures them using the familiar "tree", "branch", and "leaf" scheme.
289 Branches represent diversions from general code to more specific code, while leaves
290 represent the end-points for a complete and unique kernel whose source files,
291 when gathered from the root of the tree to the leaf, accumulate to create the files
292 necessary for a specific piece of hardware and its features.
293 The following figure displays this concept:
294 <para>
295 <imagedata fileref="figures/kernel-overview-1.png"
296 width="6in" depth="6in" align="center" scale="100" />
297 </para>
298
299 <para>
300 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
301 where a supported base kernel is modified from the Linux kernel.
302 For example, this could be the branch point for the <filename>linux-yocto-3.4</filename>
303 kernel.
304 Thus, everything further to the right in the structure is based on the
305 <filename>linux-yocto-3.4</filename> kernel.
306 Branch points to right in the figure represent where the
307 <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware
308 or types of kernels, such as real-time kernels.
309 Each leaf thus represents the end-point for a kernel designed to run on a specific
310 targeted device.
311 </para>
312
313 <para>
314 The overall result is a Git-maintained repository from which all the supported
315 kernel types can be derived for all the supported devices.
316 A big advantage to this scheme is the sharing of common features by keeping them in
317 "larger" branches within the tree.
318 This practice eliminates redundant storage of similar features shared among kernels.
319 </para>
320
321 <note>
322 Keep in mind the figure does not take into account all the supported Yocto
323 Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
324 Also keep in mind that this structure represents the Yocto Project source repositories
325 that are either pulled from during the build or established on the host development system
326 prior to the build by either cloning a particular kernel's Git repository or by
327 downloading and unpacking a tarball.
328 </note>
329
330 <para>
331 Upstream storage of all the available kernel source code is one thing, while
332 representing and using the code on your host development system is another.
333 Conceptually, you can think of the kernel source repositories as all the
334 source files necessary for all the supported kernels.
335 As a developer, you are just interested in the source files for the kernel on
336 which you are working.
337 And, furthermore, you need them available on your host system.
338 </para>
339
340 <para>
341 Kernel source code is available on your host system a couple of different
342 ways.
343 If you are working in the kernel all the time, you probably would want
344 to set up your own local Git repository of the kernel tree.
345 If you just need to make some patches to the kernel, you can access
346 temporary kernel source files that were extracted and used
347 during a build.
348 We will just talk about working with the temporary source code.
349 For more information on how to get kernel source code onto your
350 host system, see the
351 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
352 bulleted item earlier in the manual.
353 </para>
354
355 <para>
356 What happens during the build?
357 When you build the kernel on your development system, all files needed for the build
358 are taken from the source repositories pointed to by the
359 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
360 and gathered in a temporary work area
361 where they are subsequently used to create the unique kernel.
362 Thus, in a sense, the process constructs a local source tree specific to your
363 kernel to generate the new kernel image - a source generator if you will.
364 </para>
365 The following figure shows the temporary file structure
366 created on your host system when the build occurs.
367 This
368 <link linkend='build-directory'>Build Directory</link> contains all the
369 source files used during the build.
370 </para>
371
372 <para>
373 <imagedata fileref="figures/kernel-overview-2-generic.png"
374 width="6in" depth="5in" align="center" scale="100" />
375 </para>
376
377 <para>
378 Again, for additional information the Yocto Project kernel's
379 architecture and its branching strategy, see the
380 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
381 You can also reference the
382 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
383 section for a detailed example that modifies the kernel.
384 </para>
385 </section>
386
387 <section id='kernel-modification-workflow'>
388 <title>Kernel Modification Workflow</title>
389
390 <para>
391 This illustration and the following list summarizes the kernel modification general workflow.
392 </para>
393
394 <para>
395 <imagedata fileref="figures/kernel-dev-flow.png"
396 width="6in" depth="5in" align="center" scalefit="1" />
397 </para>
398
399 <para>
400 <orderedlist>
401 <listitem><para><emphasis>Set up your host development system to support
402 development using the Yocto Project</emphasis>: See
403 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
404 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
405 in the Yocto Project Quick Start for requirements.</para></listitem>
406 <listitem><para><emphasis>Establish a local copy of project files on your
407 system</emphasis>: Having the <link linkend='source-directory'>Source
408 Directory</link> on your system gives you access to the build process and tools
409 you need.
410 For information on how to get these files, see the bulleted item
411 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
412 </para></listitem>
413 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
414 Temporary kernel source files are kept in the
415 <link linkend='build-directory'>Build Directory</link>
416 created by the
417 OpenEmbedded build system when you run BitBake.
418 If you have never built the kernel you are interested in, you need to run
419 an initial build to establish local kernel source files.</para>
420 <para>If you are building an image for the first time, you need to get the build
421 environment ready by sourcing
422 the environment setup script.
423 You also need to be sure two key configuration files
424 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
425 are configured appropriately.</para>
426 <para>The entire process for building an image is overviewed in the
427 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
428 section of the Yocto Project Quick Start.
429 You might want to reference this information.
430 You can find more information on BitBake in the user manual, which is found in the
431 <filename>bitbake/doc/manual</filename> directory of the
432 Source Directory.</para>
433 <para>The build process supports several types of images to satisfy different needs.
434 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
435 the Yocto Project Reference Manual for information on supported images.
436 </para></listitem>
437 <listitem><para><emphasis>Make changes to the kernel source code if
438 applicable</emphasis>: Modifying the kernel does not always mean directly
439 changing source files.
440 However, if you have to do this, you make the changes to the files in the
441 Build directory.</para></listitem>
442 <listitem><para><emphasis>Make kernel configuration changes
443 if applicable</emphasis>:
444 If your situation calls for changing the kernel's configuration, you can
445 use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
446 to enable and disable kernel configurations.
447 Using the script lets you interactively set up kernel configurations.
448 Using <filename>menuconfig</filename> allows you to interactively develop and test the
449 configuration changes you are making to the kernel.
450 When saved, changes using <filename>menuconfig</filename> update the kernel's
451 <filename>.config</filename> file.
452 Try to resist the temptation of directly editing the <filename>.config</filename>
453 file found in the Build Directory at
454 <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
455 Doing so, can produce unexpected results when the OpenEmbedded build system
456 regenerates the configuration file.</para>
457 <para>Once you are satisfied with the configuration changes made using
458 <filename>menuconfig</filename>, you can directly compare the
459 <filename>.config</filename> file against a saved original and gather those
460 changes into a config fragment to be referenced from within the kernel's
461 <filename>.bbappend</filename> file.</para></listitem>
462 <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
463 Rebuilding the kernel image applies your changes.</para></listitem>
464 </orderedlist>
465 </para>
466 </section>
467 </section>
468</section>
469
470<section id='application-development-workflow'>
471 <title>Application Development Workflow</title>
472
473 <para>
474 Application development involves creating an application that you want
475 to run on your target hardware, which is running a kernel image created using the
476 OpenEmbedded build system.
477 The Yocto Project provides an
478 <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro-section'>Application Development Toolkit (ADT)</ulink>
479 and stand-alone
480 <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink>
481 that facilitate quick development and integration of your application into its runtime environment.
482 Using the ADT and toolchains, you can compile and link your application.
483 You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
484 If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE,
485 you can use an Eclipse Yocto Plug-in to
486 allow you to develop, deploy, and test your application all from within Eclipse.
487 </para>
488
489 <para>
490 While we strongly suggest using the ADT to develop your application, this option might not
491 be best for you.
492 If this is the case, you can still use pieces of the Yocto Project for your development process.
493 However, because the process can vary greatly, this manual does not provide detail on the process.
494 </para>
495
496 <section id='workflow-using-the-adt-and-eclipse'>
497 <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
498
499 <para>
500 To help you understand how application development works using the ADT, this section
501 provides an overview of the general development process and a detailed example of the process
502 as it is used from within the Eclipse IDE.
503 </para>
504
505 <para>
506 The following illustration and list summarize the application development general workflow.
507 </para>
508
509 <para>
510 <imagedata fileref="figures/app-dev-flow.png"
511 width="7in" depth="8in" align="center" scale="100" />
512 </para>
513
514 <para>
515 <orderedlist>
516 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
517 See
518 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
519 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
520 in the Yocto Project Quick Start for requirements.</para></listitem>
521 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
522 You must have a target kernel image that has been built using the OpenEmbedded
523 build system.</para>
524 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
525 architecture and where you are going to run the image while you develop your application
526 (QEMU or real hardware), the area from which you get the image differs.
527 <itemizedlist>
528 <listitem><para>Download the image from
529 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
530 if your target architecture is supported and you are going to develop
531 and test your application on actual hardware.</para></listitem>
532 <listitem><para>Download the image from
533 <ulink url='&YOCTO_QEMU_DL_URL;'>
534 <filename>machines/qemu</filename></ulink> if your target architecture is supported
535 and you are going to develop and test your application using the QEMU
536 emulator.</para></listitem>
537 <listitem><para>Build your image if you cannot find a pre-built image that matches
538 your target architecture.
539 If your target architecture is similar to a supported architecture, you can
540 modify the kernel image before you build it.
541 See the
542 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
543 section for an example.</para></listitem>
544 </itemizedlist></para>
545 <para>For information on pre-built kernel image naming schemes for images
546 that can run on the QEMU emulator, see the
547 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
548 section in the Yocto Project Quick Start.</para></listitem>
549 <listitem><para><emphasis>Install the ADT</emphasis>:
550 The ADT provides a target-specific cross-development toolchain, the root filesystem,
551 the QEMU emulator, and other tools that can help you develop your application.
552 While it is possible to get these pieces separately, the ADT Installer provides an
553 easy, inclusive method.
554 You can get these pieces by running an ADT installer script, which is configurable.
555 For information on how to install the ADT, see the
556 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
557 section
558 in the Yocto Project Application Developer's Guide.</para></listitem>
559 <listitem><para><emphasis>If applicable, secure the target root filesystem
560 and the Cross-development toolchain</emphasis>:
561 If you choose not to install the ADT using the ADT Installer,
562 you need to find and download the appropriate root filesystem and
563 the cross-development toolchain.</para>
564 <para>You can find the tarballs for the root filesystem in the same area used
565 for the kernel image.
566 Depending on the type of image you are running, the root filesystem you need differs.
567 For example, if you are developing an application that runs on an image that
568 supports Sato, you need to get a root filesystem that supports Sato.</para>
569 <para>You can find the cross-development toolchains at
570 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
571 Be sure to get the correct toolchain for your development host and your
572 target architecture.
573 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
574 section in the Yocto Project Application Developer's Guide for information
575 and the
576 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
577 in the Yocto Project Quick Start for information on finding and installing
578 the correct toolchain based on your host development system and your target
579 architecture.
580 </para></listitem>
581 <listitem><para><emphasis>Create and build your application</emphasis>:
582 At this point, you need to have source files for your application.
583 Once you have the files, you can use the Eclipse IDE to import them and build the
584 project.
585 If you are not using Eclipse, you need to use the cross-development tools you have
586 installed to create the image.</para></listitem>
587 <listitem><para><emphasis>Deploy the image with the application</emphasis>:
588 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
589 QEMU through the project's preferences.
590 If you are not using the Eclipse IDE, then you need to deploy the application
591 to the hardware using other methods.
592 Or, if you are using QEMU, you need to use that tool and load your image in for testing.
593 </para></listitem>
594 <listitem><para><emphasis>Test and debug the application</emphasis>:
595 Once your application is deployed, you need to test it.
596 Within the Eclipse IDE, you can use the debugging environment along with the
597 set of user-space tools installed along with the ADT to debug your application.
598 Of course, the same user-space tools are available separately if you choose
599 not to use the Eclipse IDE.</para></listitem>
600 </orderedlist>
601 </para>
602 </section>
603
604 <section id='adt-eclipse'>
605 <title>Working Within Eclipse</title>
606
607 <para>
608 The Eclipse IDE is a popular development environment and it fully
609 supports development using the Yocto Project.
610 <note>
611 This release of the Yocto Project supports both the Kepler
612 and Juno versions of the Eclipse IDE.
613 Thus, the following information provides setup information for
614 both versions.
615 </note>
616 </para>
617
618 <para>
619 When you install and configure the Eclipse Yocto Project Plug-in
620 into the Eclipse IDE, you maximize your Yocto Project experience.
621 Installing and configuring the Plug-in results in an environment
622 that has extensions specifically designed to let you more easily
623 develop software.
624 These extensions allow for cross-compilation, deployment, and
625 execution of your output into a QEMU emulation session as well as
626 actual target hardware.
627 You can also perform cross-debugging and profiling.
628 The environment also supports a suite of tools that allows you
629 to perform remote profiling, tracing, collection of power data,
630 collection of latency data, and collection of performance data.
631 </para>
632
633 <para>
634 This section describes how to install and configure the Eclipse IDE
635 Yocto Plug-in and how to use it to develop your application.
636 </para>
637
638 <section id='setting-up-the-eclipse-ide'>
639 <title>Setting Up the Eclipse IDE</title>
640
641 <para>
642 To develop within the Eclipse IDE, you need to do the following:
643 <orderedlist>
644 <listitem><para>Install the optimal version of the Eclipse
645 IDE.</para></listitem>
646 <listitem><para>Configure the Eclipse IDE.
647 </para></listitem>
648 <listitem><para>Install the Eclipse Yocto Plug-in.
649 </para></listitem>
650 <listitem><para>Configure the Eclipse Yocto Plug-in.
651 </para></listitem>
652 </orderedlist>
653 <note>
654 Do not install Eclipse from your distribution's package
655 repository.
656 Be sure to install Eclipse from the official Eclipse
657 download site as directed in the next section.
658 </note>
659 </para>
660
661 <section id='installing-eclipse-ide'>
662 <title>Installing the Eclipse IDE</title>
663
664 <para>
665 It is recommended that you have the Kepler 4.3 version of
666 the Eclipse IDE installed on your development system.
667 However, if you currently have the Juno 4.2 version
668 installed and you do not want to upgrade the IDE, you can
669 configure Juno to work with the Yocto Project.
670 </para>
671
672 <para>
673 If you do not have the Kepler 4.3 Eclipse IDE installed, you
674 can find the tarball at
675 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
676 From that site, choose the Eclipse Standard 4.3 version
677 particular to your development host.
678 This version contains the Eclipse Platform, the Java
679 Development Tools (JDT), and the Plug-in Development
680 Environment.
681 </para>
682
683 <para>
684 Once you have downloaded the tarball, extract it into a
685 clean directory.
686 For example, the following commands unpack and install the
687 downloaded Eclipse IDE tarball into a clean directory
688 using the default name <filename>eclipse</filename>:
689 <literallayout class='monospaced'>
690 $ cd ~
691 $ tar -xzvf ~/Downloads/eclipse-standard-kepler-R-linux-gtk-x86_64.tar.gz
692 </literallayout>
693 </para>
694 </section>
695
696 <section id='configuring-the-eclipse-ide'>
697 <title>Configuring the Eclipse IDE</title>
698
699 <para>
700 This section presents the steps needed to configure the
701 Eclipse IDE.
702 </para>
703
704 <para>
705 Before installing and configuring the Eclipse Yocto Plug-in,
706 you need to configure the Eclipse IDE.
707 Follow these general steps:
708 <orderedlist>
709 <listitem><para>Start the Eclipse IDE.</para></listitem>
710 <listitem><para>Make sure you are in your Workbench and
711 select "Install New Software" from the "Help"
712 pull-down menu.</para></listitem>
713 <listitem><para>Select
714 <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
715 from the "Work with:" pull-down menu.
716 <note>
717 For Juno, select
718 <filename>Juno - &ECLIPSE_JUNO_URL;</filename>
719 </note>
720 </para></listitem>
721 <listitem><para>Expand the box next to "Linux Tools"
722 and select the
723 <filename>LTTng - Linux Tracing Toolkit</filename>
724 boxes.</para></listitem>
725 <listitem><para>Expand the box next to "Mobile and
726 Device Development" and select the following boxes:
727 <itemizedlist>
728 <listitem><para><filename>C/C++ Remote Launch</filename></para></listitem>
729 <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
730 <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
731 <listitem><para><filename>Target Management Terminal</filename></para></listitem>
732 <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
733 <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
734 </itemizedlist></para></listitem>
735 <listitem><para>Expand the box next to "Programming
736 Languages" and select the
737 <filename>Autotools Support for CDT</filename>
738 and <filename>C/C++ Development Tools</filename>
739 boxes.</para></listitem>
740 <listitem><para>Complete the installation and restart
741 the Eclipse IDE.</para></listitem>
742 </orderedlist>
743 </para>
744 </section>
745
746 <section id='installing-the-eclipse-yocto-plug-in'>
747 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
748
749 <para>
750 You can install the Eclipse Yocto Plug-in into the Eclipse
751 IDE one of two ways: use the Yocto Project's Eclipse
752 Update site to install the pre-built plug-in or build and
753 install the plug-in from the latest source code.
754 </para>
755
756 <section id='new-software'>
757 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
758
759 <para>
760 To install the Eclipse Yocto Plug-in from the update
761 site, follow these steps:
762 <orderedlist>
763 <listitem><para>Start up the Eclipse IDE.
764 </para></listitem>
765 <listitem><para>In Eclipse, select "Install New
766 Software" from the "Help" menu.
767 </para></listitem>
768 <listitem><para>Click "Add..." in the "Work with:"
769 area.</para></listitem>
770 <listitem><para>Enter
771 <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
772 in the URL field and provide a meaningful name
773 in the "Name" field.
774 <note>
775 If you are using Juno, use
776 <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename>
777 in the URL field.
778 </note></para></listitem>
779 <listitem><para>Click "OK" to have the entry added
780 to the "Work with:" drop-down list.
781 </para></listitem>
782 <listitem><para>Select the entry for the plug-in
783 from the "Work with:" drop-down list.
784 </para></listitem>
785 <listitem><para>Check the boxes next to
786 <filename>Yocto Project ADT Plug-in</filename>,
787 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
788 and
789 <filename>Yocto Project Documentation plug-in</filename>.
790 </para></listitem>
791 <listitem><para>Complete the remaining software
792 installation steps and then restart the Eclipse
793 IDE to finish the installation of the plug-in.
794 </para></listitem>
795 </orderedlist>
796 </para>
797 </section>
798
799 <section id='zip-file-method'>
800 <title>Installing the Plug-in Using the Latest Source Code</title>
801
802 <para>
803 To install the Eclipse Yocto Plug-in from the latest
804 source code, follow these steps:
805 <orderedlist>
806 <listitem><para>Be sure your development system
807 is not using OpenJDK to build the plug-in
808 by doing the following:
809 <orderedlist>
810 <listitem><para>Use the Oracle JDK.
811 If you don't have that, go to
812 <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
813 and download the appropriate tarball
814 for your development system and
815 extract it into your home directory.
816 </para></listitem>
817 <listitem><para>In the shell you are going
818 to do your work, export the location of
819 the Oracle Java as follows:
820 <literallayout class='monospaced'>
821 export PATH=~/jdk1.7.0_40/bin:$PATH
822 </literallayout></para></listitem>
823 </orderedlist></para></listitem>
824 <listitem><para>In the same shell, create a Git
825 repository with:
826 <literallayout class='monospaced'>
827 $ cd ~
828 $ git clone git://git.yoctoproject.org/eclipse-poky-kepler
829 </literallayout>
830 <note>
831 If you are using Juno, the repository is
832 located at
833 <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>.
834 </note>
835 For this example, the repository is named
836 <filename>~/eclipse-poky-kepler</filename>.
837 </para></listitem>
838 <listitem><para>Change to the directory where you
839 set up the Git repository:
840 <literallayout class='monospaced'>
841 $ cd ~/eclipse-poky-kepler
842 </literallayout></para></listitem>
843 <listitem><para>Be sure you are in the right branch
844 for your Git repository.
845 For this release set the branch to
846 <filename>&DISTRO_NAME;</filename>:
847 <literallayout class='monospaced'>
848 $ git checkout &DISTRO_NAME;
849 </literallayout></para></listitem>
850 <listitem><para>Change to the
851 <filename>scripts</filename>
852 directory within the Git repository:
853 <literallayout class='monospaced'>
854 $ cd scripts
855 </literallayout></para></listitem>
856 <listitem><para>Set up the local build environment
857 by running the setup script:
858 <literallayout class='monospaced'>
859 $ ./setup.sh
860 </literallayout></para></listitem>
861 <listitem><para>When the script finishes execution,
862 it prompts you with instructions on how to run
863 the <filename>build.sh</filename> script, which
864 is also in the <filename>scripts</filename> of
865 the Git repository created earlier.
866 </para></listitem>
867 <listitem><para>Run the <filename>build.sh</filename> script
868 as directed.
869 Be sure to provide the name of the Git branch
870 along with the Yocto Project release you are
871 using.
872 Here is an example that uses the
873 <filename>&DISTRO_NAME;</filename> branch:
874 <literallayout class='monospaced'>
875 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
876 </literallayout>
877 After running the script, the file
878 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
879 is in the current directory.</para></listitem>
880 <listitem><para>If necessary, start the Eclipse IDE
881 and be sure you are in the Workbench.
882 </para></listitem>
883 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
884 </para></listitem>
885 <listitem><para>Click "Add".</para></listitem>
886 <listitem><para>Provide anything you want in the
887 "Name" field.</para></listitem>
888 <listitem><para>Click "Archive" and browse to the
889 ZIP file you built in step seven.
890 This ZIP file should not be "unzipped", and must
891 be the <filename>*archive.zip</filename> file
892 created by running the
893 <filename>build.sh</filename> script.
894 </para></listitem>
895 <listitem><para>Click through the "Okay" buttons.
896 </para></listitem>
897 <listitem><para>Check the boxes
898 in the installation window and complete
899 the installation.</para></listitem>
900 <listitem><para>Restart the Eclipse IDE if
901 necessary.</para></listitem>
902 </orderedlist>
903 </para>
904
905 <para>
906 At this point you should be able to configure the
907 Eclipse Yocto Plug-in as described in the
908 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
909 section.</para>
910 </section>
911 </section>
912
913 <section id='configuring-the-eclipse-yocto-plug-in'>
914 <title>Configuring the Eclipse Yocto Plug-in</title>
915
916 <para>
917 Configuring the Eclipse Yocto Plug-in involves setting the
918 Cross Compiler options and the Target options.
919 The configurations you choose become the default settings
920 for all projects.
921 You do have opportunities to change them later when
922 you configure the project (see the following section).
923 </para>
924
925 <para>
926 To start, you need to do the following from within the
927 Eclipse IDE:
928 <itemizedlist>
929 <listitem><para>Choose "Preferences" from the
930 "Windows" menu to display the Preferences Dialog.
931 </para></listitem>
932 <listitem><para>Click "Yocto Project ADT".
933 </para></listitem>
934 </itemizedlist>
935 </para>
936
937 <section id='configuring-the-cross-compiler-options'>
938 <title>Configuring the Cross-Compiler Options</title>
939
940 <para>
941 To configure the Cross Compiler Options, you must select
942 the type of toolchain, point to the toolchain, specify
943 the sysroot location, and select the target
944 architecture.
945 <itemizedlist>
946 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
947 Choose between
948 <filename>Standalone pre-built toolchain</filename>
949 and
950 <filename>Build system derived toolchain</filename>
951 for Cross Compiler Options.
952 <itemizedlist>
953 <listitem><para><emphasis>
954 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
955 Select this mode when you are using
956 a stand-alone cross-toolchain.
957 For example, suppose you are an
958 application developer and do not
959 need to build a target image.
960 Instead, you just want to use an
961 architecture-specific toolchain on
962 an existing kernel and target root
963 filesystem.</para></listitem>
964 <listitem><para><emphasis>
965 <filename>Build System Derived Toolchain:</filename></emphasis>
966 Select this mode if the
967 cross-toolchain has been installed
968 and built as part of the
969 <link linkend='build-directory'>Build Directory</link>.
970 When you select
971 <filename>Build system derived toolchain</filename>,
972 you are using the toolchain bundled
973 inside the Build Directory.
974 </para></listitem>
975 </itemizedlist>
976 </para></listitem>
977 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
978 If you are using a stand-alone pre-built
979 toolchain, you should be pointing to where it is
980 installed.
981 If you used the ADT Installer script and
982 accepted the default installation directory, the
983 toolchain will be installed in the
984 <filename>&YOCTO_ADTPATH_DIR;</filename>
985 directory.
986 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>"
987 and
988 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
989 in the Yocto Project Application Developer's
990 Guide describe how to install a stand-alone
991 cross-toolchain.</para>
992 <para>If you are using a system-derived
993 toolchain, the path you provide for the
994 <filename>Toolchain Root Location</filename>
995 field is the
996 <link linkend='build-directory'>Build Directory</link>.
997 See the
998 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>"
999 section in the Yocto Project Application
1000 Developer's Guide for information on how to
1001 install the toolchain into the Build
1002 Directory.</para></listitem>
1003 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
1004 This location is where the root filesystem for
1005 the target hardware resides.
1006 If you used the ADT Installer script and
1007 accepted the default installation directory,
1008 then the location is
1009 <filename>/opt/poky/&lt;release&gt;</filename>.
1010 Additionally, when you use the ADT Installer
1011 script, the same location is used for the QEMU
1012 user-space tools and the NFS boot process.
1013 </para>
1014 <para>If you used either of the other two
1015 methods to install the toolchain or did not
1016 accept the ADT Installer script's default
1017 installation directory, then the location of
1018 the sysroot filesystem depends on where you
1019 separately extracted and installed the
1020 filesystem.</para>
1021 <para>For information on how to install the
1022 toolchain and on how to extract and install the
1023 sysroot filesystem, see the
1024 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" section.
1025 </para></listitem>
1026 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1027 The target architecture is the type of hardware
1028 you are going to use or emulate.
1029 Use the pull-down
1030 <filename>Target Architecture</filename> menu
1031 to make your selection.
1032 The pull-down menu should have the supported
1033 architectures.
1034 If the architecture you need is not listed in
1035 the menu, you will need to build the image.
1036 See the
1037 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1038 section of the Yocto Project Quick Start for
1039 more information.</para></listitem>
1040 </itemizedlist>
1041 </para>
1042 </section>
1043
1044 <section id='configuring-the-target-options'>
1045 <title>Configuring the Target Options</title>
1046
1047 <para>
1048 You can choose to emulate hardware using the QEMU
1049 emulator, or you can choose to run your image on actual
1050 hardware.
1051 <itemizedlist>
1052 <listitem><para><emphasis><filename>QEMU:</filename></emphasis>
1053 Select this option if you will be using the
1054 QEMU emulator.
1055 If you are using the emulator, you also need to
1056 locate the kernel and specify any custom
1057 options.</para>
1058 <para>If you selected
1059 <filename>Build system derived toolchain</filename>,
1060 the target kernel you built will be located in
1061 the Build Directory in
1062 <filename>tmp/deploy/images/&lt;machine&gt;</filename>
1063 directory.
1064 If you selected
1065 <filename>Standalone pre-built toolchain</filename>,
1066 the pre-built image you downloaded is located
1067 in the directory you specified when you
1068 downloaded the image.</para>
1069 <para>Most custom options are for advanced QEMU
1070 users to further customize their QEMU instance.
1071 These options are specified between paired
1072 angled brackets.
1073 Some options must be specified outside the
1074 brackets.
1075 In particular, the options
1076 <filename>serial</filename>,
1077 <filename>nographic</filename>, and
1078 <filename>kvm</filename> must all be outside the
1079 brackets.
1080 Use the <filename>man qemu</filename> command
1081 to get help on all the options and their use.
1082 The following is an example:
1083 <literallayout class='monospaced'>
1084 serial ‘&lt;-m 256 -full-screen&gt;’
1085 </literallayout></para>
1086 <para>
1087 Regardless of the mode, Sysroot is already
1088 defined as part of the Cross-Compiler Options
1089 configuration in the
1090 <filename>Sysroot Location:</filename> field.
1091 </para></listitem>
1092 <listitem><para><emphasis><filename>External HW:</filename></emphasis>
1093 Select this option if you will be using actual
1094 hardware.</para></listitem>
1095 </itemizedlist>
1096 </para>
1097
1098 <para>
1099 Click the "OK" to save your plug-in configurations.
1100 </para>
1101 </section>
1102 </section>
1103 </section>
1104
1105 <section id='creating-the-project'>
1106 <title>Creating the Project</title>
1107
1108 <para>
1109 You can create two types of projects: Autotools-based, or
1110 Makefile-based.
1111 This section describes how to create Autotools-based projects
1112 from within the Eclipse IDE.
1113 For information on creating Makefile-based projects in a
1114 terminal window, see the section
1115 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1116 in the Yocto Project Application Developer's Guide.
1117 </para>
1118
1119 <para>
1120 To create a project based on a Yocto template and then display
1121 the source code, follow these steps:
1122 <orderedlist>
1123 <listitem><para>Select "Project" from the "File -> New" menu.
1124 </para></listitem>
1125 <listitem><para>Double click <filename>CC++</filename>.
1126 </para></listitem>
1127 <listitem><para>Double click <filename>C Project</filename>
1128 to create the project.</para></listitem>
1129 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.
1130 </para></listitem>
1131 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1132 This is an Autotools-based project based on a Yocto
1133 template.</para></listitem>
1134 <listitem><para>Put a name in the <filename>Project name:</filename>
1135 field.
1136 Do not use hyphens as part of the name.
1137 </para></listitem>
1138 <listitem><para>Click "Next".</para></listitem>
1139 <listitem><para>Add information in the
1140 <filename>Author</filename> and
1141 <filename>Copyright notice</filename> fields.
1142 </para></listitem>
1143 <listitem><para>Be sure the <filename>License</filename>
1144 field is correct.</para></listitem>
1145 <listitem><para>Click "Finish".</para></listitem>
1146 <listitem><para>If the "open perspective" prompt appears,
1147 click "Yes" so that you in the C/C++ perspective.
1148 </para></listitem>
1149 <listitem><para>The left-hand navigation pane shows your
1150 project.
1151 You can display your source by double clicking the
1152 project's source file.</para></listitem>
1153 </orderedlist>
1154 </para>
1155 </section>
1156
1157 <section id='configuring-the-cross-toolchains'>
1158 <title>Configuring the Cross-Toolchains</title>
1159
1160 <para>
1161 The earlier section,
1162 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
1163 sets up the default project configurations.
1164 You can override these settings for a given project by following
1165 these steps:
1166 <orderedlist>
1167 <listitem><para>Select "Change Yocto Project Settings" from
1168 the "Project" menu.
1169 This selection brings up the Yocto Project Settings
1170 Dialog and allows you to make changes specific to an
1171 individual project.</para>
1172 <para>By default, the Cross Compiler Options and Target
1173 Options for a project are inherited from settings you
1174 provide using the Preferences Dialog as described
1175 earlier in the
1176 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
1177 The Yocto Project Settings Dialog allows you to override
1178 those default settings for a given project.
1179 </para></listitem>
1180 <listitem><para>Make your configurations for the project
1181 and click "OK".
1182 If you are running the Juno version of Eclipse, you can
1183 skip down to the next section where you build the
1184 project.
1185 If you are not working with Juno, you need to reconfigure the
1186 project as described in the next step.
1187 </para></listitem>
1188 <listitem><para>Select "Reconfigure Project" from the
1189 "Project" menu.
1190 This selection reconfigures the project by running
1191 <filename>autogen.sh</filename> in the workspace for
1192 your project.
1193 The script also runs <filename>libtoolize</filename>,
1194 <filename>aclocal</filename>,
1195 <filename>autoconf</filename>,
1196 <filename>autoheader</filename>,
1197 <filename>automake --a</filename>, and
1198 <filename>./configure</filename>.
1199 Click on the "Console" tab beneath your source code to
1200 see the results of reconfiguring your project.
1201 </para></listitem>
1202 </orderedlist>
1203 </para>
1204 </section>
1205
1206 <section id='building-the-project'>
1207 <title>Building the Project</title>
1208
1209 <para>
1210 To build the project in Juno, right click on the project in
1211 the navigator pane and select "Build Project".
1212 If you are not running Juno, select "Build Project" from the
1213 "Project" menu.
1214 The console should update and you can note the cross-compiler
1215 you are using.
1216 </para>
1217 </section>
1218
1219 <section id='starting-qemu-in-user-space-nfs-mode'>
1220 <title>Starting QEMU in User-Space NFS Mode</title>
1221
1222 <para>
1223 To start the QEMU emulator from within Eclipse, follow these
1224 steps:
1225 <orderedlist>
1226 <listitem><para>Expose and select "External Tools" from
1227 the "Run" menu.
1228 Your image should appear as a selectable menu item.
1229 </para></listitem>
1230 <listitem><para>Select your image from the menu to launch
1231 the emulator in a new window.</para></listitem>
1232 <listitem><para>If needed, enter your host root password in
1233 the shell window at the prompt.
1234 This sets up a <filename>Tap 0</filename> connection
1235 needed for running in user-space NFS mode.
1236 </para></listitem>
1237 <listitem><para>Wait for QEMU to launch.</para></listitem>
1238 <listitem><para>Once QEMU launches, you can begin operating
1239 within that environment.
1240 For example, you could determine the IP Address
1241 for the user-space NFS by using the
1242 <filename>ifconfig</filename> command.</para></listitem>
1243 </orderedlist>
1244 </para>
1245 </section>
1246
1247 <section id='deploying-and-debugging-the-application'>
1248 <title>Deploying and Debugging the Application</title>
1249
1250 <para>
1251 Once the QEMU emulator is running the image, you can deploy
1252 your application using the Eclipse IDE and use then use
1253 the emulator to perform debugging.
1254 Follow these steps to deploy the application.
1255 <orderedlist>
1256 <listitem><para>Select "Debug Configurations..." from the
1257 "Run" menu.</para></listitem>
1258 <listitem><para>In the left area, expand
1259 <filename>C/C++Remote Application</filename>.
1260 </para></listitem>
1261 <listitem><para>Locate your project and select it to bring
1262 up a new tabbed view in the Debug Configurations Dialog.
1263 </para></listitem>
1264 <listitem><para>Enter the absolute path into which you want
1265 to deploy the application.
1266 Use the "Remote Absolute File Path for
1267 C/C++Application:" field.
1268 For example, enter
1269 <filename>/usr/bin/&lt;programname&gt;</filename>.
1270 </para></listitem>
1271 <listitem><para>Click on the "Debugger" tab to see the
1272 cross-tool debugger you are using.</para></listitem>
1273 <listitem><para>Click on the "Main" tab.</para></listitem>
1274 <listitem><para>Create a new connection to the QEMU instance
1275 by clicking on "new".</para></listitem>
1276 <listitem><para>Select <filename>TCF</filename>, which means
1277 Target Communication Framework.</para></listitem>
1278 <listitem><para>Click "Next".</para></listitem>
1279 <listitem><para>Clear out the "host name" field and enter
1280 the IP Address determined earlier.</para></listitem>
1281 <listitem><para>Click "Finish" to close the
1282 New Connections Dialog.</para></listitem>
1283 <listitem><para>Use the drop-down menu now in the
1284 "Connection" field and pick the IP Address you entered.
1285 </para></listitem>
1286 <listitem><para>Click "Run" to bring up a login screen
1287 and login.</para></listitem>
1288 <listitem><para>Accept the debug perspective.
1289 </para></listitem>
1290 </orderedlist>
1291 </para>
1292 </section>
1293
1294 <section id='running-user-space-tools'>
1295 <title>Running User-Space Tools</title>
1296
1297 <para>
1298 As mentioned earlier in the manual, several tools exist that
1299 enhance your development experience.
1300 These tools are aids in developing and debugging applications
1301 and images.
1302 You can run these user-space tools from within the Eclipse
1303 IDE through the "YoctoTools" menu.
1304 </para>
1305
1306 <para>
1307 Once you pick a tool, you need to configure it for the remote
1308 target.
1309 Every tool needs to have the connection configured.
1310 You must select an existing TCF-based RSE connection to the
1311 remote target.
1312 If one does not exist, click "New" to create one.
1313 </para>
1314
1315 <para>
1316 Here are some specifics about the remote tools:
1317 <itemizedlist>
1318 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
1319 Selecting this tool causes the
1320 <filename>oprofile-server</filename> on the remote
1321 target to launch on the local host machine.
1322 The <filename>oprofile-viewer</filename> must be
1323 installed on the local host machine and the
1324 <filename>oprofile-server</filename> must be installed
1325 on the remote target, respectively, in order to use.
1326 You must compile and install the
1327 <filename>oprofile-viewer</filename> from the source
1328 code on your local host machine.
1329 Furthermore, in order to convert the target's sample
1330 format data into a form that the host can use, you must
1331 have OProfile version 0.9.4 or greater installed on the
1332 host.</para>
1333 <para>You can locate both the viewer and server from
1334 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1335 You can also find more information on setting up and
1336 using this tool in the
1337 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
1338 section of the Yocto Project Profiling and Tracing
1339 Manual.
1340 <note>The <filename>oprofile-server</filename> is
1341 installed by default on the
1342 <filename>core-image-sato-sdk</filename> image.</note>
1343 </para></listitem>
1344 <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
1345 Selecting this tool transfers the remote target's
1346 <filename>Lttng</filename> tracing data back to the
1347 local host machine and uses the Lttng Eclipse plug-in
1348 to graphically display the output.
1349 For information on how to use Lttng to trace an
1350 application,
1351 see <ulink url='http://lttng.org/documentation'></ulink>
1352 and the
1353 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1354 section, which is in the Yocto Project Profiling and
1355 Tracing Manual.
1356 <note>Do not use
1357 <filename>Lttng-user space (legacy)</filename> tool.
1358 This tool no longer has any upstream support.</note>
1359 </para>
1360 <para>Before you use the
1361 <filename>Lttng2.0 ust trace import</filename> tool,
1362 you need to setup the Lttng Eclipse plug-in and create a
1363 Tracing project.
1364 Do the following:
1365 <orderedlist>
1366 <listitem><para>Select "Open Perspective" from the
1367 "Window" menu and then select "Tracing".
1368 </para></listitem>
1369 <listitem><para>Click "OK" to change the Eclipse
1370 perspective into the Tracing perspective.
1371 </para></listitem>
1372 <listitem><para>Create a new Tracing project by
1373 selecting "Project" from the "File -> New" menu.
1374 </para></listitem>
1375 <listitem><para>Choose "Tracing Project" from the
1376 "Tracing" menu.
1377 </para></listitem>
1378 <listitem><para>Generate your tracing data on the
1379 remote target.</para></listitem>
1380 <listitem><para>Select "Lttng2.0 ust trace import"
1381 from the "Yocto Project Tools" menu to
1382 start the data import process.</para></listitem>
1383 <listitem><para>Specify your remote connection name.
1384 </para></listitem>
1385 <listitem><para>For the Ust directory path, specify
1386 the location of your remote tracing data.
1387 Make sure the location ends with
1388 <filename>ust</filename> (e.g.
1389 <filename>/usr/mysession/ust</filename>).
1390 </para></listitem>
1391 <listitem><para>Click "OK" to complete the import
1392 process.
1393 The data is now in the local tracing project
1394 you created.</para></listitem>
1395 <listitem><para>Right click on the data and then use
1396 the menu to Select "Generic CTF Trace" from the
1397 "Trace Type... -> Common Trace Format" menu to
1398 map the tracing type.</para></listitem>
1399 <listitem><para>Right click the mouse and select
1400 "Open" to bring up the Eclipse Lttng Trace
1401 Viewer so you view the tracing data.
1402 </para></listitem>
1403 </orderedlist></para></listitem>
1404 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1405 Selecting this tool runs PowerTOP on the remote target
1406 machine and displays the results in a new view called
1407 PowerTOP.</para>
1408 <para>The "Time to gather data(sec):" field is the time
1409 passed in seconds before data is gathered from the
1410 remote target for analysis.</para>
1411 <para>The "show pids in wakeups list:" field corresponds
1412 to the <filename>-p</filename> argument passed to
1413 <filename>PowerTOP</filename>.</para></listitem>
1414 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1415 LatencyTOP identifies system latency, while
1416 Perf monitors the system's performance counter
1417 registers.
1418 Selecting either of these tools causes an RSE terminal
1419 view to appear from which you can run the tools.
1420 Both tools refresh the entire screen to display results
1421 while they run.
1422 For more information on setting up and using
1423 <filename>perf</filename>, see the
1424 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1425 section in the Yocto Project Profiling and Tracing
1426 Manual.
1427 </para></listitem>
1428 </itemizedlist>
1429 </para>
1430 </section>
1431
1432 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1433 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1434
1435 <para>
1436 Within the Eclipse IDE, you can create a Yocto BitBake Commander
1437 project, edit the <link linkend='metadata'>Metadata</link>, and
1438 then use
1439 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE.
1440 </para>
1441
1442 <section id='creating-the-yocto-bitbake-commander-project'>
1443 <title>Creating the Yocto BitBake Commander Project</title>
1444
1445 <para>
1446 To create a Yocto BitBake Commander project, follow these
1447 steps:
1448 <orderedlist>
1449 <listitem><para>Select "Other" from the
1450 "Window -> Open Perspective" menu
1451 and then choose "Bitbake Commander".
1452 </para></listitem>
1453 <listitem><para>Click "OK" to change the perspective to
1454 Bitbake Commander.</para></listitem>
1455 <listitem><para>Select "Project" from the "File -> New"
1456 menu to create a new Yocto
1457 Bitbake Commander project.</para></listitem>
1458 <listitem><para>Choose "New Yocto Project" from the
1459 "Yocto Project Bitbake Commander" menu and click
1460 "Next".</para></listitem>
1461 <listitem><para>Enter the Project Name and choose the
1462 Project Location.
1463 The Yocto project's Metadata files will be put under
1464 the directory
1465 <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
1466 If that directory does not exist, you need to check
1467 the "Clone from Yocto Git Repository" box, which
1468 would execute a <filename>git clone</filename>
1469 command to get the project's Metadata files.
1470 <note>
1471 Do not specify your BitBake Commander project
1472 location as your Eclipse workspace.
1473 Doing so causes an error indicating that the
1474 current project overlaps the location of
1475 another project.
1476 This error occurs even if no such project exits.
1477 </note></para></listitem>
1478 <listitem><para>Select <filename>Finish</filename> to
1479 create the project.</para></listitem>
1480 </orderedlist>
1481 </para>
1482 </section>
1483
1484 <section id='editing-the-metadata'>
1485 <title>Editing the Metadata</title>
1486
1487 <para>
1488 After you create the Yocto Bitbake Commander project, you
1489 can modify the <link linkend='metadata'>Metadata</link>
1490 files by opening them in the project.
1491 When editing recipe files (<filename>.bb</filename> files),
1492 you can view BitBake variable values and information by
1493 hovering the mouse pointer over the variable name and
1494 waiting a few seconds.
1495 </para>
1496
1497 <para>
1498 To edit the Metadata, follow these steps:
1499 <orderedlist>
1500 <listitem><para>Select your Yocto Bitbake Commander
1501 project.</para></listitem>
1502 <listitem><para>Select "BitBake Recipe" from the
1503 "File -> New -> Yocto BitBake Commander" menu
1504 to open a new recipe wizard.</para></listitem>
1505 <listitem><para>Point to your source by filling in the
1506 "SRC_URL" field.
1507 For example, you can add a recipe to your
1508 <link linkend='source-directory'>Source Directory</link>
1509 by defining "SRC_URL" as follows:
1510 <literallayout class='monospaced'>
1511 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1512 </literallayout></para></listitem>
1513 <listitem><para>Click "Populate" to calculate the
1514 archive md5, sha256, license checksum values and to
1515 auto-generate the recipe filename.</para></listitem>
1516 <listitem><para>Fill in the "Description" field.
1517 </para></listitem>
1518 <listitem><para>Be sure values for all required
1519 fields exist.</para></listitem>
1520 <listitem><para>Click "Finish".</para></listitem>
1521 </orderedlist>
1522 </para>
1523 </section>
1524
1525 <section id='biding-and-customizing-the-image-using-hob'>
1526 <title>Building and Customizing the Image Using Hob</title>
1527
1528 <para>
1529 To build and customize the image using Hob from within the
1530 Eclipse IDE, follow these steps:
1531 <orderedlist>
1532 <listitem><para>Select your Yocto Bitbake Commander
1533 project.</para></listitem>
1534 <listitem><para>Select "Launch Hob" from the "Project"
1535 menu.</para></listitem>
1536 <listitem><para>Enter the
1537 <link linkend='build-directory'>Build Directory</link>
1538 where you want to put your final images.
1539 </para></listitem>
1540 <listitem><para>Click "OK" to launch Hob.
1541 </para></listitem>
1542 <listitem><para>Use Hob to customize and build your own
1543 images.
1544 For information on Hob, see the
1545 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink>
1546 on the Yocto Project website.</para></listitem>
1547 </orderedlist>
1548 </para>
1549 </section>
1550 </section>
1551 </section>
1552
1553 <section id='workflow-using-stand-alone-cross-development-toolchains'>
1554 <title>Workflow Using Stand-Alone Cross-Development Toolchains</title>
1555
1556 <para>
1557 If you want to develop an application without prior installation
1558 of the ADT, you still can employ the
1559 <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>,
1560 the QEMU emulator, and a number of supported target image files.
1561 You just need to follow these general steps:
1562 <orderedlist>
1563 <listitem><para><emphasis>Install the cross-development
1564 toolchain for your target hardware:</emphasis>
1565 For information on how to install the toolchain, see the
1566 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1567 section in the Yocto Project Application Developer's
1568 Guide.</para></listitem>
1569 <listitem><para><emphasis>Download the Target Image:</emphasis>
1570 The Yocto Project supports several target architectures
1571 and has many pre-built kernel images and root filesystem
1572 images.</para>
1573 <para>If you are going to develop your application on
1574 hardware, go to the
1575 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
1576 download area and choose a target machine area
1577 from which to download the kernel image and root filesystem.
1578 This download area could have several files in it that
1579 support development using actual hardware.
1580 For example, the area might contain
1581 <filename>.hddimg</filename> files that combine the
1582 kernel image with the filesystem, boot loaders, and
1583 so forth.
1584 Be sure to get the files you need for your particular
1585 development process.</para>
1586 <para>If you are going to develop your application and
1587 then run and test it using the QEMU emulator, go to the
1588 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
1589 download area.
1590 From this area, go down into the directory for your
1591 target architecture (e.g. <filename>qemux86_64</filename>
1592 for an <trademark class='registered'>Intel</trademark>-based
1593 64-bit architecture).
1594 Download kernel, root filesystem, and any other files you
1595 need for your process.
1596 <note>In order to use the root filesystem in QEMU, you
1597 need to extract it.
1598 See the
1599 "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
1600 section for information on how to extract the root
1601 filesystem.</note></para></listitem>
1602 <listitem><para><emphasis>Develop and Test your
1603 Application:</emphasis> At this point, you have the tools
1604 to develop your application.
1605 If you need to separately install and use the QEMU
1606 emulator, you can go to
1607 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
1608 to download and learn about the emulator.</para></listitem>
1609 </orderedlist>
1610 </para>
1611 </section>
1612</section>
1613
1614<section id="modifying-temporary-source-code">
1615 <title>Modifying Temporary Source Code</title>
1616
1617 <para>
1618 You might
1619 find it helpful during development to modify the temporary source code used by recipes
1620 to build packages.
1621 For example, suppose you are developing a patch and you need to experiment a bit
1622 to figure out your solution.
1623 After you have initially built the package, you can iteratively tweak the
1624 source code, which is located in the
1625 <link linkend='build-directory'>Build Directory</link>, and then
1626 you can force a re-compile and quickly test your altered code.
1627 Once you settle on a solution, you can then preserve your changes in the form of
1628 patches.
1629 You can accomplish these steps all within either a
1630 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1631 <link linkend='git'>Git</link> workflow.
1632 </para>
1633
1634 <section id='finding-the-temporary-source-code'>
1635 <title>Finding the Temporary Source Code</title>
1636
1637 <para>
1638 During a build, the unpacked temporary source code used by recipes
1639 to build packages is available in the Build Directory as
1640 defined by the
1641 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
1642 Below is the default value for the <filename>S</filename> variable as defined in the
1643 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1644 <link linkend='source-directory'>Source Directory</link>:
1645 <literallayout class='monospaced'>
1646 S = ${WORKDIR}/${BP}
1647 </literallayout>
1648 You should be aware that many recipes override the <filename>S</filename> variable.
1649 For example, recipes that fetch their source from Git usually set
1650 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1651 <note>
1652 The
1653 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
1654 represents the base recipe name, which consists of the name and version:
1655 <literallayout class='monospaced'>
1656 BP = ${BPN}-${PV}
1657 </literallayout>
1658 </note>
1659 </para>
1660
1661 <para>
1662 The path to the work directory for the recipe
1663 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends
1664 on the recipe name and the architecture of the target device.
1665 For example, here is the work directory for recipes and resulting packages that are
1666 not device-dependent:
1667 <literallayout class='monospaced'>
1668 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${EXTENDPE}${PV}-${PR}
1669 </literallayout>
1670 Let's look at an example without variables.
1671 Assuming a top-level <link linkend='source-directory'>Source Directory</link>
1672 named <filename>poky</filename>
1673 and a default Build Directory of <filename>poky/build</filename>,
1674 the following is the work directory for the <filename>acl</filename> recipe that
1675 creates the <filename>acl</filename> package:
1676 <literallayout class='monospaced'>
1677 ~/poky/build/tmp/work/i586-poky-linux/acl/2.2.51-r3/
1678 </literallayout>
1679 </para>
1680
1681 <para>
1682 If your resulting package is dependent on the target device,
1683 the work directory varies slightly:
1684 <literallayout class='monospaced'>
1685 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${EXTENDPE}${PV}-${PR}
1686 </literallayout>
1687 Again, assuming top-level Source Directory named <filename>poky</filename>
1688 and a default Build Directory of <filename>poky/build</filename>, the
1689 following are the work and temporary source directories, respectively,
1690 for the <filename>acl</filename> package that is being
1691 built for a MIPS-based device:
1692 <literallayout class='monospaced'>
1693 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
1694 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2/acl-2.2.51
1695 </literallayout>
1696 </para>
1697
1698 <note>
1699 To better understand how the OpenEmbedded build system resolves directories during the
1700 build process, see the glossary entries for the
1701 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
1702 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
1703 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
1704 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
1705 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
1706 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
1707 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
1708 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>,
1709 and
1710 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
1711 variables in the Yocto Project Reference Manual.
1712 </note>
1713
1714 <para>
1715 Now that you know where to locate the directory that has the temporary source code,
1716 you can use a Quilt or Git workflow to make your edits, test the changes,
1717 and preserve the changes in the form of patches.
1718 </para>
1719 </section>
1720
1721 <section id="using-a-quilt-workflow">
1722 <title>Using a Quilt Workflow</title>
1723
1724 <para>
1725 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
1726 is a powerful tool that allows you to capture source code changes without having
1727 a clean source tree.
1728 This section outlines the typical workflow you can use to modify temporary source code,
1729 test changes, and then preserve the changes in the form of a patch all using Quilt.
1730 </para>
1731
1732 <para>
1733 Follow these general steps:
1734 <orderedlist>
1735 <listitem><para><emphasis>Find the Source Code:</emphasis>
1736 The temporary source code used by the OpenEmbedded build system is kept in the
1737 Build Directory.
1738 See the
1739 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1740 section to learn how to locate the directory that has the temporary source code for a
1741 particular package.</para></listitem>
1742 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1743 You need to be in the directory that has the temporary source code.
1744 That directory is defined by the
1745 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1746 variable.</para></listitem>
1747 <listitem><para><emphasis>Create a New Patch:</emphasis>
1748 Before modifying source code, you need to create a new patch.
1749 To create a new patch file, use <filename>quilt new</filename> as below:
1750 <literallayout class='monospaced'>
1751 $ quilt new my_changes.patch
1752 </literallayout></para></listitem>
1753 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1754 After creating the patch, you need to notify Quilt about the files
1755 you plan to edit.
1756 You notify Quilt by adding the files to the patch you just created:
1757 <literallayout class='monospaced'>
1758 $ quilt add file1.c file2.c file3.c
1759 </literallayout>
1760 </para></listitem>
1761 <listitem><para><emphasis>Edit the Files:</emphasis>
1762 Make your changes in the temporary source code to the files you added
1763 to the patch.</para></listitem>
1764 <listitem><para><emphasis>Test Your Changes:</emphasis>
1765 Once you have modified the source code, the easiest way to test your changes
1766 is by calling the <filename>compile</filename> task as shown in the following example:
1767 <literallayout class='monospaced'>
1768 $ bitbake -c compile -f &lt;name_of_package&gt;
1769 </literallayout>
1770 The <filename>-f</filename> or <filename>--force</filename>
1771 option forces the specified task to execute.
1772 If you find problems with your code, you can just keep editing and
1773 re-testing iteratively until things work as expected.
1774 <note>All the modifications you make to the temporary source code
1775 disappear once you <filename>-c clean</filename> or
1776 <filename>-c cleanall</filename> with BitBake for the package.
1777 Modifications will also disappear if you use the <filename>rm_work</filename>
1778 feature as described in the
1779 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1780 section of the Yocto Project Quick Start.
1781 </note></para></listitem>
1782 <listitem><para><emphasis>Generate the Patch:</emphasis>
1783 Once your changes work as expected, you need to use Quilt to generate the final patch that
1784 contains all your modifications.
1785 <literallayout class='monospaced'>
1786 $ quilt refresh
1787 </literallayout>
1788 At this point, the <filename>my_changes.patch</filename> file has all your edits made
1789 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1790 <filename>file3.c</filename> files.</para>
1791 <para>You can find the resulting patch file in the <filename>patches/</filename>
1792 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1793 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1794 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1795 which you can create in the same directory that holds the recipe
1796 (<filename>.bb</filename>) file or the
1797 append (<filename>.bbappend</filename>) file.
1798 Placing the patch here guarantees that the OpenEmbedded build system will find
1799 the patch.
1800 Next, add the patch into the
1801 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1802 of the recipe.
1803 Here is an example:
1804 <literallayout class='monospaced'>
1805 SRC_URI += "file://my_changes.patch"
1806 </literallayout></para></listitem>
1807 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1808 Finally, don't forget to 'bump' the
1809 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1810 value in the recipe since the resulting packages have changed.</para></listitem>
1811 </orderedlist>
1812 </para> </section>
1813
1814 <section id='using-a-git-workflow'>
1815 <title>Using a Git Workflow</title>
1816 <para>
1817 Git is an even more powerful tool that allows you to capture source code changes without having
1818 a clean source tree.
1819 This section outlines the typical workflow you can use to modify temporary source code,
1820 test changes, and then preserve the changes in the form of a patch all using Git.
1821 For general information on Git as it is used in the Yocto Project, see the
1822 "<link linkend='git'>Git</link>" section.
1823 </para>
1824
1825 <note>
1826 This workflow uses Git only for its ability to manage local changes to the source code
1827 and produce patches independent of any version control system used with the Yocto Project.
1828 </note>
1829
1830 <para>
1831 Follow these general steps:
1832 <orderedlist>
1833 <listitem><para><emphasis>Find the Source Code:</emphasis>
1834 The temporary source code used by the OpenEmbedded build system is kept in the
1835 Build Directory.
1836 See the
1837 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1838 section to learn how to locate the directory that has the temporary source code for a
1839 particular package.</para></listitem>
1840 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1841 You need to be in the directory that has the temporary source code.
1842 That directory is defined by the
1843 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1844 variable.</para></listitem>
1845 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
1846 If the recipe you are working with does not use a Git fetcher,
1847 you need to set up a Git repository as follows:
1848 <literallayout class='monospaced'>
1849 $ git init
1850 $ git add *
1851 $ git commit -m "initial revision"
1852 </literallayout>
1853 The above Git commands initialize a Git repository that is based on the
1854 files in your current working directory, stage all the files, and commit
1855 the files.
1856 At this point, your Git repository is aware of all the source code files.
1857 Any edits you now make to files can be committed later and will be tracked by
1858 Git.</para></listitem>
1859 <listitem><para><emphasis>Edit the Files:</emphasis>
1860 Make your changes to the temporary source code.</para></listitem>
1861 <listitem><para><emphasis>Test Your Changes:</emphasis>
1862 Once you have modified the source code, the easiest way to test your changes
1863 is by calling the <filename>compile</filename> task as shown in the following example:
1864 <literallayout class='monospaced'>
1865 $ bitbake -c compile -f &lt;name_of_package&gt;
1866 </literallayout>
1867 The <filename>-f</filename> or <filename>--force</filename>
1868 option forces the specified task to execute.
1869 If you find problems with your code, you can just keep editing and
1870 re-testing iteratively until things work as expected.
1871 <note>All the modifications you make to the temporary source code
1872 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
1873 or <filename>-c cleanall</filename> with BitBake for the package.
1874 Modifications will also disappear if you use the <filename>rm_work</filename>
1875 feature as described in the
1876 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1877 section of the Yocto Project Quick Start.
1878 </note></para></listitem>
1879 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1880 Use the <filename>git status</filename> command to see what files you have actually edited.
1881 The ability to have Git track the files you have changed is an advantage that this
1882 workflow has over the Quilt workflow.
1883 Here is the Git command to list your changed files:
1884 <literallayout class='monospaced'>
1885 $ git status
1886 </literallayout></para></listitem>
1887 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1888 Use the <filename>git add</filename> command to stage the changed files so they
1889 can be committed as follows:
1890 <literallayout class='monospaced'>
1891 $ git add file1.c file2.c file3.c
1892 </literallayout></para></listitem>
1893 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1894 Use the <filename>git commit</filename> command to commit the changes to the
1895 local repository.
1896 Once you have committed the files, you can use the <filename>git log</filename>
1897 command to see your changes:
1898 <literallayout class='monospaced'>
1899 $ git commit -m "&lt;commit-summary-message&gt;"
1900 $ git log
1901 </literallayout>
1902 <note>The name of the patch file created in the next step is based on your
1903 <filename>commit-summary-message</filename>.</note></para></listitem>
1904 <listitem><para><emphasis>Generate the Patch:</emphasis>
1905 Once the changes are committed, use the <filename>git format-patch</filename>
1906 command to generate a patch file:
1907 <literallayout class='monospaced'>
1908 $ git format-patch -1
1909 </literallayout>
1910 Specifying "-1" causes Git to generate the
1911 patch file for the most recent commit.</para>
1912 <para>At this point, the patch file has all your edits made
1913 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1914 <filename>file3.c</filename> files.
1915 You can find the resulting patch file in the current directory and it
1916 is named according to the <filename>git commit</filename> summary line.
1917 The patch file ends with <filename>.patch</filename>.</para></listitem>
1918 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1919 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1920 which you can create in the same directory that holds the recipe
1921 (<filename>.bb</filename>) file or the
1922 append (<filename>.bbappend</filename>) file.
1923 Placing the patch here guarantees that the OpenEmbedded build system will find
1924 the patch.
1925 Next, add the patch into the
1926 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1927 of the recipe.
1928 Here is an example:
1929 <literallayout class='monospaced'>
1930 SRC_URI += "file://0001-&lt;commit-summary-message&gt;.patch"
1931 </literallayout></para></listitem>
1932 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1933 Finally, don't forget to 'bump' the
1934 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1935 value in the recipe since the resulting packages have changed.</para></listitem>
1936 </orderedlist>
1937 </para>
1938 </section>
1939</section>
1940
1941<section id='image-development-using-hob'>
1942 <title>Image Development Using Hob</title>
1943
1944 <para>
1945 The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the
1946 OpenEmbedded build system, which is based on BitBake.
1947 You can use the Hob to build custom operating system images within the Yocto Project build environment.
1948 Hob simply provides a friendly interface over the build system used during development.
1949 In other words, building images with the Hob lets you take care of common build tasks more easily.
1950 </para>
1951
1952 <para>
1953 For a better understanding of Hob, see the project page at
1954 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink>
1955 on the Yocto Project website.
1956 If you follow the "Documentation" link from the Hob page, you will
1957 find a short introductory training video on Hob.
1958 The following lists some features of Hob:
1959 <itemizedlist>
1960 <listitem><para>You can setup and run Hob using these commands:
1961 <literallayout class='monospaced'>
1962 $ source oe-init-build-env
1963 $ hob
1964 </literallayout></para></listitem>
1965 <listitem><para>You can set the
1966 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1967 for which you are building the image.</para></listitem>
1968 <listitem><para>You can modify various policy settings such as the
1969 package format with which to build,
1970 the parallelism BitBake uses, whether or not to build an
1971 external toolchain, and which host to build against.
1972 </para></listitem>
1973 <listitem><para>You can manage
1974 <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
1975 <listitem><para>You can select a base image and then add extra packages for your custom build.
1976 </para></listitem>
1977 <listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
1978 </itemizedlist>
1979 </para>
1980</section>
1981
1982<section id="platdev-appdev-devshell">
1983 <title>Using a Development Shell</title>
1984
1985 <para>
1986 When debugging certain commands or even when just editing packages,
1987 <filename>devshell</filename> can be a useful tool.
1988 When you invoke <filename>devshell</filename>, source files are
1989 extracted into your working directory and patches are applied.
1990 Then, a new terminal is opened and you are placed in the working directory.
1991 In the new terminal, all the OpenEmbedded build-related environment variables are
1992 still defined so you can use commands such as <filename>configure</filename> and
1993 <filename>make</filename>.
1994 The commands execute just as if the OpenEmbedded build system were executing them.
1995 Consequently, working this way can be helpful when debugging a build or preparing
1996 software to be used with the OpenEmbedded build system.
1997 </para>
1998
1999 <para>
2000 Following is an example that uses <filename>devshell</filename> on a target named
2001 <filename>matchbox-desktop</filename>:
2002 <literallayout class='monospaced'>
2003 $ bitbake matchbox-desktop -c devshell
2004 </literallayout>
2005 </para>
2006
2007 <para>
2008 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
2009 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
2010 variable controls what type of shell is opened.
2011 </para>
2012
2013 <para>
2014 For spawned terminals, the following occurs:
2015 <itemizedlist>
2016 <listitem><para>The <filename>PATH</filename> variable includes the
2017 cross-toolchain.</para></listitem>
2018 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
2019 <filename>.pc</filename> files.</para></listitem>
2020 <listitem><para>The <filename>configure</filename> command finds the
2021 Yocto Project site files as well as any other necessary files.</para></listitem>
2022 </itemizedlist>
2023 </para>
2024
2025 <para>
2026 Within this environment, you can run configure or compile
2027 commands as if they were being run by
2028 the OpenEmbedded build system itself.
2029 As noted earlier, the working directory also automatically changes to the
2030 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
2031 </para>
2032
2033 <para>
2034 When you are finished, you just exit the shell or close the terminal window.
2035 </para>
2036
2037 <note>
2038 <para>
2039 It is worth remembering that when using <filename>devshell</filename>
2040 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
2041 instead of just using <filename>gcc</filename>.
2042 The same applies to other applications such as <filename>binutils</filename>,
2043 <filename>libtool</filename> and so forth.
2044 BitBake sets up environment variables such as <filename>CC</filename>
2045 to assist applications, such as <filename>make</filename> to find the correct tools.
2046 </para>
2047
2048 <para>
2049 It is also worth noting that <filename>devshell</filename> still works over
2050 X11 forwarding and similar situations.
2051 </para>
2052 </note>
2053</section>
2054
2055</chapter>
2056<!--
2057vim: expandtab tw=80 ts=4
2058-->
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
new file mode 100644
index 0000000000..34326d10b6
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -0,0 +1,1575 @@
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 24GB RAM and plenty of
188 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 and SCMs, see the
226 BitBake manual located in the
227 <filename>bitbake/doc/manual</filename> directory of the
228 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
229 </note>
230 </para>
231
232 <para>
233 It is relatively easy to set up Git services and create
234 infrastructure like
235 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
236 which is based on server software called
237 <filename>gitolite</filename> with <filename>cgit</filename>
238 being used to generate the web interface that lets you view the
239 repositories.
240 The <filename>gitolite</filename> software identifies users
241 using <filename>ssh</filename> keys and allows branch-based
242 access controls to repositories that you can control as little
243 or as much as necessary.
244 </para>
245
246 <note>
247 The setup of these services is beyond the scope of this manual.
248 However, sites such as these exist that describe how to perform
249 setup:
250 <itemizedlist>
251 <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
252 Describes how to install <filename>gitolite</filename>
253 on the server.</para></listitem>
254 <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
255 All topics for <filename>gitolite</filename>.
256 </para></listitem>
257 <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
258 Documentation on how to create interfaces and frontends
259 for Git.</para></listitem>
260 </itemizedlist>
261 </note>
262 </section>
263
264 <section id='best-practices-autobuilders'>
265 <title>Autobuilders</title>
266
267 <para>
268 Autobuilders are often the core of a development project.
269 It is here that changes from individual developers are brought
270 together and centrally tested and subsequent decisions about
271 releases can be made.
272 Autobuilders also allow for "continuous integration" style
273 testing of software components and regression identification
274 and tracking.
275 </para>
276
277 <para>
278 See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
279 for more information and links to buildbot.
280 The Yocto Project team has found this implementation
281 works well in this role.
282 A public example of this is the Yocto Project
283 Autobuilders, which we use to test the overall health of the
284 project.
285 </para>
286
287 <para>
288 The features of this system are:
289 <itemizedlist>
290 <listitem><para>Highlights when commits break the build.
291 </para></listitem>
292 <listitem><para>Populates an sstate cache from which
293 developers can pull rather than requiring local
294 builds.</para></listitem>
295 <listitem><para>Allows commit hook triggers,
296 which trigger builds when commits are made.
297 </para></listitem>
298 <listitem><para>Allows triggering of automated image booting
299 and testing under the QuickEMUlator (QEMU).
300 </para></listitem>
301 <listitem><para>Supports incremental build testing and from
302 scratch builds.</para></listitem>
303 <listitem><para>Shares output that allows developer
304 testing and historical regression investigation.
305 </para></listitem>
306 <listitem><para>Creates output that can be used for releases.
307 </para></listitem>
308 <listitem><para>Allows scheduling of builds so that resources
309 can be used efficiently.</para></listitem>
310 </itemizedlist>
311 </para>
312 </section>
313
314 <section id='best-practices-policies-and-change-flow'>
315 <title>Policies and Change Flow</title>
316
317 <para>
318 The Yocto Project itself uses a hierarchical structure and a
319 pull model.
320 Scripts exist to create and send pull requests
321 (i.e. <filename>create-pull-request</filename> and
322 <filename>send-pull-request</filename>).
323 This model is in line with other open source projects where
324 maintainers are responsible for specific areas of the project
325 and a single maintainer handles the final "top-of-tree" merges.
326 </para>
327
328 <note>
329 You can also use a more collective push model.
330 The <filename>gitolite</filename> software supports both the
331 push and pull models quite easily.
332 </note>
333
334 <para>
335 As with any development environment, it is important
336 to document the policy used as well as any main project
337 guidelines so they are understood by everyone.
338 It is also a good idea to have well structured
339 commit messages, which are usually a part of a project's
340 guidelines.
341 Good commit messages are essential when looking back in time and
342 trying to understand why changes were made.
343 </para>
344
345 <para>
346 If you discover that changes are needed to the core layer of the
347 project, it is worth sharing those with the community as soon
348 as possible.
349 Chances are if you have discovered the need for changes, someone
350 else in the community needs them also.
351 </para>
352 </section>
353
354 <section id='best-practices-summary'>
355 <title>Summary</title>
356
357 <para>
358 This section summarizes the key recommendations described in the
359 previous sections:
360 <itemizedlist>
361 <listitem><para>Use <link linkend='git'>Git</link>
362 as the source control system.</para></listitem>
363 <listitem><para>Maintain your Metadata in layers that make sense
364 for your situation.
365 See the "<link linkend='understanding-and-creating-layers'>Understanding
366 and Creating Layers</link>" section for more information on
367 layers.</para></listitem>
368 <listitem><para>Separate the project's Metadata and code by using
369 separate Git repositories.
370 See the "<link linkend='yocto-project-repositories'>Yocto Project
371 Source Repositories</link>" section for information on these
372 repositories.
373 See the "<link linkend='getting-setup'>Getting Set Up</link>" section
374 for information on how to set up various Yocto Project related
375 Git repositories.</para></listitem>
376 <listitem><para>Set up the directory for the shared state cache
377 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
378 where it makes sense.
379 For example, set up the sstate cache on a system used
380 by developers in the same organization and share the
381 same source directories on their machines.
382 </para></listitem>
383 <listitem><para>Set up an Autobuilder and have it populate the
384 sstate cache and source directories.</para></listitem>
385 <listitem><para>The Yocto Project community encourages you
386 to send patches to the project to fix bugs or add features.
387 If you do submit patches, follow the project commit
388 guidelines for writing good commit messages.
389 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
390 section.</para></listitem>
391 <listitem><para>Send changes to the core sooner than later
392 as others likely run into the same issues.
393 For some guidance on mailing lists to use, see the list in the
394 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
395 section.
396 For a description of the available mailing lists, see the
397 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
398 section in the Yocto Project Reference Manual.
399 </para></listitem>
400 </itemizedlist>
401 </para>
402 </section>
403</section>
404
405<section id='yocto-project-repositories'>
406 <title>Yocto Project Source Repositories</title>
407
408 <para>
409 The Yocto Project team maintains complete source repositories for all Yocto Project files
410 at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
411 This web-based source code browser is organized into categories by function such as
412 IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
413 From the interface, you can click on any particular item in the "Name" column and
414 see the URL at the bottom of the page that you need to clone a Git repository for
415 that particular item.
416 Having a local Git repository of the Source Directory (poky) allows you to
417 make changes, contribute to the history, and ultimately enhance the Yocto Project's
418 tools, Board Support Packages, and so forth.
419 </para>
420
421 <para>
422 Conversely, if you are a developer that is not interested in contributing back to the
423 Yocto Project, you have the ability to simply download and extract release tarballs
424 and use them within the Yocto Project environment.
425 All that is required is a particular release of the Yocto Project and
426 your application source code.
427 </para>
428
429 <para>
430 For any supported release of Yocto Project, you can go to the
431 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
432 select the "Downloads" tab and get a tarball of the release.
433 You can also go to this site to download any supported BSP tarballs.
434 Unpacking the tarball gives you a hierarchical Source Directory that lets you develop
435 using the Yocto Project.
436 </para>
437
438 <para>
439 Once you are set up through either tarball extraction or a checkout of Git repositories,
440 you are ready to develop.
441 </para>
442
443 <para>
444 In summary, here is where you can get the project files needed for development:
445 <itemizedlist>
446 <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
447 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
448 Metadata Layers.
449 You can create local copies of Git repositories for each of these areas.</para>
450 <para>
451 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
452 </para></listitem>
453 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
454 This area contains index releases such as
455 the <trademark class='trade'>Eclipse</trademark>
456 Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
457 and all released versions of Yocto Project in the form of images or tarballs.
458 Downloading and extracting these files does not produce a local copy of the
459 Git repository but rather a snapshot of a particular release or image.</para>
460 <para>
461 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
462 </para></listitem>
463 <listitem><para><emphasis>"Downloads" page for the
464 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis>
465 Access this page by going to the website and then selecting
466 the "Downloads" tab.
467 This page allows you to download any Yocto Project
468 release or Board Support Package (BSP) in tarball form.
469 The tarballs are similar to those found in the
470 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
471 <para>
472 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
473 </para></listitem>
474 </itemizedlist>
475 </para>
476</section>
477
478<section id='yocto-project-terms'>
479 <title>Yocto Project Terms</title>
480
481 <para>
482 Following is a list of terms and definitions users new to the Yocto Project development
483 environment might find helpful.
484 While some of these terms are universal, the list includes them just in case:
485 <itemizedlist>
486 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
487 a recipe file.
488 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
489 The OpenEmbedded build system expects every append file to have a corresponding
490 recipe (<filename>.bb</filename>) file.
491 Furthermore, the append file and corresponding recipe file
492 must use the same root filename.
493 The filenames can differ only in the file type suffix used (e.g.
494 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
495 </para>
496 <para>Information in append files overrides the information in the similarly-named recipe file.
497 For an example of an append file in use, see the
498 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
499 </para></listitem>
500 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
501 The task executor and scheduler used by
502 the OpenEmbedded build system to build images.
503 For more information on BitBake, see the BitBake documentation
504 in the <filename>bitbake/doc/manual</filename> directory of the
505 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
506 <listitem>
507 <para id='build-directory'><emphasis>Build Directory:</emphasis>
508 This term refers to the area used by the OpenEmbedded build system for builds.
509 The area is created when you <filename>source</filename> the setup
510 environment script that is found in the Source Directory
511 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
512 or
513 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
514 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
515 variable points to the Build Directory.</para>
516
517 <para>You have a lot of flexibility when creating the Build Directory.
518 Following are some examples that show how to create the directory:
519 <itemizedlist>
520 <listitem><para>Create the Build Directory in your current working directory
521 and name it <filename>build</filename>.
522 This is the default behavior.
523 <literallayout class='monospaced'>
524 $ source &OE_INIT_PATH;
525 </literallayout></para></listitem>
526 <listitem><para>Provide a directory path and specifically name the build
527 directory.
528 This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename>
529 in your home directory within the directory <filename>mybuilds</filename>.
530 If <filename>mybuilds</filename> does not exist, the directory is created for you:
531 <literallayout class='monospaced'>
532 $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION;
533 </literallayout></para></listitem>
534 <listitem><para>Provide an existing directory to use as the Build Directory
535 and use the default <filename>build</filename> name.
536 <literallayout class='monospaced'>
537 $ source &OE_INIT_PATH; $HOME/mybuilds/
538 </literallayout></para></listitem>
539 </itemizedlist>
540 </para></listitem>
541 <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project,
542 this term refers to the OpenEmbedded build system used by the project.
543 This build system is based on the project known as "Poky."
544 For some historical information about Poky, see the
545 <link linkend='poky'>Poky</link> term.
546 </para></listitem>
547 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
548 and inheritance so that commonly used patterns can be defined once and then easily used
549 in multiple recipes.
550 Class files end with the <filename>.bbclass</filename> filename extension.
551 </para></listitem>
552 <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
553 <filename>.conf</filename> files provides global definitions of variables.
554 The <filename>conf/local.conf</filename> configuration file in the
555 <link linkend='build-directory'>Build Directory</link>
556 contains user-defined variables that affect each build.
557 The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
558 defines Yocto "distro" configuration
559 variables used only when building with this policy.
560 Machine configuration files, which
561 are located throughout the
562 <link linkend='source-directory'>Source Directory</link>, define
563 variables for specific hardware and are only used when building for that target
564 (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
565 variables for the Texas Instruments ARM Cortex-A8 development board).
566 Configuration files end with a <filename>.conf</filename> filename extension.
567 </para></listitem>
568 <listitem><para id='cross-development-toolchain'>
569 <emphasis>Cross-Development Toolchain:</emphasis>
570 In general, a cross-development toolchain is a collection of
571 software development tools and utilities that run on one
572 architecture and allow you to develop software for a
573 different, or targeted, architecture.
574 These toolchains contain cross-compilers, linkers, and
575 debuggers that are specific to the target architecture.
576 </para>
577
578 <para>The Yocto Project supports two different cross-development
579 toolchains:
580 <itemizedlist>
581 <listitem><para>A toolchain only used by and within
582 BitBake when building an image for a target
583 architecture.</para></listitem>
584 <listitem><para>A relocatable toolchain used outside of
585 BitBake by developers when developing applications
586 that will run on a targeted device.
587 Sometimes this relocatable cross-development
588 toolchain is referred to as the meta-toolchain.
589 </para></listitem>
590 </itemizedlist>
591 </para>
592
593 <para>
594 Creation of these toolchains is simple and automated.
595 For information on toolchain concepts as they apply to the
596 Yocto Project, see the
597 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
598 section in the Yocto Project Reference Manual.
599 You can also find more information on using the
600 relocatable toolchain in the
601 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
602 Application Developer's Guide</ulink>.
603 </para></listitem>
604 <listitem><para><emphasis>Image:</emphasis> An image is the result produced when
605 BitBake processes a given collection of recipes and related Metadata.
606 Images are the binary output that run on specific hardware or QEMU
607 and for specific use cases.
608 For a list of the supported image types that the Yocto Project provides, see the
609 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
610 chapter in the Yocto Project Reference Manual.</para></listitem>
611 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
612 a BSP, or an application stack.
613 For a discussion on BSP Layers, see the
614 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
615 section in the Yocto Project Board Support Packages (BSP)
616 Developer's Guide.</para></listitem>
617 <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis>
618 A term sometimes used for
619 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
620 </para></listitem>
621 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
622 The files that BitBake parses when building an image.
623 In general, Metadata includes recipes, classes, and
624 configuration files.
625 In the context of the kernel ("kernel Metadata"),
626 it refers to Metadata in the <filename>meta</filename>
627 branches of the kernel source Git repositories.
628 </para></listitem>
629 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
630 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
631 This Metadata is found in the <filename>meta</filename> directory of the
632 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
633 <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
634 this term refers to the packaged output from a baked recipe.
635 A package is generally the compiled binaries produced from the recipe's sources.
636 You "bake" something by running it through BitBake.</para>
637 <para>It is worth noting that the term "package" can, in general, have subtle
638 meanings. For example, the packages referred to in the
639 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are
640 compiled binaries that when installed add functionality to your Linux
641 distribution.</para>
642 <para>Another point worth noting is that historically within the Yocto Project,
643 recipes were referred to as packages - thus, the existence of several BitBake
644 variables that are seemingly mis-named,
645 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
646 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>,
647 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
648 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
649 </para></listitem>
650 <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
651 In its most general sense, it is an open-source project that was initially developed
652 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
653 build system becoming a build system for embedded images.
654 After Intel Corporation acquired OpenedHand, the project poky became the basis for
655 the Yocto Project's build system.
656 Within the Yocto Project source repositories, <filename>poky</filename>
657 exists as a separate Git repository
658 that can be cloned to yield a local copy on the host system.
659 Thus, "poky" can refer to the local copy of the Source Directory used to develop within
660 the Yocto Project.</para></listitem>
661 <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
662 A recipe describes where you get source code and which patches to apply.
663 Recipes describe dependencies for libraries or for other recipes, and they
664 also contain configuration and compilation options.
665 Recipes contain the logical unit of execution, the software/images to build, and
666 use the <filename>.bb</filename> file extension.</para></listitem>
667 <listitem>
668 <para id='source-directory'><emphasis>Source Directory:</emphasis>
669 This term refers to the directory structure created as a result of either downloading
670 and unpacking a Yocto Project release tarball or creating a local copy of
671 the <filename>poky</filename> Git repository
672 <filename>git://git.yoctoproject.org/poky</filename>.
673 Sometimes you might hear the term "poky directory" used to refer to this
674 directory structure.
675 <note>
676 The OpenEmbedded build system does not support file or directory names that
677 contain spaces.
678 Be sure that the Source Directory you use does not contain these types
679 of names.
680 </note></para>
681 <para>The Source Directory contains BitBake, Documentation, Metadata and
682 other files that all support the Yocto Project.
683 Consequently, you must have the Source Directory in place on your development
684 system in order to do any development using the Yocto Project.</para>
685
686 <para>For tarball expansion, the name of the top-level directory of the Source Directory
687 is derived from the Yocto Project release tarball.
688 For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename>
689 results in a Source Directory whose top-level folder is named
690 <filename>&YOCTO_POKY;</filename>.
691 If you create a local copy of the Git repository, you can name the repository
692 anything you like.
693 Throughout much of the documentation, <filename>poky</filename> is used as the name of
694 the top-level folder of the local copy of the poky Git repository.
695 So, for example, cloning the <filename>poky</filename> Git repository results in a
696 local Git repository whose top-level folder is also named <filename>poky</filename>.</para>
697
698 <para>It is important to understand the differences between the Source Directory created
699 by unpacking a released tarball as compared to cloning
700 <filename>git://git.yoctoproject.org/poky</filename>.
701 When you unpack a tarball, you have an exact copy of the files based on the time of
702 release - a fixed release point.
703 Any changes you make to your local files in the Source Directory are on top of the release.
704 On the other hand, when you clone the <filename>poky</filename> Git repository, you have an
705 active development repository.
706 In this case, any local changes you make to the Source Directory can be later applied
707 to active development branches of the upstream <filename>poky</filename> Git
708 repository.</para>
709
710 <para>Finally, if you want to track a set of local changes while starting from the same point
711 as a release tarball, you can create a local Git branch that
712 reflects the exact copy of the files at the time of their release.
713 You do this by using Git tags that are part of the repository.</para>
714
715 <para>For more information on concepts related to Git repositories, branches, and tags,
716 see the
717 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
718 section.</para></listitem>
719 <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
720 You use tasks to hold recipes that, when built, usually accomplish a single task.
721 For example, a task could contain the recipes for a company’s proprietary or value-add software.
722 Or, the task could contain the recipes that enable graphics.
723 A task is really just another recipe.
724 Because task files are recipes, they end with the <filename>.bb</filename> filename
725 extension.</para></listitem>
726 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
727 that are not local to the development system but located in a master area that is controlled
728 by the maintainer of the source code.
729 For example, in order for a developer to work on a particular piece of code, they need to
730 first get a copy of it from an "upstream" source.</para></listitem>
731 </itemizedlist>
732 </para>
733</section>
734
735<section id='licensing'>
736 <title>Licensing</title>
737
738 <para>
739 Because open source projects are open to the public, they have different licensing structures in place.
740 License evolution for both Open Source and Free Software has an interesting history.
741 If you are interested in this history, you can find basic information here:
742 <itemizedlist>
743 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
744 </para></listitem>
745 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license
746 history</ulink></para></listitem>
747 </itemizedlist>
748 </para>
749
750 <para>
751 In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
752 (MIT) License.
753 MIT licensing permits the reuse of software within proprietary software as long as the
754 license is distributed with that software.
755 MIT is also compatible with the GNU General Public License (GPL).
756 Patches to the Yocto Project follow the upstream licensing scheme.
757 You can find information on the MIT license at
758 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
759 You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>
760 here</ulink>.
761 </para>
762
763 <para>
764 When you build an image using the Yocto Project, the build process uses a
765 known list of licenses to ensure compliance.
766 You can find this list in the
767 <link linkend='source-directory'>Source Directory</link> at
768 <filename>meta/files/common-licenses</filename>.
769 Once the build completes, the list of all licenses found and used during that build are
770 kept in the
771 <link linkend='build-directory'>Build Directory</link> at
772 <filename>tmp/deploy/licenses</filename>.
773 </para>
774
775 <para>
776 If a module requires a license that is not in the base list, the build process
777 generates a warning during the build.
778 These tools make it easier for a developer to be certain of the licenses with which
779 their shipped products must comply.
780 However, even with these tools it is still up to the developer to resolve potential licensing issues.
781 </para>
782
783 <para>
784 The base list of licenses used by the build process is a combination of the Software Package
785 Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
786 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation
787 that maintains a specification
788 for a standard format for communicating the components, licenses, and copyrights
789 associated with a software package.
790 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
791 Definition and the effort for reviewing and approving licenses that are OSD-conformant.
792 </para>
793
794 <para>
795 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
796 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
797 </para>
798
799 <para>
800 For information that can help you to maintain compliance with various open source licensing
801 during the lifecycle of a product created using the Yocto Project, see the
802 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section.
803 </para>
804</section>
805
806<section id='git'>
807 <title>Git</title>
808
809 <para>
810 The Yocto Project uses Git, which is a free, open source distributed version control system.
811 Git supports distributed development, non-linear development, and can handle large projects.
812 It is best that you have some fundamental understanding of how Git tracks projects and
813 how to work with Git if you are going to use the Yocto Project for development.
814 This section provides a quick overview of how Git works and provides you with a summary
815 of some essential Git commands.
816 </para>
817
818 <para>
819 For more information on Git, see
820 <ulink url='http://git-scm.com/documentation'></ulink>.
821 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
822 </para>
823
824 <section id='repositories-tags-and-branches'>
825 <title>Repositories, Tags, and Branches</title>
826
827 <para>
828 As mentioned earlier in the section
829 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
830 the Yocto Project maintains source repositories at
831 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
832 If you look at this web-interface of the repositories, each item is a separate
833 Git repository.
834 </para>
835
836 <para>
837 Git repositories use branching techniques that track content change (not files)
838 within a project (e.g. a new feature or updated documentation).
839 Creating a tree-like structure based on project divergence allows for excellent historical
840 information over the life of a project.
841 This methodology also allows for an environment from which you can do lots of
842 local experimentation on projects as you develop changes or new features.
843 </para>
844
845 <para>
846 A Git repository represents all development efforts for a given project.
847 For example, the Git repository <filename>poky</filename> contains all changes
848 and developments for Poky over the course of its entire life.
849 That means that all changes that make up all releases are captured.
850 The repository maintains a complete history of changes.
851 </para>
852
853 <para>
854 You can create a local copy of any repository by "cloning" it with the Git
855 <filename>clone</filename> command.
856 When you clone a Git repository, you end up with an identical copy of the
857 repository on your development system.
858 Once you have a local copy of a repository, you can take steps to develop locally.
859 For examples on how to clone Git repositories, see the
860 "<link linkend='getting-setup'>Getting Set Up</link>" section.
861 </para>
862
863 <para>
864 It is important to understand that Git tracks content change and not files.
865 Git uses "branches" to organize different development efforts.
866 For example, the <filename>poky</filename> repository has
867 <filename>denzil</filename>, <filename>danny</filename>,
868 <filename>dylan</filename>, <filename>dora</filename>,
869 and <filename>master</filename> branches among others.
870 You can see all the branches by going to
871 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
872 clicking on the
873 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
874 link beneath the "Branch" heading.
875 </para>
876
877 <para>
878 Each of these branches represents a specific area of development.
879 The <filename>master</filename> branch represents the current or most recent
880 development.
881 All other branches represent off-shoots of the <filename>master</filename>
882 branch.
883 </para>
884
885 <para>
886 When you create a local copy of a Git repository, the copy has the same set
887 of branches as the original.
888 This means you can use Git to create a local working area (also called a branch)
889 that tracks a specific development branch from the source Git repository.
890 in other words, you can define your local Git environment to work on any development
891 branch in the repository.
892 To help illustrate, here is a set of commands that creates a local copy of the
893 <filename>poky</filename> Git repository and then creates and checks out a local
894 Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
895 <literallayout class='monospaced'>
896 $ cd ~
897 $ git clone git://git.yoctoproject.org/poky
898 $ cd poky
899 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
900 </literallayout>
901 In this example, the name of the top-level directory of your local
902 <link linkend='source-directory'>Source Directory</link>
903 is <filename>poky</filename>,
904 and the name of that local working area (local branch) you just
905 created and checked out is <filename>&DISTRO_NAME;</filename>.
906 The files in your local repository now reflect the same files that
907 are in the <filename>&DISTRO_NAME;</filename> development
908 branch of the Yocto Project's <filename>poky</filename>
909 upstream repository.
910 It is important to understand that when you create and checkout a
911 local working branch based on a branch name,
912 your local environment matches the "tip" of that development branch
913 at the time you created your local branch, which could be
914 different than the files at the time of a similarly named release.
915 In other words, creating and checking out a local branch based on the
916 <filename>&DISTRO_NAME;</filename> branch name is not the same as
917 cloning and checking out the <filename>master</filename> branch.
918 Keep reading to see how you create a local snapshot of a Yocto Project Release.
919 </para>
920
921 <para>
922 Git uses "tags" to mark specific changes in a repository.
923 Typically, a tag is used to mark a special point such as the final change
924 before a project is released.
925 You can see the tags used with the <filename>poky</filename> Git repository
926 by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
927 clicking on the
928 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
929 link beneath the "Tag" heading.
930 </para>
931
932 <para>
933 Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>,
934 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
935 These tags represent Yocto Project releases.
936 </para>
937
938 <para>
939 When you create a local copy of the Git repository, you also have access to all the
940 tags.
941 Similar to branches, you can create and checkout a local working Git branch based
942 on a tag name.
943 When you do this, you get a snapshot of the Git repository that reflects
944 the state of the files when the change was made associated with that tag.
945 The most common use is to checkout a working branch that matches a specific
946 Yocto Project release.
947 Here is an example:
948 <literallayout class='monospaced'>
949 $ cd ~
950 $ git clone git://git.yoctoproject.org/poky
951 $ cd poky
952 $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
953 </literallayout>
954 In this example, the name of the top-level directory of your local Yocto Project
955 Files Git repository is <filename>poky</filename>.
956 And, the name of the local branch you have created and checked out is
957 <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.
958 The files in your repository now exactly match the Yocto Project &DISTRO;
959 Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).
960 It is important to understand that when you create and checkout a local
961 working branch based on a tag, your environment matches a specific point
962 in time and not the entire development branch.
963 </para>
964 </section>
965
966 <section id='basic-commands'>
967 <title>Basic Commands</title>
968
969 <para>
970 Git has an extensive set of commands that lets you manage changes and perform
971 collaboration over the life of a project.
972 Conveniently though, you can manage with a small set of basic operations and workflows
973 once you understand the basic philosophy behind Git.
974 You do not have to be an expert in Git to be functional.
975 A good place to look for instruction on a minimal set of Git commands is
976 <ulink url='http://git-scm.com/documentation'>here</ulink>.
977 If you need to download Git, you can do so
978 <ulink url='http://git-scm.com/download'>here</ulink>.
979 </para>
980
981 <para>
982 If you don’t know much about Git, you should educate
983 yourself by visiting the links previously mentioned.
984 </para>
985
986 <para>
987 The following list briefly describes some basic Git operations as a way to get started.
988 As with any set of commands, this list (in most cases) simply shows the base command and
989 omits the many arguments they support.
990 See the Git documentation for complete descriptions and strategies on how to use these commands:
991 <itemizedlist>
992 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
993 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
994 <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
995 During collaboration, this command allows you to create a local repository that is on
996 equal footing with a fellow developer’s repository.</para></listitem>
997 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
998 to the index that
999 Git uses to track changes.
1000 You must stage all files that have changed before you can commit them.</para></listitem>
1001 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents
1002 the changes you made.
1003 Commits are used for historical purposes, for determining if a maintainer of a project
1004 will allow the change, and for ultimately pushing the change from your local Git repository
1005 into the project’s upstream (or master) repository.</para></listitem>
1006 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
1007 possibly need staged and committed.</para></listitem>
1008 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
1009 your working branch.
1010 This command is analogous to "cd".</para></listitem>
1011 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
1012 a working branch on your local machine where you can isolate work.
1013 It is a good idea to use local branches when adding specific features or changes.
1014 This way if you do not like what you have done you can easily get rid of the work.</para></listitem>
1015 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
1016 existing local branches and
1017 tells you the branch in which you are currently working.</para></listitem>
1018 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
1019 Deletes an existing local branch.
1020 You need to be in a local branch other than the one you are deleting
1021 in order to delete <filename>&lt;branch-name&gt;</filename>.</para></listitem>
1022 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
1023 from an upstream Git
1024 repository and places it in your local Git repository.
1025 You use this command to make sure you are synchronized with the repository
1026 from which you are basing changes (.e.g. the master branch).</para></listitem>
1027 <listitem><para><emphasis><filename>git push</filename>:</emphasis>
1028 Sends all your committed local changes to an upstream Git
1029 repository (e.g. a contribution repository).
1030 The maintainer of the project draws from these repositories
1031 when adding changes to the project’s master repository or
1032 other development branch.
1033 </para></listitem>
1034 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
1035 local branch of your repository with another branch.
1036 When you create a local Git repository, the default branch is named "master".
1037 A typical workflow is to create a temporary branch for isolated work, make and commit your
1038 changes, switch to your local master branch, merge the changes from the temporary branch into the
1039 local master branch, and then delete the temporary branch.</para></listitem>
1040 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
1041 commits from one branch into another branch.
1042 There are times when you might not be able to merge all the changes in one branch with
1043 another but need to pick out certain ones.</para></listitem>
1044 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
1045 and changes in your local Git repository.
1046 This command is a good way to graphically see where things have diverged in your
1047 local repository.</para></listitem>
1048 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
1049 repository.</para></listitem>
1050 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
1051 between your local working files and the same files in the upstream Git repository that your
1052 branch currently tracks.</para></listitem>
1053 </itemizedlist>
1054 </para>
1055 </section>
1056</section>
1057
1058<section id='workflows'>
1059 <title>Workflows</title>
1060
1061 <para>
1062 This section provides some overview on workflows using Git.
1063 In particular, the information covers basic practices that describe roles and actions in a
1064 collaborative development environment.
1065 Again, if you are familiar with this type of development environment, you might want to just
1066 skip this section.
1067 </para>
1068
1069 <para>
1070 The Yocto Project files are maintained using Git in a "master" branch whose Git history
1071 tracks every change and whose structure provides branches for all diverging functionality.
1072 Although there is no need to use Git, many open source projects do so.
1073 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
1074 branch of a given Git repository.
1075 The "master" branch is the “upstream” repository where the final builds of the project occur.
1076 The maintainer is responsible for allowing changes in from other developers and for
1077 organizing the underlying branch structure to reflect release strategies and so forth.
1078 <note>For information on finding out who is responsible (maintains)
1079 for a particular area of code, see the
1080 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1081 section.
1082 </note>
1083 </para>
1084
1085 <para>
1086 The project also has contribution repositories known as "contrib" areas.
1087 These areas temporarily hold changes to the project that have been submitted or committed
1088 by the Yocto Project development team and by community members that contribute to the project.
1089 The maintainer determines if the changes are qualified to be moved from the "contrib" areas
1090 into the "master" branch of the Git repository.
1091 </para>
1092
1093 <para>
1094 Developers (including contributing community members) create and maintain cloned repositories
1095 of the upstream "master" branch.
1096 These repositories are local to their development platforms and are used to develop changes.
1097 When a developer is satisfied with a particular feature or change, they "push" the changes
1098 to the appropriate "contrib" repository.
1099 </para>
1100
1101 <para>
1102 Developers are responsible for keeping their local repository up-to-date with "master".
1103 They are also responsible for straightening out any conflicts that might arise within files
1104 that are being worked on simultaneously by more than one person.
1105 All this work is done locally on the developer’s machines before anything is pushed to a
1106 "contrib" area and examined at the maintainer’s level.
1107 </para>
1108
1109 <para>
1110 A somewhat formal method exists by which developers commit changes and push them into the
1111 "contrib" area and subsequently request that the maintainer include them into "master"
1112 This process is called “submitting a patch” or "submitting a change."
1113 For information on submitting patches and changes, see the
1114 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
1115 </para>
1116
1117 <para>
1118 To summarize the environment: we have a single point of entry for changes into the project’s
1119 "master" branch of the Git repository, which is controlled by the project’s maintainer.
1120 And, we have a set of developers who independently develop, test, and submit changes
1121 to "contrib" areas for the maintainer to examine.
1122 The maintainer then chooses which changes are going to become a permanent part of the project.
1123 </para>
1124
1125 <para>
1126 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
1127 </para>
1128
1129 <para>
1130 While each development environment is unique, there are some best practices or methods
1131 that help development run smoothly.
1132 The following list describes some of these practices.
1133 For more information about Git workflows, see the workflow topics in the
1134 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
1135 <itemizedlist>
1136 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
1137 small as compared to bundling many disparate changes into a single commit.
1138 This practice not only keeps things manageable but also allows the maintainer
1139 to more easily include or refuse changes.</para>
1140 <para>It is also good practice to leave the repository in a state that allows you to
1141 still successfully build your project. In other words, do not commit half of a feature,
1142 then add the other half as a separate, later commit.
1143 Each commit should take you from one buildable project state to another
1144 buildable state.</para></listitem>
1145 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
1146 delete local branches in your working Git repository.
1147 You can name these branches anything you like.
1148 It is helpful to give them names associated with the particular feature or change
1149 on which you are working.
1150 Once you are done with a feature or change and have merged it
1151 into your local master branch, simply discard the temporary
1152 branch.</para></listitem>
1153 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
1154 command allows you to take the
1155 changes from one branch and fold them into another branch.
1156 This process is especially helpful when more than a single developer might be working
1157 on different parts of the same feature.
1158 Merging changes also automatically identifies any collisions or "conflicts"
1159 that might happen as a result of the same lines of code being altered by two different
1160 developers.</para></listitem>
1161 <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
1162 use a system where branches indicate varying levels of code readiness.
1163 For example, you can have a "work" branch to develop in, a "test" branch where the code or
1164 change is tested, a "stage" branch where changes are ready to be committed, and so forth.
1165 As your project develops, you can merge code across the branches to reflect ever-increasing
1166 stable states of the development.</para></listitem>
1167 <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
1168 concept of developers "pushing" local commits to a remote repository, which is
1169 usually a contribution repository.
1170 This workflow is also based on developers "pulling" known states of the project down into their
1171 local development repositories.
1172 The workflow easily allows you to pull changes submitted by other developers from the
1173 upstream repository into your work area ensuring that you have the most recent software
1174 on which to develop.
1175 The Yocto Project has two scripts named <filename>create-pull-request</filename> and
1176 <filename>send-pull-request</filename> that ship with the release to facilitate this
1177 workflow.
1178 You can find these scripts in the <filename>scripts</filename>
1179 folder of the
1180 <link linkend='source-directory'>Source Directory</link>.
1181 For information on how to use these scripts, see the
1182 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
1183 </para></listitem>
1184 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
1185 maintainer through an email that you have a change (or patch) you would like considered
1186 for the "master" branch of the Git repository.
1187 To send this type of change, you format the patch and then send the email using the Git commands
1188 <filename>git format-patch</filename> and <filename>git send-email</filename>.
1189 For information on how to use these scripts, see the
1190 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1191 section.
1192 </para></listitem>
1193 </itemizedlist>
1194 </para>
1195</section>
1196
1197<section id='tracking-bugs'>
1198 <title>Tracking Bugs</title>
1199
1200 <para>
1201 The Yocto Project uses its own implementation of
1202 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
1203 Implementations of Bugzilla work well for group development because they track bugs and code
1204 changes, can be used to communicate changes and problems with developers, can be used to
1205 submit and review patches, and can be used to manage quality assurance.
1206 The home page for the Yocto Project implementation of Bugzilla is
1207 <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
1208 </para>
1209
1210 <para>
1211 Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
1212 such as when discovering an issue with some component of the build system that acts contrary
1213 to the documentation or your expectations.
1214 Following is the general procedure for submitting a new bug using the Yocto Project
1215 Bugzilla.
1216 You can find more information on defect management, bug tracking, and feature request
1217 processes all accomplished through the Yocto Project Bugzilla on the wiki page
1218 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
1219 <orderedlist>
1220 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
1221 a bug.</para></listitem>
1222 <listitem><para>When submitting a new bug, be sure to choose the appropriate
1223 Classification, Product, and Component for which the issue was found.
1224 Defects for the Yocto Project fall into one of six classifications: Yocto Project
1225 Components, Infrastructure, Build System &amp; Metadata, Documentation,
1226 QA/Testing, and Runtime.
1227 Each of these Classifications break down into multiple Products and, in some
1228 cases, multiple Components.</para></listitem>
1229 <listitem><para>Use the bug form to choose the correct Hardware and Architecture
1230 for which the bug applies.</para></listitem>
1231 <listitem><para>Indicate the Yocto Project version you were using when the issue
1232 occurred.</para></listitem>
1233 <listitem><para>Be sure to indicate the Severity of the bug.
1234 Severity communicates how the bug impacted your work.</para></listitem>
1235 <listitem><para>Select the appropriate "Documentation change" item
1236 for the bug.
1237 Fixing a bug may or may not affect the Yocto Project
1238 documentation.</para></listitem>
1239 <listitem><para>Provide a brief summary of the issue.
1240 Try to limit your summary to just a line or two and be sure to capture the
1241 essence of the issue.</para></listitem>
1242 <listitem><para>Provide a detailed description of the issue.
1243 You should provide as much detail as you can about the context, behavior, output,
1244 and so forth that surrounds the issue.
1245 You can even attach supporting files for output from logs by
1246 using the "Add an attachment" button.</para></listitem>
1247 <listitem><para>Be sure to copy the appropriate people in the
1248 "CC List" for the bug.
1249 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1250 section for information about finding out who is responsible
1251 for code.</para></listitem>
1252 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
1253 </orderedlist>
1254 </para>
1255</section>
1256
1257<section id='how-to-submit-a-change'>
1258 <title>How to Submit a Change</title>
1259
1260 <para>
1261 Contributions to the Yocto Project and OpenEmbedded are very welcome.
1262 Because the system is extremely configurable and flexible, we recognize that developers
1263 will want to extend, configure or optimize it for their specific uses.
1264 You should send patches to the appropriate mailing list so that they
1265 can be reviewed and merged by the appropriate maintainer.
1266 </para>
1267
1268 <para>
1269 Before submitting any change, be sure to find out who you should be
1270 notifying.
1271 Several methods exist through which you find out who you should be copying
1272 or notifying:
1273 <itemizedlist>
1274 <listitem><para><emphasis>Maintenance File:</emphasis>
1275 Examine the <filename>maintainers.inc</filename> file, which is
1276 located in the
1277 <link linkend='source-directory'>Source Directory</link>
1278 at <filename>meta-yocto/conf/distro/include</filename>, to
1279 see who is responsible for code.
1280 </para></listitem>
1281 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
1282 For BSP maintainers of supported BSPs, you can examine
1283 individual BSP <filename>README</filename> files.
1284 Alternatively, you can examine the
1285 <filename>MAINTAINERS</filename> file, which is found in the
1286 <filename>meta-intel</filename>, for a list of all supported
1287 BSP maintainers.
1288 </para></listitem>
1289 <listitem><para><emphasis>Search by File:</emphasis>
1290 Using <link linkend='git'>Git</link>, you can enter the
1291 following command to bring up a short list of all commits
1292 against a specific file:
1293 <literallayout class='monospaced'>
1294 git shortlog -- &lt;filename&gt;
1295 </literallayout>
1296 Just provide the name of the file for which you are interested.
1297 The information returned is not ordered by history but does
1298 include a list of all committers grouped by name.
1299 From the list, you can see who is responsible for the bulk of
1300 the changes against the file.
1301 </para></listitem>
1302 </itemizedlist>
1303 </para>
1304
1305 <para>
1306 For a list of the Yocto Project and related mailing lists, see the
1307 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
1308 the Yocto Project Reference Manual.
1309 </para>
1310
1311 <para>
1312 Here is some guidance on which mailing list to use for what type of change:
1313 <itemizedlist>
1314 <listitem><para>For changes to the core
1315 <link linkend='metadata'>Metadata</link>, send your patch to the
1316 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
1317 For example, a change to anything under the <filename>meta</filename> or
1318 <filename>scripts</filename> directories
1319 should be sent to this mailing list.</para></listitem>
1320 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
1321 directory), send your patch to the
1322 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
1323 <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
1324 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
1325 <listitem><para>For changes to other layers hosted on
1326 <filename>yoctoproject.org</filename> (unless the
1327 layer's documentation specifies otherwise), tools, and Yocto Project
1328 documentation, use the
1329 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
1330 <listitem><para>For additional recipes that do not fit into the core Metadata,
1331 you should determine which layer the recipe should go into and submit the
1332 change in the manner recommended by the documentation (e.g. README) supplied
1333 with the layer. If in doubt, please ask on the
1334 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
1335 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
1336 mailing lists.</para></listitem>
1337 </itemizedlist>
1338 </para>
1339
1340 <para>
1341 When you send a patch, be sure to include a "Signed-off-by:"
1342 line in the same style as required by the Linux kernel.
1343 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
1344 as follows:
1345 <literallayout class='monospaced'>
1346 Developer's Certificate of Origin 1.1
1347
1348 By making a contribution to this project, I certify that:
1349
1350 (a) The contribution was created in whole or in part by me and I
1351 have the right to submit it under the open source license
1352 indicated in the file; or
1353
1354 (b) The contribution is based upon previous work that, to the best
1355 of my knowledge, is covered under an appropriate open source
1356 license and I have the right under that license to submit that
1357 work with modifications, whether created in whole or in part
1358 by me, under the same open source license (unless I am
1359 permitted to submit under a different license), as indicated
1360 in the file; or
1361
1362 (c) The contribution was provided directly to me by some other
1363 person who certified (a), (b) or (c) and I have not modified
1364 it.
1365
1366 (d) I understand and agree that this project and the contribution
1367 are public and that a record of the contribution (including all
1368 personal information I submit with it, including my sign-off) is
1369 maintained indefinitely and may be redistributed consistent with
1370 this project or the open source license(s) involved.
1371 </literallayout>
1372 </para>
1373
1374 <para>
1375 In a collaborative environment, it is necessary to have some sort of standard
1376 or method through which you submit changes.
1377 Otherwise, things could get quite chaotic.
1378 One general practice to follow is to make small, controlled changes.
1379 Keeping changes small and isolated aids review, makes merging/rebasing easier
1380 and keeps the change history clean when anyone needs to refer to it in future.
1381 </para>
1382
1383 <para>
1384 When you make a commit, you must follow certain standards established by the
1385 OpenEmbedded and Yocto Project development teams.
1386 For each commit, you must provide a single-line summary of the change and you
1387 should almost always provide a more detailed description of what you did (i.e.
1388 the body of the commit message).
1389 The only exceptions for not providing a detailed description would be if your
1390 change is a simple, self-explanatory change that needs no further description
1391 beyond the summary.
1392 Here are the guidelines for composing a commit message:
1393 <itemizedlist>
1394 <listitem><para>Provide a single-line, short summary of the change.
1395 This summary is typically viewable in the "shortlist" of changes.
1396 Thus, providing something short and descriptive that gives the reader
1397 a summary of the change is useful when viewing a list of many commits.
1398 This short description should be prefixed by the recipe name (if changing a recipe), or
1399 else the short form path to the file being changed.
1400 </para></listitem>
1401 <listitem><para>For the body of the commit message, provide detailed information
1402 that describes what you changed, why you made the change, and the approach
1403 you used. It may also be helpful if you mention how you tested the change.
1404 Provide as much detail as you can in the body of the commit message.
1405 </para></listitem>
1406 <listitem><para>If the change addresses a specific bug or issue that is
1407 associated with a bug-tracking ID, include a reference to that ID in
1408 your detailed description.
1409 For example, the Yocto Project uses a specific convention for bug
1410 references - any commit that addresses a specific bug should include the
1411 bug ID in the description (typically at the beginning) as follows:
1412 <literallayout class='monospaced'>
1413 [YOCTO #&lt;bug-id&gt;]
1414
1415 &lt;detailed description of change&gt;
1416 </literallayout></para></listitem>
1417 Where &lt;bug-id&gt; is replaced with the specific bug ID from the
1418 Yocto Project Bugzilla instance.
1419 </itemizedlist>
1420 </para>
1421
1422 <para>
1423 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1424 wiki page:
1425 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1426 </para>
1427
1428 <para>
1429 The next two sections describe general instructions for both pushing
1430 changes upstream and for submitting changes as patches.
1431 </para>
1432
1433 <section id='pushing-a-change-upstream'>
1434 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
1435
1436 <para>
1437 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1438 <itemizedlist>
1439 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1440 <listitem><para>Stage your changes by using the <filename>git add</filename>
1441 command on each file you changed.</para></listitem>
1442 <listitem><para>Commit the change by using the <filename>git commit</filename>
1443 command and push it to the "contrib" repository.
1444 Be sure to provide a commit message that follows the project’s commit message standards
1445 as described earlier.</para></listitem>
1446 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1447 request.
1448 The Yocto Project provides two scripts that conveniently let you generate and send
1449 pull requests to the Yocto Project.
1450 These scripts are <filename>create-pull-request</filename> and
1451 <filename>send-pull-request</filename>.
1452 You can find these scripts in the <filename>scripts</filename> directory
1453 within the <link linkend='source-directory'>Source Directory</link>.</para>
1454 <para>Using these scripts correctly formats the requests without introducing any
1455 whitespace or HTML formatting.
1456 The maintainer that receives your patches needs to be able to save and apply them
1457 directly from your emails.
1458 Using these scripts is the preferred method for sending patches.</para>
1459 <para>For help on using these scripts, simply provide the
1460 <filename>-h</filename> argument as follows:
1461 <literallayout class='monospaced'>
1462 $ ~/poky/scripts/create-pull-request -h
1463 $ ~/poky/scripts/send-pull-request -h
1464 </literallayout></para></listitem>
1465 </itemizedlist>
1466 </para>
1467
1468 <para>
1469 You can find general Git information on how to push a change upstream in the
1470 <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>.
1471 </para>
1472 </section>
1473
1474 <section id='submitting-a-patch'>
1475 <title>Using Email to Submit a Patch</title>
1476
1477 <para>
1478 You can submit patches without using the <filename>create-pull-request</filename> and
1479 <filename>send-pull-request</filename> scripts described in the previous section.
1480 However, keep in mind, the preferred method is to use the scripts.
1481 </para>
1482
1483 <para>
1484 Depending on the components changed, you need to submit the email to a specific
1485 mailing list.
1486 For some guidance on which mailing list to use, see the list in the
1487 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1488 section.
1489 For a description of the available mailing lists, see the
1490 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
1491 section in the Yocto Project Reference Manual.
1492 </para>
1493
1494 <para>
1495 Here is the general procedure on how to submit a patch through email without using the
1496 scripts:
1497 <itemizedlist>
1498 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1499 <listitem><para>Stage your changes by using the <filename>git add</filename>
1500 command on each file you changed.</para></listitem>
1501 <listitem><para>Commit the change by using the
1502 <filename>git commit --signoff</filename> command.
1503 Using the <filename>--signoff</filename> option identifies you as the person
1504 making the change and also satisfies the Developer's Certificate of
1505 Origin (DCO) shown earlier.</para>
1506 <para>When you form a commit, you must follow certain standards established by the
1507 Yocto Project development team.
1508 See the earlier section
1509 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1510 for Yocto Project commit message standards.</para></listitem>
1511 <listitem><para>Format the commit into an email message.
1512 To format commits, use the <filename>git format-patch</filename> command.
1513 When you provide the command, you must include a revision list or a number of patches
1514 as part of the command.
1515 For example, either of these two commands takes your most
1516 recent single commit and formats it as an email message in
1517 the current directory:
1518 <literallayout class='monospaced'>
1519 $ git format-patch -1
1520 </literallayout>
1521 or
1522 <literallayout class='monospaced'>
1523 $ git format-patch HEAD~
1524 </literallayout></para>
1525 <para>After the command is run, the current directory contains a
1526 numbered <filename>.patch</filename> file for the commit.</para>
1527 <para>If you provide several commits as part of the command,
1528 the <filename>git format-patch</filename> command produces a
1529 series of numbered files in the current directory – one for each commit.
1530 If you have more than one patch, you should also use the
1531 <filename>--cover</filename> option with the command, which generates a
1532 cover letter as the first "patch" in the series.
1533 You can then edit the cover letter to provide a description for
1534 the series of patches.
1535 For information on the <filename>git format-patch</filename> command,
1536 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
1537 <filename>man git-format-patch</filename> command.</para>
1538 <note>If you are or will be a frequent contributor to the Yocto Project
1539 or to OpenEmbedded, you might consider requesting a contrib area and the
1540 necessary associated rights.</note></listitem>
1541 <listitem><para>Import the files into your mail client by using the
1542 <filename>git send-email</filename> command.
1543 <note>In order to use <filename>git send-email</filename>, you must have the
1544 the proper Git packages installed.
1545 For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para>
1546 <para>The <filename>git send-email</filename> command sends email by using a local
1547 or remote Mail Transport Agent (MTA) such as
1548 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
1549 <filename>smtp</filename> configuration in your Git <filename>config</filename>
1550 file.
1551 If you are submitting patches through email only, it is very important
1552 that you submit them without any whitespace or HTML formatting that
1553 either you or your mailer introduces.
1554 The maintainer that receives your patches needs to be able to save and
1555 apply them directly from your emails.
1556 A good way to verify that what you are sending will be applicable by the
1557 maintainer is to do a dry run and send them to yourself and then
1558 save and apply them as the maintainer would.</para>
1559 <para>The <filename>git send-email</filename> command is the preferred method
1560 for sending your patches since there is no risk of compromising whitespace
1561 in the body of the message, which can occur when you use your own mail client.
1562 The command also has several options that let you
1563 specify recipients and perform further editing of the email message.
1564 For information on how to use the <filename>git send-email</filename> command,
1565 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
1566 the <filename>man git-send-email</filename> command.
1567 </para></listitem>
1568 </itemizedlist>
1569 </para>
1570 </section>
1571</section>
1572</chapter>
1573<!--
1574vim: expandtab tw=80 ts=4
1575-->
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000000..0729baa0da
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,407 @@
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 OpenEmbedded build system in the Yocto Project documentation.
28 The Yocto Project provides various ancillary tools for the embedded developer
29 and also features the Sato reference User Interface, which is optimized for
30 stylus driven, low-resolution screens.
31 </para>
32
33 <para>
34 You can use the OpenEmbedded build system, which uses
35 BitBake, to develop complete Linux
36 images and associated user-space applications for architectures based
37 on ARM, MIPS, PowerPC, x86 and x86-64.
38 <note>
39 By default, using the Yocto Project creates a Poky distribution.
40 However, you can create your own distribution by providing key
41 <link linkend='metadata'>Metadata</link>.
42 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
43 section for more information.
44 </note>
45 While the Yocto Project does not provide a strict testing framework,
46 it does provide or generate for you artifacts that let you perform target-level and
47 emulated testing and debugging.
48 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
49 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
50 develop within that familiar environment.
51 </para>
52</section>
53
54<section id='getting-setup'>
55 <title>Getting Set Up</title>
56
57 <para>
58 Here is what you need to get set up to use the Yocto Project:
59 <itemizedlist>
60 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
61 Linux-based host system.
62 You will have the best results with a recent release of Fedora,
63 OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
64 and officially supported.
65 For a list of the distributions under validation and their status, see the
66 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
67 in the Yocto Project Reference Manual and the wiki page at
68 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
69 <para>
70 You should also have about 100 gigabytes of free disk space for building images.
71 </para></listitem>
72 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
73 requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
74 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
75 section in the Yocto Project Quick Start and the
76 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
77 section in the Yocto Project Reference Manual for the exact
78 package requirements and the installation commands to install
79 them for the supported distributions.
80 </para></listitem>
81 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
82 You need a release of the Yocto Project.
83 You set that up with a local <link linkend='source-directory'>Source Directory</link>
84 one of two ways depending on whether you
85 are going to contribute back into the Yocto Project or not.
86 <note>
87 Regardless of the method you use, this manual refers to the resulting local
88 hierarchical set of files as the "Source Directory."
89 </note>
90 <itemizedlist>
91 <listitem><para><emphasis>Tarball Extraction:</emphasis>
92 If you are not going to contribute back into the Yocto
93 Project, you can simply go to the
94 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>,
95 select the "Downloads" tab, and choose what you want.
96 Once you have the tarball, just extract it into a
97 directory of your choice.</para>
98 <para>For example, the following command extracts the
99 Yocto Project &DISTRO; release tarball
100 into the current working directory and sets up the local Source Directory
101 with a top-level folder named <filename>&YOCTO_POKY;</filename>:
102 <literallayout class='monospaced'>
103 $ tar xfj &YOCTO_POKY_TARBALL;
104 </literallayout></para>
105 <para>This method does not produce a local Git repository.
106 Instead, you simply end up with a snapshot of the release.</para></listitem>
107 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
108 back into the Yocto Project or you simply want to keep up
109 with the latest developments, you should use Git commands to set up a local
110 Git repository of the upstream <filename>poky</filename> source repository.
111 Doing so creates a repository with a complete history of changes and allows
112 you to easily submit your changes upstream to the project.
113 Because you clone the repository, you have access to all the Yocto Project development
114 branches and tag names used in the upstream repository.</para>
115 <note>You can view the Yocto Project Source Repositories at
116 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
117 <para>The following transcript shows how to clone the <filename>poky</filename>
118 Git repository into the current working directory.
119 The command creates the local repository in a directory named <filename>poky</filename>.
120 For information on Git used within the Yocto Project, see the
121 "<link linkend='git'>Git</link>" section.
122 <literallayout class='monospaced'>
123 $ git clone git://git.yoctoproject.org/poky
124 Cloning into 'poky'...
125 remote: Counting objects: 203728, done.
126 remote: Compressing objects: 100% (52371/52371), done.
127 remote: Total 203728 (delta 147444), reused 202891 (delta 146614)
128 Receiving objects: 100% (203728/203728), 95.54 MiB | 308 KiB/s, done.
129 Resolving deltas: 100% (147444/147444), done.
130 </literallayout></para>
131 <para>For another example of how to set up your own local Git repositories, see this
132 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
133 wiki page</ulink>, which describes how to create both <filename>poky</filename>
134 and <filename>meta-intel</filename> Git repositories.</para></listitem>
135 </itemizedlist></para></listitem>
136 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
137 If you are going to be making modifications to a supported Yocto Project kernel, you
138 need to establish local copies of the source.
139 You can find Git repositories of supported Yocto Project Kernels organized under
140 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
141 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
142 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
143 copying that cloned repository.
144 You can create the bare clone and the copy of the bare clone anywhere you like.
145 For simplicity, it is recommended that you create these structures outside of the
146 Source Directory (usually <filename>poky</filename>).</para>
147 <para>As an example, the following transcript shows how to create the bare clone
148 of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of
149 that clone.
150 <note>When you have a local Yocto Project kernel Git repository, you can
151 reference that repository rather than the upstream Git repository as
152 part of the <filename>clone</filename> command.
153 Doing so can speed up the process.</note></para>
154 <para>In the following example, the bare clone is named
155 <filename>linux-yocto-3.10.git</filename>, while the
156 copy is named <filename>my-linux-yocto-3.10-work</filename>:
157 <literallayout class='monospaced'>
158 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git
159 Cloning into bare repository 'linux-yocto-3.10.git'...
160 remote: Counting objects: 3364487, done.
161 remote: Compressing objects: 100% (507178/507178), done.
162 remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709)
163 Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done.
164 Resolving deltas: 100% (2827715/2827715), done.
165 </literallayout></para>
166 <para>Now create a clone of the bare clone just created:
167 <literallayout class='monospaced'>
168 $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work
169 Cloning into 'my-linux-yocto-3.10-work'...
170 done.
171 </literallayout></para></listitem>
172 <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
173 The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
174 The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
175 only if you are modifying and building the kernel image.
176 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
177 files that you
178 edit to point to your locally modified kernel source files and to build the kernel
179 image.
180 Pointing to these local files is much more efficient than requiring a download of the
181 kernel's source files from upstream each time you make changes to the kernel.</para>
182 <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
183 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
184 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
185 It is good practice to create this Git repository inside the Source Directory.</para>
186 <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
187 repository inside the Source Directory, which is named <filename>poky</filename>
188 in this case:
189 <literallayout class='monospaced'>
190 $ cd ~/poky
191 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
192 Cloning into 'meta-yocto-kernel-extras'...
193 remote: Counting objects: 727, done.
194 remote: Compressing objects: 100% (452/452), done.
195 remote: Total 727 (delta 260), reused 719 (delta 252)
196 Receiving objects: 100% (727/727), 536.36 KiB | 102 KiB/s, done.
197 Resolving deltas: 100% (260/260), done.
198 </literallayout></para></listitem>
199 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
200 Support Packages (BSPs):</emphasis>
201 The Yocto Project provides a layer called <filename>meta-intel</filename> and
202 it is maintained in its own separate Git repository.
203 The <filename>meta-intel</filename> layer contains many supported
204 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
205 <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
206 layer.
207 You can get set up for BSP development one of two ways: tarball extraction or
208 with a local Git repository.
209 It is a good idea to use the same method that you used to set up the Source Directory.
210 Regardless of the method you use, the Yocto Project uses the following BSP layer
211 naming scheme:
212 <literallayout class='monospaced'>
213 meta-&lt;BSP_name&gt;
214 </literallayout>
215 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
216 Here are some examples:
217 <literallayout class='monospaced'>
218 meta-crownbay
219 meta-emenlow
220 meta-n450
221 </literallayout>
222 See the
223 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
224 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
225 information on BSP Layers.
226 <itemizedlist>
227 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
228 BSP tarball from the same "Downloads" page of the
229 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
230 to get the Yocto Project release.
231 Once on the "Download" page, look to the right of the
232 page and scroll down to find the BSP tarballs.</para>
233 <para>Once you have the tarball, just extract it into a directory of your choice.
234 Again, this method just produces a snapshot of the BSP layer in the form
235 of a hierarchical directory structure.</para></listitem>
236 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
237 with a local Git repository for your Source Directory, you should also use this method
238 to set up the <filename>meta-intel</filename> Git repository.
239 You can locate the <filename>meta-intel</filename> Git repository in the
240 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
241 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
242 <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
243 the Source Directory.
244 For example, the following transcript shows the steps to clone the
245 <filename>meta-intel</filename>
246 Git repository inside the local <filename>poky</filename> Git repository.
247 <literallayout class='monospaced'>
248 $ cd ~/poky
249 $ git clone git://git.yoctoproject.org/meta-intel.git
250 Cloning into 'meta-intel'...
251 remote: Counting objects: 7366, done.
252 remote: Compressing objects: 100% (2491/2491), done.
253 remote: Total 7366 (delta 3997), reused 7299 (delta 3930)
254 Receiving objects: 100% (7366/7366), 2.31 MiB | 95 KiB/s, done.
255 Resolving deltas: 100% (3997/3997), done.
256 </literallayout></para>
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
260 set up the <filename>meta-intel</filename> Git repository.
261 </para></listitem>
262 </itemizedlist></para></listitem>
263 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
264 applications using the Eclipse Integrated Development Environment (IDE),
265 you will need this plug-in.
266 See the
267 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
268 section for more information.</para></listitem>
269 </itemizedlist>
270 </para>
271</section>
272
273<section id='building-images'>
274 <title>Building Images</title>
275
276 <para>
277 The build process creates an entire Linux distribution, including the toolchain, from source.
278 For more information on this topic, see the
279 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
280 section in the Yocto Project Quick Start.
281 </para>
282
283 <para>
284 The build process is as follows:
285 <orderedlist>
286 <listitem><para>Make sure you have set up the Source Directory described in the
287 previous section.</para></listitem>
288 <listitem><para>Initialize the build environment by sourcing a build environment
289 script.</para></listitem>
290 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
291 which is found in the
292 <link linkend='build-directory'>Build Directory</link>,
293 is set up how you want it.
294 This file defines many aspects of the build environment including
295 the target machine architecture through the
296 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
297 the development machine's processor use through the
298 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
299 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
300 a centralized tarball download directory through the
301 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
302 <listitem><para>Build the image using the <filename>bitbake</filename> command.
303 If you want information on BitBake, see the user manual included in the
304 <filename>bitbake/doc/manual</filename> directory of the
305 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
306 <listitem><para>Run the image either on the actual hardware or using the QEMU
307 emulator.</para></listitem>
308 </orderedlist>
309 </para>
310</section>
311
312<section id='using-pre-built-binaries-and-qemu'>
313 <title>Using Pre-Built Binaries and QEMU</title>
314
315 <para>
316 Another option you have to get started is to use pre-built binaries.
317 The Yocto Project provides many types of binaries with each release.
318 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
319 chapter in the Yocto Project Reference Manual
320 for descriptions of the types of binaries that ship with a Yocto Project
321 release.
322 </para>
323
324 <para>
325 Using a pre-built binary is ideal for developing software applications to run on your
326 target hardware.
327 To do this, you need to be able to access the appropriate cross-toolchain tarball for
328 the architecture on which you are developing.
329 If you are using an SDK type image, the image ships with the complete toolchain native to
330 the architecture.
331 If you are not using an SDK type image, you need to separately download and
332 install the stand-alone Yocto Project cross-toolchain tarball.
333 </para>
334
335 <para>
336 Regardless of the type of image you are using, you need to download the pre-built kernel
337 that you will boot in the QEMU emulator and then download and extract the target root
338 filesystem for your target machine’s architecture.
339 You can get architecture-specific binaries and file systems from
340 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
341 You can get installation scripts for stand-alone toolchains from
342 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
343 Once you have all your files, you set up the environment to emulate the hardware
344 by sourcing an environment setup script.
345 Finally, you start the QEMU emulator.
346 You can find details on all these steps in the
347 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
348 section of the Yocto Project Quick Start.
349 </para>
350
351 <para>
352 Using QEMU to emulate your hardware can result in speed issues
353 depending on the target and host architecture mix.
354 For example, using the <filename>qemux86</filename> image in the emulator
355 on an Intel-based 32-bit (x86) host machine is fast because the target and
356 host architectures match.
357 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
358 host can be slower.
359 But, you still achieve faithful emulation of ARM-specific issues.
360 </para>
361
362 <para>
363 To speed things up, the QEMU images support using <filename>distcc</filename>
364 to call a cross-compiler outside the emulated system.
365 If you used <filename>runqemu</filename> to start QEMU, and the
366 <filename>distccd</filename> application is present on the host system, any
367 BitBake cross-compiling toolchain available from the build system is automatically
368 used from within QEMU simply by calling <filename>distcc</filename>.
369 You can accomplish this by defining the cross-compiler variable
370 (e.g. <filename>export CC="distcc"</filename>).
371 Alternatively, if you are using a suitable SDK image or the appropriate
372 stand-alone toolchain is present,
373 the toolchain is also automatically used.
374 </para>
375
376 <note>
377 Several mechanisms exist that let you connect to the system running on the
378 QEMU emulator:
379 <itemizedlist>
380 <listitem><para>QEMU provides a framebuffer interface that makes standard
381 consoles available.</para></listitem>
382 <listitem><para>Generally, headless embedded devices have a serial port.
383 If so, you can configure the operating system of the running image
384 to use that port to run a console.
385 The connection uses standard IP networking.</para></listitem>
386 <listitem><para>SSH servers exist in some QEMU images.
387 The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
388 shell (SSH) server that runs with the root password disabled.
389 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
390 have OpenSSH instead of Dropbear.
391 Including these SSH servers allow you to use standard <filename>ssh</filename> and
392 <filename>scp</filename> commands.
393 The <filename>core-image-minimal</filename> QEMU image, however, contains no SSH
394 server.</para></listitem>
395 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
396 using a local copy of the root filesystem on the host.
397 In order to make this connection, you must extract a root filesystem tarball by using the
398 <filename>runqemu-extract-sdk</filename> command.
399 After running the command, you must then point the <filename>runqemu</filename>
400 script to the extracted directory instead of a root filesystem image file.</para></listitem>
401 </itemizedlist>
402 </note>
403</section>
404</chapter>
405<!--
406vim: expandtab tw=80 ts=4
407-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
new file mode 100644
index 0000000000..ca400fbd18
--- /dev/null
+++ b/documentation/dev-manual/dev-manual.xml
@@ -0,0 +1,102 @@
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>Sometime in 2013</date>
62 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
63 </revision>
64 </revhistory>
65
66 <copyright>
67 <year>&COPYRIGHT_YEAR;</year>
68 <holder>Linux Foundation</holder>
69 </copyright>
70
71 <legalnotice>
72 <para>
73 Permission is granted to copy, distribute and/or modify this document under
74 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
75 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
76 Creative Commons.
77 </para>
78
79 <note>
80 For the latest version of this manual associated with this
81 Yocto Project release, see the
82 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
83 from the Yocto Project website.
84 </note>
85 </legalnotice>
86
87 </bookinfo>
88
89 <xi:include href="dev-manual-intro.xml"/>
90
91 <xi:include href="dev-manual-start.xml"/>
92
93 <xi:include href="dev-manual-newbie.xml"/>
94
95 <xi:include href="dev-manual-model.xml"/>
96
97 <xi:include href="dev-manual-common-tasks.xml"/>
98
99</book>
100<!--
101vim: expandtab tw=80 ts=4
102-->
diff --git a/documentation/dev-manual/dev-style.css b/documentation/dev-manual/dev-style.css
new file mode 100644
index 0000000000..23c8e74c1e
--- /dev/null
+++ b/documentation/dev-manual/dev-style.css
@@ -0,0 +1,979 @@
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
317div.informalfigure,
318div.informalexample,
319div.informaltable,
320div.figure,
321div.table,
322div.example {
323 margin: 1em 0em;
324 padding: 1em;
325 page-break-inside: avoid;
326}
327
328
329div.informalfigure p.title b,
330div.informalexample p.title b,
331div.informaltable p.title b,
332div.figure p.title b,
333div.example p.title b,
334div.table p.title b{
335 padding-top: 0em;
336 margin-top: 0em;
337 font-size: 100%;
338 font-weight: normal;
339}
340
341.mediaobject .caption,
342.mediaobject .caption p {
343 text-align: center;
344 font-size: 80%;
345 padding-top: 0.5em;
346 padding-bottom: 0.5em;
347}
348
349.epigraph {
350 padding-left: 55%;
351 margin-bottom: 1em;
352}
353
354.epigraph p {
355 text-align: left;
356}
357
358.epigraph .quote {
359 font-style: italic;
360}
361.epigraph .attribution {
362 font-style: normal;
363 text-align: right;
364}
365
366span.application {
367 font-style: italic;
368}
369
370.programlisting {
371 font-family: monospace;
372 font-size: 80%;
373 white-space: pre;
374 margin: 1.33em 0em;
375 padding: 1.33em;
376}
377
378.tip,
379.warning,
380.caution,
381.note {
382 margin-top: 1em;
383 margin-bottom: 1em;
384
385}
386
387/* force full width of table within div */
388.tip table,
389.warning table,
390.caution table,
391.note table {
392 border: none;
393 width: 100%;
394}
395
396
397.tip table th,
398.warning table th,
399.caution table th,
400.note table th {
401 padding: 0.8em 0.0em 0.0em 0.0em;
402 margin : 0em 0em 0em 0em;
403}
404
405.tip p,
406.warning p,
407.caution p,
408.note p {
409 margin-top: 0.5em;
410 margin-bottom: 0.5em;
411 padding-right: 1em;
412 text-align: left;
413}
414
415.acronym {
416 text-transform: uppercase;
417}
418
419b.keycap,
420.keycap {
421 padding: 0.09em 0.3em;
422 margin: 0em;
423}
424
425.itemizedlist li {
426 clear: none;
427}
428
429.filename {
430 font-size: medium;
431 font-family: Courier, monospace;
432}
433
434
435div.navheader, div.heading{
436 position: absolute;
437 left: 0em;
438 top: 0em;
439 width: 100%;
440 background-color: #cdf;
441 width: 100%;
442}
443
444div.navfooter, div.footing{
445 position: fixed;
446 left: 0em;
447 bottom: 0em;
448 background-color: #eee;
449 width: 100%;
450}
451
452
453div.navheader td,
454div.navfooter td {
455 font-size: 66%;
456}
457
458div.navheader table th {
459 /*font-family: Georgia, Times, serif;*/
460 /*font-size: x-large;*/
461 font-size: 80%;
462}
463
464div.navheader table {
465 border-left: 0em;
466 border-right: 0em;
467 border-top: 0em;
468 width: 100%;
469}
470
471div.navfooter table {
472 border-left: 0em;
473 border-right: 0em;
474 border-bottom: 0em;
475 width: 100%;
476}
477
478div.navheader table td a,
479div.navfooter table td a {
480 color: #777;
481 text-decoration: none;
482}
483
484/* normal text in the footer */
485div.navfooter table td {
486 color: black;
487}
488
489div.navheader table td a:visited,
490div.navfooter table td a:visited {
491 color: #444;
492}
493
494
495/* links in header and footer */
496div.navheader table td a:hover,
497div.navfooter table td a:hover {
498 text-decoration: underline;
499 background-color: transparent;
500 color: #33a;
501}
502
503div.navheader hr,
504div.navfooter hr {
505 display: none;
506}
507
508
509.qandaset tr.question td p {
510 margin: 0em 0em 1em 0em;
511 padding: 0em 0em 0em 0em;
512}
513
514.qandaset tr.answer td p {
515 margin: 0em 0em 1em 0em;
516 padding: 0em 0em 0em 0em;
517}
518.answer td {
519 padding-bottom: 1.5em;
520}
521
522.emphasis {
523 font-weight: bold;
524}
525
526
527 /************* /
528 / decorations /
529/ *************/
530
531.titlepage {
532}
533
534.part .title {
535}
536
537.subtitle {
538 border: none;
539}
540
541/*
542h1 {
543 border: none;
544}
545
546h2 {
547 border-top: solid 0.2em;
548 border-bottom: solid 0.06em;
549}
550
551h3 {
552 border-top: 0em;
553 border-bottom: solid 0.06em;
554}
555
556h4 {
557 border: 0em;
558 border-bottom: solid 0.06em;
559}
560
561h5 {
562 border: 0em;
563}
564*/
565
566.programlisting {
567 border: solid 1px;
568}
569
570div.figure,
571div.table,
572div.informalfigure,
573div.informaltable,
574div.informalexample,
575div.example {
576 border: 1px solid;
577}
578
579
580
581.tip,
582.warning,
583.caution,
584.note {
585 border: 1px solid;
586}
587
588.tip table th,
589.warning table th,
590.caution table th,
591.note table th {
592 border-bottom: 1px solid;
593}
594
595.question td {
596 border-top: 1px solid black;
597}
598
599.answer {
600}
601
602
603b.keycap,
604.keycap {
605 border: 1px solid;
606}
607
608
609div.navheader, div.heading{
610 border-bottom: 1px solid;
611}
612
613
614div.navfooter, div.footing{
615 border-top: 1px solid;
616}
617
618 /********* /
619 / colors /
620/ *********/
621
622body {
623 color: #333;
624 background: white;
625}
626
627a {
628 background: transparent;
629}
630
631a:hover {
632 background-color: #dedede;
633}
634
635
636h1,
637h2,
638h3,
639h4,
640h5,
641h6,
642h7,
643h8 {
644 background-color: transparent;
645}
646
647hr {
648 border-color: #aaa;
649}
650
651
652.tip, .warning, .caution, .note {
653 border-color: #fff;
654}
655
656
657.tip table th,
658.warning table th,
659.caution table th,
660.note table th {
661 border-bottom-color: #fff;
662}
663
664
665.warning {
666 background-color: #f0f0f2;
667}
668
669.caution {
670 background-color: #f0f0f2;
671}
672
673.tip {
674 background-color: #f0f0f2;
675}
676
677.note {
678 background-color: #f0f0f2;
679}
680
681.glossary dl dt,
682.variablelist dl dt,
683.variablelist dl dt span.term {
684 color: #044;
685}
686
687div.figure,
688div.table,
689div.example,
690div.informalfigure,
691div.informaltable,
692div.informalexample {
693 border-color: #aaa;
694}
695
696pre.programlisting {
697 color: black;
698 background-color: #fff;
699 border-color: #aaa;
700 border-width: 2px;
701}
702
703.guimenu,
704.guilabel,
705.guimenuitem {
706 background-color: #eee;
707}
708
709
710b.keycap,
711.keycap {
712 background-color: #eee;
713 border-color: #999;
714}
715
716
717div.navheader {
718 border-color: black;
719}
720
721
722div.navfooter {
723 border-color: black;
724}
725
726
727 /*********** /
728 / graphics /
729/ ***********/
730
731/*
732body {
733 background-image: url("images/body_bg.jpg");
734 background-attachment: fixed;
735}
736
737.navheader,
738.note,
739.tip {
740 background-image: url("images/note_bg.jpg");
741 background-attachment: fixed;
742}
743
744.warning,
745.caution {
746 background-image: url("images/warning_bg.jpg");
747 background-attachment: fixed;
748}
749
750.figure,
751.informalfigure,
752.example,
753.informalexample,
754.table,
755.informaltable {
756 background-image: url("images/figure_bg.jpg");
757 background-attachment: fixed;
758}
759
760*/
761h1,
762h2,
763h3,
764h4,
765h5,
766h6,
767h7{
768}
769
770/*
771Example of how to stick an image as part of the title.
772
773div.article .titlepage .title
774{
775 background-image: url("figures/white-on-black.png");
776 background-position: center;
777 background-repeat: repeat-x;
778}
779*/
780
781div.preface .titlepage .title,
782div.colophon .title,
783div.chapter .titlepage .title,
784div.article .titlepage .title
785{
786}
787
788div.section div.section .titlepage .title,
789div.sect2 .titlepage .title {
790 background: none;
791}
792
793
794h1.title {
795 background-color: transparent;
796 background-image: url("figures/yocto-project-bw.png");
797 background-repeat: no-repeat;
798 height: 256px;
799 text-indent: -9000px;
800 overflow:hidden;
801}
802
803h2.subtitle {
804 background-color: transparent;
805 text-indent: -9000px;
806 overflow:hidden;
807 width: 0px;
808 display: none;
809}
810
811 /*************************************** /
812 / pippin.gimp.org specific alterations /
813/ ***************************************/
814
815/*
816div.heading, div.navheader {
817 color: #777;
818 font-size: 80%;
819 padding: 0;
820 margin: 0;
821 text-align: left;
822 position: absolute;
823 top: 0px;
824 left: 0px;
825 width: 100%;
826 height: 50px;
827 background: url('/gfx/heading_bg.png') transparent;
828 background-repeat: repeat-x;
829 background-attachment: fixed;
830 border: none;
831}
832
833div.heading a {
834 color: #444;
835}
836
837div.footing, div.navfooter {
838 border: none;
839 color: #ddd;
840 font-size: 80%;
841 text-align:right;
842
843 width: 100%;
844 padding-top: 10px;
845 position: absolute;
846 bottom: 0px;
847 left: 0px;
848
849 background: url('/gfx/footing_bg.png') transparent;
850}
851*/
852
853
854
855 /****************** /
856 / nasty ie tweaks /
857/ ******************/
858
859/*
860div.heading, div.navheader {
861 width:expression(document.body.clientWidth + "px");
862}
863
864div.footing, div.navfooter {
865 width:expression(document.body.clientWidth + "px");
866 margin-left:expression("-5em");
867}
868body {
869 padding:expression("4em 5em 0em 5em");
870}
871*/
872
873 /**************************************** /
874 / mozilla vendor specific css extensions /
875/ ****************************************/
876/*
877div.navfooter, div.footing{
878 -moz-opacity: 0.8em;
879}
880
881div.figure,
882div.table,
883div.informalfigure,
884div.informaltable,
885div.informalexample,
886div.example,
887.tip,
888.warning,
889.caution,
890.note {
891 -moz-border-radius: 0.5em;
892}
893
894b.keycap,
895.keycap {
896 -moz-border-radius: 0.3em;
897}
898*/
899
900table tr td table tr td {
901 display: none;
902}
903
904
905hr {
906 display: none;
907}
908
909table {
910 border: 0em;
911}
912
913 .photo {
914 float: right;
915 margin-left: 1.5em;
916 margin-bottom: 1.5em;
917 margin-top: 0em;
918 max-width: 17em;
919 border: 1px solid gray;
920 padding: 3px;
921 background: white;
922}
923 .seperator {
924 padding-top: 2em;
925 clear: both;
926 }
927
928 #validators {
929 margin-top: 5em;
930 text-align: right;
931 color: #777;
932 }
933 @media print {
934 body {
935 font-size: 8pt;
936 }
937 .noprint {
938 display: none;
939 }
940 }
941
942
943.tip,
944.note {
945 background: #f0f0f2;
946 color: #333;
947 padding: 20px;
948 margin: 20px;
949}
950
951.tip h3,
952.note h3 {
953 padding: 0em;
954 margin: 0em;
955 font-size: 2em;
956 font-weight: bold;
957 color: #333;
958}
959
960.tip a,
961.note a {
962 color: #333;
963 text-decoration: underline;
964}
965
966.footnote {
967 font-size: small;
968 color: #333;
969}
970
971/* Changes the announcement text */
972.tip h3,
973.warning h3,
974.caution h3,
975.note h3 {
976 font-size:large;
977 color: #00557D;
978}
979
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..1ccd9c3e3b
--- /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..4fdf42f89c
--- /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..edd9e82af7
--- /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/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..7f1e5ca118
--- /dev/null
+++ b/documentation/dev-manual/figures/yp-download.png
Binary files differ
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-28 15:19:26 +0000