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.xml7381
-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.xml207
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2069
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml1687
-rw-r--r--documentation/dev-manual/dev-manual-start.xml415
-rw-r--r--documentation/dev-manual/dev-manual.xml107
-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 -> 42751 bytes
-rw-r--r--documentation/dev-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/dev-manual/figures/git-workflow.pngbin0 -> 26586 bytes
-rw-r--r--documentation/dev-manual/figures/index-downloads.pngbin0 -> 100374 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin0 -> 35561 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-1.pngbin0 -> 35839 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-2-generic.pngbin0 -> 39931 bytes
-rw-r--r--documentation/dev-manual/figures/recipe-workflow.pngbin0 -> 48276 bytes
-rw-r--r--documentation/dev-manual/figures/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/dev-manual/figures/yp-download.pngbin0 -> 193275 bytes
20 files changed, 12882 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
new file mode 100644
index 0000000000..445ca1750b
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,7381 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='extendpoky'>
6
7<title>Common Tasks</title>
8 <para>
9 This chapter describes fundamental procedures such as creating layers,
10 adding new software packages, extending or customizing images,
11 porting work to new hardware (adding a new machine), and so forth.
12 You will find that the procedures documented here occur often in the
13 development cycle using the Yocto Project.
14 </para>
15
16 <section id="understanding-and-creating-layers">
17 <title>Understanding and Creating Layers</title>
18
19 <para>
20 The OpenEmbedded build system supports organizing
21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from
23 each other.
24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular your Metadata, the easier
27 it is to cope with future changes.
28 </para>
29
30 <para>
31 To illustrate how layers are used to keep things modular, consider
32 machine customizations.
33 These types of customizations typically reside in a special layer,
34 rather than a general layer, called a Board Support Package (BSP)
35 Layer.
36 Furthermore, the machine customizations should be isolated from
37 recipes and Metadata that support a new GUI environment,
38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
44 with those machine-specific changes.
45 You can accomplish this through a recipe that is a BitBake append
46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
48 </para>
49
50 <para>
51 </para>
52
53 <section id='yocto-project-layers'>
54 <title>Layers</title>
55
56 <para>
57 The <link linkend='source-directory'>Source Directory</link>
58 contains both general layers and BSP
59 layers right out of the box.
60 You can easily identify layers that ship with a
61 Yocto Project release in the Source Directory by their
62 folder names.
63 Folders that represent layers typically have names that begin with
64 the string <filename>meta-</filename>.
65 <note>
66 It is not a requirement that a layer name begin with the
67 prefix <filename>meta-</filename>, but it is a commonly
68 accepted standard in the Yocto Project community.
69 </note>
70 For example, when you set up the Source Directory structure,
71 you will see several layers:
72 <filename>meta</filename>,
73 <filename>meta-skeleton</filename>,
74 <filename>meta-yocto</filename>, and
75 <filename>meta-yocto-bsp</filename>.
76 Each of these folders represents a distinct layer.
77 </para>
78
79 <para>
80 As another example, if you set up a local copy of the
81 <filename>meta-intel</filename> Git repository
82 and then explore the folder of that general layer,
83 you will discover many Intel-specific BSP layers inside.
84 For more information on BSP layers, see the
85 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
86 section in the Yocto Project Board Support Package (BSP)
87 Developer's Guide.
88 </para>
89 </section>
90
91 <section id='creating-your-own-layer'>
92 <title>Creating Your Own Layer</title>
93
94 <para>
95 It is very easy to create your own layers to use with the
96 OpenEmbedded build system.
97 The Yocto Project ships with scripts that speed up creating
98 general layers and BSP layers.
99 This section describes the steps you perform by hand to create
100 a layer so that you can better understand them.
101 For information about the layer-creation scripts, see the
102 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
103 section in the Yocto Project Board Support Package (BSP)
104 Developer's Guide and the
105 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
106 section further down in this manual.
107 </para>
108
109 <para>
110 Follow these general steps to create your layer:
111 <orderedlist>
112 <listitem><para><emphasis>Check Existing Layers:</emphasis>
113 Before creating a new layer, you should be sure someone
114 has not already created a layer containing the Metadata
115 you need.
116 You can see the
117 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
118 for a list of layers from the OpenEmbedded community
119 that can be used in the Yocto Project.
120 </para></listitem>
121 <listitem><para><emphasis>Create a Directory:</emphasis>
122 Create the directory for your layer.
123 While not strictly required, prepend the name of the
124 folder with the string <filename>meta-</filename>.
125 For example:
126 <literallayout class='monospaced'>
127 meta-mylayer
128 meta-GUI_xyz
129 meta-mymachine
130 </literallayout>
131 </para></listitem>
132 <listitem><para><emphasis>Create a Layer Configuration
133 File:</emphasis>
134 Inside your new layer folder, you need to create a
135 <filename>conf/layer.conf</filename> file.
136 It is easiest to take an existing layer configuration
137 file and copy that to your layer's
138 <filename>conf</filename> directory and then modify the
139 file as needed.</para>
140 <para>The
141 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
142 demonstrates the required syntax:
143 <literallayout class='monospaced'>
144 # We have a conf and classes directory, add to BBPATH
145 BBPATH .= ":${LAYERDIR}"
146
147 # We have recipes-* directories, add to BBFILES
148 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
149 ${LAYERDIR}/recipes-*/*/*.bbappend"
150
151 BBFILE_COLLECTIONS += "yoctobsp"
152 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
153 BBFILE_PRIORITY_yoctobsp = "5"
154 LAYERVERSION_yoctobsp = "2"
155 </literallayout></para>
156 <para>Here is an explanation of the example:
157 <itemizedlist>
158 <listitem><para>The configuration and
159 classes directory is appended to
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
161 <note>
162 All non-distro layers, which include all BSP
163 layers, are expected to append the layer
164 directory to the
165 <filename>BBPATH</filename>.
166 On the other hand, distro layers, such as
167 <filename>meta-yocto</filename>, can choose
168 to enforce their own precedence over
169 <filename>BBPATH</filename>.
170 For an example of that syntax, see the
171 <filename>layer.conf</filename> file for
172 the <filename>meta-yocto</filename> layer.
173 </note></para></listitem>
174 <listitem><para>The recipes for the layers are
175 appended to
176 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
177 </para></listitem>
178 <listitem><para>The
179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
180 variable is then appended with the layer name.
181 </para></listitem>
182 <listitem><para>The
183 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
184 variable is set to a regular expression and is
185 used to match files from
186 <filename>BBFILES</filename> into a particular
187 layer.
188 In this case,
189 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
190 is used to make <filename>BBFILE_PATTERN</filename> match within the
191 layer's path.</para></listitem>
192 <listitem><para>The
193 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
194 variable then assigns a priority to the layer.
195 Applying priorities is useful in situations
196 where the same package might appear in multiple
197 layers and allows you to choose the layer
198 that takes precedence.</para></listitem>
199 <listitem><para>The
200 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
201 variable optionally specifies the version of a
202 layer as a single number.</para></listitem>
203 </itemizedlist></para>
204 <para>Note the use of the
205 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
206 variable, which expands to the directory of the current
207 layer.</para>
208 <para>Through the use of the <filename>BBPATH</filename>
209 variable, BitBake locates class files
210 (<filename>.bbclass</filename>),
211 configuration files, and files that are included
212 with <filename>include</filename> and
213 <filename>require</filename> statements.
214 For these cases, BitBake uses the first file that
215 matches the name found in <filename>BBPATH</filename>.
216 This is similar to the way the <filename>PATH</filename>
217 variable is used for binaries.
218 It is recommended, therefore, that you use unique
219 class and configuration
220 filenames in your custom layer.</para></listitem>
221 <listitem><para><emphasis>Add Content:</emphasis> Depending
222 on the type of layer, add the content.
223 If the layer adds support for a machine, add the machine
224 configuration in a <filename>conf/machine/</filename>
225 file within the layer.
226 If the layer adds distro policy, add the distro
227 configuration in a <filename>conf/distro/</filename>
228 file within the layer.
229 If the layer introduces new recipes, put the recipes
230 you need in <filename>recipes-*</filename>
231 subdirectories within the layer.
232 <note>In order to be compliant with the Yocto Project,
233 a layer must contain a
234 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
235 </note></para></listitem>
236 </orderedlist>
237 </para>
238 </section>
239
240 <section id='best-practices-to-follow-when-creating-layers'>
241 <title>Best Practices to Follow When Creating Layers</title>
242
243 <para>
244 To create layers that are easier to maintain and that will
245 not impact builds for other machines, you should consider the
246 information in the following sections.
247 </para>
248
249 <section id='avoid-overlaying-entire-recipes'>
250 <title>Avoid "Overlaying" Entire Recipes</title>
251
252 <para>
253 Avoid "overlaying" entire recipes from other layers in your
254 configuration.
255 In other words, do not copy an entire recipe into your
256 layer and then modify it.
257 Rather, use an append file (<filename>.bbappend</filename>)
258 to override
259 only those parts of the original recipe you need to modify.
260 </para>
261 </section>
262
263 <section id='avoid-duplicating-include-files'>
264 <title>Avoid Duplicating Include Files</title>
265
266 <para>
267 Avoid duplicating include files.
268 Use append files (<filename>.bbappend</filename>)
269 for each recipe
270 that uses an include file.
271 Or, if you are introducing a new recipe that requires
272 the included file, use the path relative to the original
273 layer directory to refer to the file.
274 For example, use
275 <filename>require recipes-core/somepackage/somefile.inc</filename>
276 instead of <filename>require somefile.inc</filename>.
277 If you're finding you have to overlay the include file,
278 it could indicate a deficiency in the include file in
279 the layer to which it originally belongs.
280 If this is the case, you need to address that deficiency
281 instead of overlaying the include file.
282 </para>
283
284 <para>
285 For example, consider how support plug-ins for the Qt 4
286 database are configured.
287 The Source Directory does not have MySQL or PostgreSQL.
288 However, OpenEmbedded's layer <filename>meta-oe</filename>
289 does.
290 Consequently, <filename>meta-oe</filename> uses
291 append files to modify the
292 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
293 enable the appropriate plug-ins.
294 This variable was added to the <filename>qt4.inc</filename>
295 include file in the Source Directory specifically to allow
296 the <filename>meta-oe</filename> layer to be able to control
297 which plug-ins are built.
298 </para>
299 </section>
300
301 <section id='structure-your-layers'>
302 <title>Structure Your Layers</title>
303
304 <para>
305 Proper use of overrides within append files and placement
306 of machine-specific files within your layer can ensure that
307 a build is not using the wrong Metadata and negatively
308 impacting a build for a different machine.
309 Following are some examples:
310 <itemizedlist>
311 <listitem><para><emphasis>Modifying Variables to Support
312 a Different Machine:</emphasis>
313 Suppose you have a layer named
314 <filename>meta-one</filename> that adds support
315 for building machine "one".
316 To do so, you use an append file named
317 <filename>base-files.bbappend</filename> and
318 create a dependency on "foo" by altering the
319 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
320 variable:
321 <literallayout class='monospaced'>
322 DEPENDS = "foo"
323 </literallayout>
324 The dependency is created during any build that
325 includes the layer
326 <filename>meta-one</filename>.
327 However, you might not want this dependency
328 for all machines.
329 For example, suppose you are building for
330 machine "two" but your
331 <filename>bblayers.conf</filename> file has the
332 <filename>meta-one</filename> layer included.
333 During the build, the
334 <filename>base-files</filename> for machine
335 "two" will also have the dependency on
336 <filename>foo</filename>.</para>
337 <para>To make sure your changes apply only when
338 building machine "one", use a machine override
339 with the <filename>DEPENDS</filename> statement:
340 <literallayout class='monospaced'>
341 DEPENDS_one = "foo"
342 </literallayout>
343 You should follow the same strategy when using
344 <filename>_append</filename> and
345 <filename>_prepend</filename> operations:
346 <literallayout class='monospaced'>
347 DEPENDS_append_one = " foo"
348 DEPENDS_prepend_one = "foo "
349 </literallayout>
350 <note>
351 Avoiding "+=" and "=+" and using
352 machine-specific
353 <filename>_append</filename>
354 and <filename>_prepend</filename> operations
355 is recommended as well.
356 </note></para></listitem>
357 <listitem><para><emphasis>Place Machine-Specific Files
358 in Machine-Specific Locations:</emphasis>
359 When you have a base recipe, such as
360 <filename>base-files.bb</filename>, that
361 contains a
362 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
363 statement to a file, you can use an append file
364 to cause the build to use your own version of
365 the file.
366 For example, an append file in your layer at
367 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
368 could extend
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
370 using
371 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
372 as follows:
373 <literallayout class='monospaced'>
374 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
375 </literallayout>
376 The build for machine "one" will pick up your
377 machine-specific file as long as you have the
378 file in
379 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
380 However, if you are building for a different
381 machine and the
382 <filename>bblayers.conf</filename> file includes
383 the <filename>meta-one</filename> layer and
384 the location of your machine-specific file is
385 the first location where that file is found
386 according to <filename>FILESPATH</filename>,
387 builds for all machines will also use that
388 machine-specific file.</para>
389 <para>You can make sure that a machine-specific
390 file is used for a particular machine by putting
391 the file in a subdirectory specific to the
392 machine.
393 For example, rather than placing the file in
394 <filename>meta-one/recipes-core/base-files/base-files/</filename>
395 as shown above, put it in
396 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
397 Not only does this make sure the file is used
398 only when building for machine "one", but the
399 build process locates the file more quickly.</para>
400 <para>In summary, you need to place all files
401 referenced from <filename>SRC_URI</filename>
402 in a machine-specific subdirectory within the
403 layer in order to restrict those files to
404 machine-specific builds.</para></listitem>
405 </itemizedlist>
406 </para>
407 </section>
408
409 <section id='other-recommendations'>
410 <title>Other Recommendations</title>
411
412 <para>
413 We also recommend the following:
414 <itemizedlist>
415 <listitem><para>Store custom layers in a Git repository
416 that uses the
417 <filename>meta-&lt;layer_name&gt;</filename> format.
418 </para></listitem>
419 <listitem><para>Clone the repository alongside other
420 <filename>meta</filename> directories in the
421 <link linkend='source-directory'>Source Directory</link>.
422 </para></listitem>
423 </itemizedlist>
424 Following these recommendations keeps your Source Directory and
425 its configuration entirely inside the Yocto Project's core
426 base.
427 </para>
428 </section>
429 </section>
430
431 <section id='enabling-your-layer'>
432 <title>Enabling Your Layer</title>
433
434 <para>
435 Before the OpenEmbedded build system can use your new layer,
436 you need to enable it.
437 To enable your layer, simply add your layer's path to the
438 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
439 variable in your <filename>conf/bblayers.conf</filename> file,
440 which is found in the
441 <link linkend='build-directory'>Build Directory</link>.
442 The following example shows how to enable a layer named
443 <filename>meta-mylayer</filename>:
444 <literallayout class='monospaced'>
445 LCONF_VERSION = "6"
446
447 BBPATH = "${TOPDIR}"
448 BBFILES ?= ""
449
450 BBLAYERS ?= " \
451 $HOME/poky/meta \
452 $HOME/poky/meta-yocto \
453 $HOME/poky/meta-yocto-bsp \
454 $HOME/poky/meta-mylayer \
455 "
456
457 BBLAYERS_NON_REMOVABLE ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 "
461 </literallayout>
462 </para>
463
464 <para>
465 BitBake parses each <filename>conf/layer.conf</filename> file
466 as specified in the <filename>BBLAYERS</filename> variable
467 within the <filename>conf/bblayers.conf</filename> file.
468 During the processing of each
469 <filename>conf/layer.conf</filename> file, BitBake adds the
470 recipes, classes and configurations contained within the
471 particular layer to the source directory.
472 </para>
473 </section>
474
475 <section id='using-bbappend-files'>
476 <title>Using .bbappend Files</title>
477
478 <para>
479 Recipes used to append Metadata to other recipes are called
480 BitBake append files.
481 BitBake append files use the <filename>.bbappend</filename> file
482 type suffix, while the corresponding recipes to which Metadata
483 is being appended use the <filename>.bb</filename> file type
484 suffix.
485 </para>
486
487 <para>
488 A <filename>.bbappend</filename> file allows your layer to make
489 additions or changes to the content of another layer's recipe
490 without having to copy the other recipe into your layer.
491 Your <filename>.bbappend</filename> file resides in your layer,
492 while the main <filename>.bb</filename> recipe file to
493 which you are appending Metadata resides in a different layer.
494 </para>
495
496 <para>
497 Append files must have the same root names as their corresponding
498 recipes.
499 For example, the append file
500 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
501 <filename>someapp_&DISTRO;.bb</filename>.
502 This means the original recipe and append file names are version
503 number-specific.
504 If the corresponding recipe is renamed to update to a newer
505 version, the corresponding <filename>.bbappend</filename> file must
506 be renamed (and possibly updated) as well.
507 During the build process, BitBake displays an error on starting
508 if it detects a <filename>.bbappend</filename> file that does
509 not have a corresponding recipe with a matching name.
510 See the
511 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
512 variable for information on how to handle this error.
513 </para>
514
515 <para>
516 Being able to append information to an existing recipe not only
517 avoids duplication, but also automatically applies recipe
518 changes in a different layer to your layer.
519 If you were copying recipes, you would have to manually merge
520 changes as they occur.
521 </para>
522
523 <para>
524 As an example, consider the main formfactor recipe and a
525 corresponding formfactor append file both from the
526 <link linkend='source-directory'>Source Directory</link>.
527 Here is the main formfactor recipe, which is named
528 <filename>formfactor_0.0.bb</filename> and located in the
529 "meta" layer at
530 <filename>meta/recipes-bsp/formfactor</filename>:
531 <literallayout class='monospaced'>
532 SUMMARY = "Device formfactor information"
533 SECTION = "base"
534 LICENSE = "MIT"
535 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
536 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
537 PR = "r44"
538
539 SRC_URI = "file://config file://machconfig"
540 S = "${WORKDIR}"
541
542 PACKAGE_ARCH = "${MACHINE_ARCH}"
543 INHIBIT_DEFAULT_DEPS = "1"
544
545 do_install() {
546 # Only install file if it has a contents
547 install -d ${D}${sysconfdir}/formfactor/
548 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
549 if [ -s "${S}/machconfig" ]; then
550 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
551 fi
552 }
553 </literallayout>
554 In the main recipe, note the
555 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
556 variable, which tells the OpenEmbedded build system where to
557 find files during the build.
558 </para>
559
560 <para>
561 Following is the append file, which is named
562 <filename>formfactor_0.0.bbappend</filename> and is from the
563 Crown Bay BSP Layer named
564 <filename>meta-intel/meta-crownbay</filename>.
565 The file is in <filename>recipes-bsp/formfactor</filename>:
566 <literallayout class='monospaced'>
567 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
568 </literallayout>
569 </para>
570
571 <para>
572 By default, the build system uses the
573 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
574 variable to locate files.
575 This append file extends the locations by setting the
576 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
577 variable.
578 Setting this variable in the <filename>.bbappend</filename>
579 file is the most reliable and recommended method for adding
580 directories to the search path used by the build system
581 to find files.
582 </para>
583
584 <para>
585 The statement in this example extends the directories to include
586 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
587 which resolves to a directory named
588 <filename>formfactor</filename> in the same directory
589 in which the append file resides (i.e.
590 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
591 This implies that you must have the supporting directory
592 structure set up that will contain any files or patches you
593 will be including from the layer.
594 </para>
595
596 <para>
597 Using the immediate expansion assignment operator
598 <filename>:=</filename> is important because of the reference to
599 <filename>THISDIR</filename>.
600 The trailing colon character is important as it ensures that
601 items in the list remain colon-separated.
602 <note>
603 <para>
604 BitBake automatically defines the
605 <filename>THISDIR</filename> variable.
606 You should never set this variable yourself.
607 Using "_prepend" ensures your path will
608 be searched prior to other paths in the final list.
609 </para>
610
611 <para>
612 Also, not all append files add extra files.
613 Many append files simply exist to add build options
614 (e.g. <filename>systemd</filename>).
615 For these cases, it is not necessary to use the
616 "_prepend" part of the statement.
617 </para>
618 </note>
619 </para>
620 </section>
621
622 <section id='prioritizing-your-layer'>
623 <title>Prioritizing Your Layer</title>
624
625 <para>
626 Each layer is assigned a priority value.
627 Priority values control which layer takes precedence if there
628 are recipe files with the same name in multiple layers.
629 For these cases, the recipe file from the layer with a higher
630 priority number takes precedence.
631 Priority values also affect the order in which multiple
632 <filename>.bbappend</filename> files for the same recipe are
633 applied.
634 You can either specify the priority manually, or allow the
635 build system to calculate it based on the layer's dependencies.
636 </para>
637
638 <para>
639 To specify the layer's priority manually, use the
640 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
641 variable.
642 For example:
643 <literallayout class='monospaced'>
644 BBFILE_PRIORITY_mylayer = "1"
645 </literallayout>
646 </para>
647
648 <note>
649 <para>It is possible for a recipe with a lower version number
650 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
651 in a layer that has a higher priority to take precedence.</para>
652 <para>Also, the layer priority does not currently affect the
653 precedence order of <filename>.conf</filename>
654 or <filename>.bbclass</filename> files.
655 Future versions of BitBake might address this.</para>
656 </note>
657 </section>
658
659 <section id='managing-layers'>
660 <title>Managing Layers</title>
661
662 <para>
663 You can use the BitBake layer management tool to provide a view
664 into the structure of recipes across a multi-layer project.
665 Being able to generate output that reports on configured layers
666 with their paths and priorities and on
667 <filename>.bbappend</filename> files and their applicable
668 recipes can help to reveal potential problems.
669 </para>
670
671 <para>
672 Use the following form when running the layer management tool.
673 <literallayout class='monospaced'>
674 $ bitbake-layers &lt;command&gt; [arguments]
675 </literallayout>
676 The following list describes the available commands:
677 <itemizedlist>
678 <listitem><para><filename><emphasis>help:</emphasis></filename>
679 Displays general help or help on a specified command.
680 </para></listitem>
681 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
682 Shows the current configured layers.
683 </para></listitem>
684 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
685 Lists available recipes and the layers that provide them.
686 </para></listitem>
687 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
688 Lists overlayed recipes.
689 A recipe is overlayed when a recipe with the same name
690 exists in another layer that has a higher layer
691 priority.
692 </para></listitem>
693 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
694 Lists <filename>.bbappend</filename> files and the
695 recipe files to which they apply.
696 </para></listitem>
697 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
698 Lists dependency relationships between recipes that
699 cross layer boundaries.
700 </para></listitem>
701 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
702 Flattens the layer configuration into a separate output
703 directory.
704 Flattening your layer configuration builds a "flattened"
705 directory that contains the contents of all layers,
706 with any overlayed recipes removed and any
707 <filename>.bbappend</filename> files appended to the
708 corresponding recipes.
709 You might have to perform some manual cleanup of the
710 flattened layer as follows:
711 <itemizedlist>
712 <listitem><para>Non-recipe files (such as patches)
713 are overwritten.
714 The flatten command shows a warning for these
715 files.
716 </para></listitem>
717 <listitem><para>Anything beyond the normal layer
718 setup has been added to the
719 <filename>layer.conf</filename> file.
720 Only the lowest priority layer's
721 <filename>layer.conf</filename> is used.
722 </para></listitem>
723 <listitem><para>Overridden and appended items from
724 <filename>.bbappend</filename> files need to be
725 cleaned up.
726 The contents of each
727 <filename>.bbappend</filename> end up in the
728 flattened recipe.
729 However, if there are appended or changed
730 variable values, you need to tidy these up
731 yourself.
732 Consider the following example.
733 Here, the <filename>bitbake-layers</filename>
734 command adds the line
735 <filename>#### bbappended ...</filename> so that
736 you know where the following lines originate:
737 <literallayout class='monospaced'>
738 ...
739 DESCRIPTION = "A useful utility"
740 ...
741 EXTRA_OECONF = "--enable-something"
742 ...
743
744 #### bbappended from meta-anotherlayer ####
745
746 DESCRIPTION = "Customized utility"
747 EXTRA_OECONF += "--enable-somethingelse"
748 </literallayout>
749 Ideally, you would tidy up these utilities as
750 follows:
751 <literallayout class='monospaced'>
752 ...
753 DESCRIPTION = "Customized utility"
754 ...
755 EXTRA_OECONF = "--enable-something --enable-somethingelse"
756 ...
757 </literallayout></para></listitem>
758 </itemizedlist></para></listitem>
759 </itemizedlist>
760 </para>
761 </section>
762
763 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
764 <title>Creating a General Layer Using the yocto-layer Script</title>
765
766 <para>
767 The <filename>yocto-layer</filename> script simplifies
768 creating a new general layer.
769 <note>
770 For information on BSP layers, see the
771 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
772 section in the Yocto Project Board Specific (BSP)
773 Developer's Guide.
774 </note>
775 The default mode of the script's operation is to prompt you for
776 information needed to generate the layer:
777 <itemizedlist>
778 <listitem><para>The layer priority
779 </para></listitem>
780 <listitem><para>Whether or not to create a sample recipe.
781 </para></listitem>
782 <listitem><para>Whether or not to create a sample
783 append file.
784 </para></listitem>
785 </itemizedlist>
786 </para>
787
788 <para>
789 Use the <filename>yocto-layer create</filename> sub-command
790 to create a new general layer.
791 In its simplest form, you can create a layer as follows:
792 <literallayout class='monospaced'>
793 $ yocto-layer create mylayer
794 </literallayout>
795 The previous example creates a layer named
796 <filename>meta-mylayer</filename> in the current directory.
797 </para>
798
799 <para>
800 As the <filename>yocto-layer create</filename> command runs,
801 default values for the prompts appear in brackets.
802 Pressing enter without supplying anything for the prompts
803 or pressing enter and providing an invalid response causes the
804 script to accept the default value.
805 Once the script completes, the new layer
806 is created in the current working directory.
807 The script names the layer by prepending
808 <filename>meta-</filename> to the name you provide.
809 </para>
810
811 <para>
812 Minimally, the script creates the following within the layer:
813 <itemizedlist>
814 <listitem><para><emphasis>The <filename>conf</filename>
815 directory:</emphasis>
816 This directory contains the layer's configuration file.
817 The root name for the file is the same as the root name
818 your provided for the layer (e.g.
819 <filename>&lt;layer&gt;.conf</filename>).
820 </para></listitem>
821 <listitem><para><emphasis>The
822 <filename>COPYING.MIT</filename> file:</emphasis>
823 The copyright and use notice for the software.
824 </para></listitem>
825 <listitem><para><emphasis>The <filename>README</filename>
826 file:</emphasis>
827 A file describing the contents of your new layer.
828 </para></listitem>
829 </itemizedlist>
830 </para>
831
832 <para>
833 If you choose to generate a sample recipe file, the script
834 prompts you for the name for the recipe and then creates it
835 in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
836 The script creates a <filename>.bb</filename> file and a
837 directory, which contains a sample
838 <filename>helloworld.c</filename> source file, along with
839 a sample patch file.
840 If you do not provide a recipe name, the script uses
841 "example".
842 </para>
843
844 <para>
845 If you choose to generate a sample append file, the script
846 prompts you for the name for the file and then creates it
847 in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
848 The script creates a <filename>.bbappend</filename> file and a
849 directory, which contains a sample patch file.
850 If you do not provide a recipe name, the script uses
851 "example".
852 The script also prompts you for the version of the append file.
853 The version should match the recipe to which the append file
854 is associated.
855 </para>
856
857 <para>
858 The easiest way to see how the <filename>yocto-layer</filename>
859 script works is to experiment with the script.
860 You can also read the usage information by entering the
861 following:
862 <literallayout class='monospaced'>
863 $ yocto-layer help
864 </literallayout>
865 </para>
866
867 <para>
868 Once you create your general layer, you must add it to your
869 <filename>bblayers.conf</filename> file.
870 Here is an example where a layer named
871 <filename>meta-mylayer</filename> is added:
872 <literallayout class='monospaced'>
873 BBLAYERS = ?" \
874 /usr/local/src/yocto/meta \
875 /usr/local/src/yocto/meta-yocto \
876 /usr/local/src/yocto/meta-yocto-bsp \
877 /usr/local/src/yocto/meta-mylayer \
878 "
879
880 BBLAYERS_NON_REMOVABLE ?= " \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 "
884 </literallayout>
885 Adding the layer to this file enables the build system to
886 locate the layer during the build.
887 </para>
888 </section>
889 </section>
890
891 <section id='usingpoky-extend-customimage'>
892 <title>Customizing Images</title>
893
894 <para>
895 You can customize images to satisfy particular requirements.
896 This section describes several methods and provides guidelines for each.
897 </para>
898
899 <section id='usingpoky-extend-customimage-localconf'>
900 <title>Customizing Images Using <filename>local.conf</filename></title>
901
902 <para>
903 Probably the easiest way to customize an image is to add a
904 package by way of the <filename>local.conf</filename>
905 configuration file.
906 Because it is limited to local use, this method generally only
907 allows you to add packages and is not as flexible as creating
908 your own customized image.
909 When you add packages using local variables this way, you need
910 to realize that these variable changes are in effect for every
911 build and consequently affect all images, which might not
912 be what you require.
913 </para>
914
915 <para>
916 To add a package to your image using the local configuration
917 file, use the
918 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
919 variable with the <filename>_append</filename> operator:
920 <literallayout class='monospaced'>
921 IMAGE_INSTALL_append = " strace"
922 </literallayout>
923 Use of the syntax is important - specifically, the space between
924 the quote and the package name, which is
925 <filename>strace</filename> in this example.
926 This space is required since the <filename>_append</filename>
927 operator does not add the space.
928 </para>
929
930 <para>
931 Furthermore, you must use <filename>_append</filename> instead
932 of the <filename>+=</filename> operator if you want to avoid
933 ordering issues.
934 The reason for this is because doing so unconditionally appends
935 to the variable and avoids ordering problems due to the
936 variable being set in image recipes and
937 <filename>.bbclass</filename> files with operators like
938 <filename>?=</filename>.
939 Using <filename>_append</filename> ensures the operation takes
940 affect.
941 </para>
942
943 <para>
944 As shown in its simplest use,
945 <filename>IMAGE_INSTALL_append</filename> affects all images.
946 It is possible to extend the syntax so that the variable
947 applies to a specific image only.
948 Here is an example:
949 <literallayout class='monospaced'>
950 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
951 </literallayout>
952 This example adds <filename>strace</filename> to the
953 <filename>core-image-minimal</filename> image only.
954 </para>
955
956 <para>
957 You can add packages using a similar approach through the
958 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
959 variable.
960 If you use this variable, only
961 <filename>core-image-*</filename> images are affected.
962 </para>
963 </section>
964
965 <section id='usingpoky-extend-customimage-imagefeatures'>
966 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
967 <filename>EXTRA_IMAGE_FEATURES</filename></title>
968
969 <para>
970 Another method for customizing your image is to enable or
971 disable high-level image features by using the
972 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
973 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
974 variables.
975 Although the functions for both variables are nearly equivalent,
976 best practices dictate using <filename>IMAGE_FEATURES</filename>
977 from within a recipe and using
978 <filename>EXTRA_IMAGE_FEATURES</filename> from within
979 your <filename>local.conf</filename> file, which is found in the
980 <link linkend='build-directory'>Build Directory</link>.
981 </para>
982
983 <para>
984 To understand how these features work, the best reference is
985 <filename>meta/classes/core-image.bbclass</filename>.
986 In summary, the file looks at the contents of the
987 <filename>IMAGE_FEATURES</filename> variable and then maps
988 those contents into a set of package groups.
989 Based on this information, the build system automatically
990 adds the appropriate packages to the
991 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
992 variable.
993 Effectively, you are enabling extra features by extending the
994 class or creating a custom class for use with specialized image
995 <filename>.bb</filename> files.
996 </para>
997
998 <para>
999 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1000 from within your local configuration file.
1001 Using a separate area from which to enable features with
1002 this variable helps you avoid overwriting the features in the
1003 image recipe that are enabled with
1004 <filename>IMAGE_FEATURES</filename>.
1005 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1006 to <filename>IMAGE_FEATURES</filename> within
1007 <filename>meta/conf/bitbake.conf</filename>.
1008 </para>
1009
1010 <para>
1011 To illustrate how you can use these variables to modify your
1012 image, consider an example that selects the SSH server.
1013 The Yocto Project ships with two SSH servers you can use
1014 with your images: Dropbear and OpenSSH.
1015 Dropbear is a minimal SSH server appropriate for
1016 resource-constrained environments, while OpenSSH is a
1017 well-known standard SSH server implementation.
1018 By default, the <filename>core-image-sato</filename> image
1019 is configured to use Dropbear.
1020 The <filename>core-image-full-cmdline</filename> and
1021 <filename>core-image-lsb</filename> images both
1022 include OpenSSH.
1023 The <filename>core-image-minimal</filename> image does not
1024 contain an SSH server.
1025 </para>
1026
1027 <para>
1028 You can customize your image and change these defaults.
1029 Edit the <filename>IMAGE_FEATURES</filename> variable
1030 in your recipe or use the
1031 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1032 <filename>local.conf</filename> file so that it configures the
1033 image you are working with to include
1034 <filename>ssh-server-dropbear</filename> or
1035 <filename>ssh-server-openssh</filename>.
1036 </para>
1037
1038 <note>
1039 See the
1040 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1041 section in the Yocto Project Reference Manual for a complete
1042 list of image features that ship with the Yocto Project.
1043 </note>
1044 </section>
1045
1046 <section id='usingpoky-extend-customimage-custombb'>
1047 <title>Customizing Images Using Custom .bb Files</title>
1048
1049 <para>
1050 You can also customize an image by creating a custom recipe
1051 that defines additional software as part of the image.
1052 The following example shows the form for the two lines you need:
1053 <literallayout class='monospaced'>
1054 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1055
1056 inherit core-image
1057 </literallayout>
1058 </para>
1059
1060 <para>
1061 Defining the software using a custom recipe gives you total
1062 control over the contents of the image.
1063 It is important to use the correct names of packages in the
1064 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1065 variable.
1066 You must use the OpenEmbedded notation and not the Debian notation for the names
1067 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
1068 </para>
1069
1070 <para>
1071 The other method for creating a custom image is to base it on an existing image.
1072 For example, if you want to create an image based on <filename>core-image-sato</filename>
1073 but add the additional package <filename>strace</filename> to the image,
1074 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1075 new <filename>.bb</filename> and add the following line to the end of the copy:
1076 <literallayout class='monospaced'>
1077 IMAGE_INSTALL += "strace"
1078 </literallayout>
1079 </para>
1080 </section>
1081
1082 <section id='usingpoky-extend-customimage-customtasks'>
1083 <title>Customizing Images Using Custom Package Groups</title>
1084
1085 <para>
1086 For complex custom images, the best approach for customizing
1087 an image is to create a custom package group recipe that is
1088 used to build the image or images.
1089 A good example of a package group recipe is
1090 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1091 The
1092 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1093 variable lists the package group packages you wish to produce.
1094 <filename>inherit packagegroup</filename> sets appropriate
1095 default values and automatically adds <filename>-dev</filename>,
1096 <filename>-dbg</filename>, and <filename>-ptest</filename>
1097 complementary packages for every package specified in
1098 <filename>PACKAGES</filename>.
1099 Note that the inherit line should be towards
1100 the top of the recipe, certainly before you set
1101 <filename>PACKAGES</filename>.
1102 For each package you specify in <filename>PACKAGES</filename>,
1103 you can use
1104 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1105 and
1106 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1107 entries to provide a list of packages the parent task package
1108 should contain.
1109 Following is an example:
1110 <literallayout class='monospaced'>
1111 DESCRIPTION = "My Custom Package Groups"
1112
1113 inherit packagegroup
1114
1115 PACKAGES = "\
1116 packagegroup-custom-apps \
1117 packagegroup-custom-tools \
1118 "
1119
1120 RDEPENDS_packagegroup-custom-apps = "\
1121 dropbear \
1122 portmap \
1123 psplash"
1124
1125 RDEPENDS_packagegroup-custom-tools = "\
1126 oprofile \
1127 oprofileui-server \
1128 lttng-control \
1129 lttng-viewer"
1130
1131 RRECOMMENDS_packagegroup-custom-tools = "\
1132 kernel-module-oprofile"
1133 </literallayout>
1134 </para>
1135
1136 <para>
1137 In the previous example, two package group packages are created with their dependencies and their
1138 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1139 <filename>packagegroup-custom-tools</filename>.
1140 To build an image using these package group packages, you need to add
1141 <filename>packagegroup-custom-apps</filename> and/or
1142 <filename>packagegroup-custom-tools</filename> to
1143 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1144 For other forms of image dependencies see the other areas of this section.
1145 </para>
1146 </section>
1147 </section>
1148
1149 <section id='new-recipe-writing-a-new-recipe'>
1150 <title>Writing a New Recipe</title>
1151
1152 <para>
1153 Recipes (<filename>.bb</filename> files) are fundamental components
1154 in the Yocto Project environment.
1155 Each software component built by the OpenEmbedded build system
1156 requires a recipe to define the component.
1157 This section describes how to create, write, and test a new
1158 recipe.
1159 <note>
1160 For information on variables that are useful for recipes and
1161 for information about recipe naming issues, see the
1162 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1163 section of the Yocto Project Reference Manual.
1164 </note>
1165 </para>
1166
1167 <section id='new-recipe-overview'>
1168 <title>Overview</title>
1169
1170 <para>
1171 The following figure shows the basic process for creating a
1172 new recipe.
1173 The remainder of the section provides details for the steps.
1174 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1175 </para>
1176 </section>
1177
1178 <section id='new-recipe-locate-a-base-recipe'>
1179 <title>Locate a Base Recipe</title>
1180
1181 <para>
1182 Before writing a recipe from scratch, it is often useful to
1183 discover whether someone else has already written one that
1184 meets (or comes close to meeting) your needs.
1185 The Yocto Project and OpenEmbedded communities maintain many
1186 recipes that might be candidates for what you are doing.
1187 You can find a good central index of these recipes in the
1188 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1189 </para>
1190
1191 <para>
1192 Working from an existing recipe or a skeleton recipe is the
1193 best way to get started.
1194 Here are some points on both methods:
1195 <itemizedlist>
1196 <listitem><para><emphasis>Locate and modify a recipe that
1197 is close to what you want to do:</emphasis>
1198 This method works when you are familiar with the
1199 current recipe space.
1200 The method does not work so well for those new to
1201 the Yocto Project or writing recipes.</para>
1202 <para>Some risks associated with this method are
1203 using a recipe that has areas totally unrelated to
1204 what you are trying to accomplish with your recipe,
1205 not recognizing areas of the recipe that you might
1206 have to add from scratch, and so forth.
1207 All these risks stem from unfamiliarity with the
1208 existing recipe space.</para></listitem>
1209 <listitem><para><emphasis>Use and modify the following
1210 skeleton recipe:</emphasis>
1211 <literallayout class='monospaced'>
1212 SUMMARY = ""
1213 HOMEPAGE = ""
1214 LICENSE = ""
1215
1216 LIC_FILES_CHKSUM = ""
1217
1218 SRC_URI = ""
1219 SRC_URI[md5sum] = ""
1220 SRC_URI[sha256sum] = ""
1221
1222 S = "${WORKDIR}/${PN}-${PV}"
1223
1224 inherit &lt;stuff&gt;
1225 </literallayout>
1226 Modifying this recipe is the recommended method for
1227 creating a new recipe.
1228 The recipe provides the fundamental areas that you need
1229 to include, exclude, or alter to fit your needs.
1230 </para></listitem>
1231 </itemizedlist>
1232 </para>
1233 </section>
1234
1235 <section id='new-recipe-storing-and-naming-the-recipe'>
1236 <title>Storing and Naming the Recipe</title>
1237
1238 <para>
1239 Once you have your base recipe, you should put it in your
1240 own layer and name it appropriately.
1241 Locating it correctly ensures that the OpenEmbedded build
1242 system can find it when you use BitBake to process the
1243 recipe.
1244 </para>
1245
1246 <itemizedlist>
1247 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1248 The OpenEmbedded build system locates your recipe
1249 through the layer's <filename>conf/layer.conf</filename>
1250 file and the
1251 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1252 variable.
1253 This variable sets up a path from which the build system can
1254 locate recipes.
1255 Here is the typical use:
1256 <literallayout class='monospaced'>
1257 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1258 ${LAYERDIR}/recipes-*/*/*.bbappend"
1259 </literallayout>
1260 Consequently, you need to be sure you locate your new recipe
1261 inside your layer such that it can be found.</para>
1262 <para>You can find more information on how layers are
1263 structured in the
1264 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1265 section.</para></listitem>
1266 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1267 When you name your recipe, you need to follow this naming
1268 convention:
1269 <literallayout class='monospaced'>
1270 &lt;basename&gt;_&lt;version&gt;.bb
1271 </literallayout>
1272 Use lower-cased characters and do not include the reserved
1273 suffixes <filename>-native</filename>,
1274 <filename>-cross</filename>, <filename>-initial</filename>,
1275 or <filename>-dev</filename> casually (i.e. do not use them
1276 as part of your recipe name unless the string applies).
1277 Here are some examples:
1278 <literallayout class='monospaced'>
1279 cups_1.7.0.bb
1280 gawk_4.0.2.bb
1281 xdg-utils_1.1.0-rc1.bb
1282 </literallayout></para></listitem>
1283 </itemizedlist>
1284 </section>
1285
1286 <section id='new-recipe-running-a-build-on-the-recipe'>
1287 <title>Running a Build on the Recipe</title>
1288
1289 <para>
1290 Creating a new recipe is usually an iterative process that
1291 requires using BitBake to process the recipe multiple times in
1292 order to progressively discover and add information to the
1293 recipe.
1294 </para>
1295
1296 <para>
1297 Assuming you have sourced a build environment setup script (i.e.
1298 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1299 or
1300 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1301 and you are in the
1302 <link linkend='build-directory'>Build Directory</link>,
1303 use BitBake to process your recipe.
1304 All you need to provide is the
1305 <filename>&lt;basename&gt;</filename> of the recipe as described
1306 in the previous section:
1307 <literallayout class='monospaced'>
1308 $ bitbake &lt;basename&gt;
1309 </literallayout>
1310
1311 </para>
1312
1313 <para>
1314 During the build, the OpenEmbedded build system creates a
1315 temporary work directory for the recipe
1316 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1317 where it keeps extracted source files, log files, intermediate
1318 compilation and packaging files, and so forth.
1319 </para>
1320
1321 <para>
1322 The temporary work directory is constructed as follows and
1323 depends on several factors:
1324 <literallayout class='monospaced'>
1325 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1326 </literallayout>
1327 As an example, assume a Source Directory top-level folder named
1328 <filename>poky</filename>, a default Build Directory at
1329 <filename>poky/build</filename>, and a
1330 <filename>qemux86-poky-linux</filename> machine target system.
1331 Furthermore, suppose your recipe is named
1332 <filename>foo_1.3.0-r0.bb</filename>.
1333 In this case, the work directory the build system uses to
1334 build the package would be as follows:
1335 <literallayout class='monospaced'>
1336 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1337 </literallayout>
1338 Inside this directory you can find sub-directories such as
1339 <filename>image</filename>, <filename>packages-split</filename>,
1340 and <filename>temp</filename>.
1341 After the build, you can examine these to determine how well
1342 the build went.
1343 <note>
1344 You can find log files for each task in the recipe's
1345 <filename>temp</filename> directory (e.g.
1346 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1347 Log files are named <filename>log.&lt;taskname&gt;</filename>
1348 (e.g. <filename>log.do_configure</filename>,
1349 <filename>log.do_fetch</filename>, and
1350 <filename>log.do_compile</filename>).
1351 </note>
1352 </para>
1353
1354 <para>
1355 You can find more information about the build process in the
1356 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1357 chapter of the Yocto Project Reference Manual.
1358 </para>
1359
1360 <para>
1361 You can also reference the following variables in the
1362 Yocto Project Reference Manual's glossary for more information:
1363 <itemizedlist>
1364 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1365 The top-level build output directory</listitem>
1366 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1367 The target system identifier</listitem>
1368 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1369 The recipe name</listitem>
1370 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1371 The epoch - (if
1372 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1373 is not specified, which is usually the case for most
1374 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1375 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1376 The recipe version</listitem>
1377 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1378 The recipe revision</listitem>
1379 </itemizedlist>
1380 </para>
1381 </section>
1382
1383 <section id='new-recipe-fetching-code'>
1384 <title>Fetching Code</title>
1385
1386 <para>
1387 The first thing your recipe must do is specify how to fetch
1388 the source files.
1389 Fetching is controlled mainly through the
1390 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1391 variable.
1392 Your recipe must have a <filename>SRC_URI</filename> variable
1393 that points to where the source is located.
1394 For a graphical representation of source locations, see the
1395 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1396 section in the Yocto Project Reference Manual.
1397 </para>
1398
1399 <para>
1400 The <filename>do_fetch</filename> task uses the prefix of
1401 each entry in the <filename>SRC_URI</filename> variable value
1402 to determine what fetcher to use to get your source files.
1403 It is the <filename>SRC_URI</filename> variable that triggers
1404 the fetcher.
1405 The <filename>do_patch</filename> task uses the variable after
1406 source is fetched to apply patches.
1407 The OpenEmbedded build system uses
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1409 for scanning directory locations for local files in
1410 <filename>SRC_URI</filename>.
1411 </para>
1412
1413 <para>
1414 The <filename>SRC_URI</filename> variable in your recipe must
1415 define each unique location for your source files.
1416 It is good practice to not hard-code pathnames in an URL used
1417 in <filename>SRC_URI</filename>.
1418 Rather than hard-code these paths, use
1419 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1420 which causes the fetch process to use the version specified in
1421 the recipe filename.
1422 Specifying the version in this manner means that upgrading the
1423 recipe to a future version is as simple as renaming the recipe
1424 to match the new version.
1425 </para>
1426
1427 <para>
1428 Here is a simple example from the
1429 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
1430 recipe where the source comes from a single tarball.
1431 Notice the use of the
1432 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1433 variable:
1434 <literallayout class='monospaced'>
1435 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1436 </literallayout>
1437 </para>
1438
1439 <para>
1440 Files mentioned in <filename>SRC_URI</filename> whose names end
1441 in a typical archive extension (e.g. <filename>.tar</filename>,
1442 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1443 <filename>.zip</filename>, and so forth), are automatically
1444 extracted during the <filename>do_unpack</filename> task.
1445 For another example that specifies these types of files, see
1446 the
1447 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1448 section.
1449 </para>
1450
1451 <para>
1452 Another way of specifying source is from an SCM.
1453 For Git repositories, you must specify
1454 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1455 and you should specify
1456 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1457 to include the revision with
1458 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1459 Here is an example from the recipe
1460 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1461 <literallayout class='monospaced'>
1462 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1463
1464 PR = "r6"
1465 PV = "1.0.5+git${SRCPV}"
1466
1467 SRC_URI = "git://git.kernel.dk/blktrace.git \
1468 file://ldflags.patch"
1469 </literallayout>
1470 </para>
1471
1472 <para>
1473 If your <filename>SRC_URI</filename> statement includes
1474 URLs pointing to individual files fetched from a remote server
1475 other than a version control system, BitBake attempts to
1476 verify the files against checksums defined in your recipe to
1477 ensure they have not been tampered with or otherwise modified
1478 since the recipe was written.
1479 Two checksums are used:
1480 <filename>SRC_URI[md5sum]</filename> and
1481 <filename>SRC_URI[sha256sum]</filename>.
1482 </para>
1483
1484 <para>
1485 If your <filename>SRC_URI</filename> variable points to
1486 more than a single URL (excluding SCM URLs), you need to
1487 provide the <filename>md5</filename> and
1488 <filename>sha256</filename> checksums for each URL.
1489 For these cases, you provide a name for each URL as part of
1490 the <filename>SRC_URI</filename> and then reference that name
1491 in the subsequent checksum statements.
1492 Here is an example:
1493 <literallayout class='monospaced'>
1494 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1495 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1496
1497 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1498 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1499
1500 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1501 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1502 </literallayout>
1503 </para>
1504
1505 <para>
1506 To find these checksums, you can comment the statements out
1507 and then attempt to build the software.
1508 The build will produce an error for each missing checksum
1509 and as part of the error message provide the correct checksum
1510 string.
1511 Once you have the correct checksums, simply copy them into your
1512 recipe for a subsequent build.
1513 </para>
1514
1515 <para>
1516 This final example is a bit more complicated and is from the
1517 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1518 recipe.
1519 The example's <filename>SRC_URI</filename> statement identifies
1520 multiple files as the source files for the recipe: a tarball, a
1521 patch file, a desktop file, and an icon.
1522 <literallayout class='monospaced'>
1523 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1524 file://xwc.patch \
1525 file://rxvt.desktop \
1526 file://rxvt.png"
1527 </literallayout>
1528 </para>
1529
1530 <para>
1531 When you specify local files using the
1532 <filename>file://</filename> URI protocol, the build system
1533 fetches files from the local machine.
1534 The path is relative to the
1535 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1536 variable and searches specific directories in a certain order:
1537 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1538 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1539 and <filename>files</filename>.
1540 The directories are assumed to be subdirectories of the
1541 directory in which the recipe or append file resides.
1542 For another example that specifies these types of files, see the
1543 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1544 section.
1545 </para>
1546
1547 <para>
1548 The previous example also specifies a patch file.
1549 Patch files are files whose names end in
1550 <filename>.patch</filename> or <filename>.diff</filename>.
1551 The build system automatically applies patches as described
1552 in the
1553 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1554 </para>
1555 </section>
1556
1557 <section id='new-recipe-unpacking-code'>
1558 <title>Unpacking Code</title>
1559
1560 <para>
1561 During the build, the <filename>do_unpack</filename> task
1562 unpacks the source with
1563 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1564 pointing to where it is unpacked.
1565 </para>
1566
1567 <para>
1568 If you are fetching your source files from an upstream source
1569 archived tarball and the tarball's internal structure matches
1570 the common convention of a top-level subdirectory named
1571 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1572 then you do not need to set <filename>S</filename>.
1573 However, if <filename>SRC_URI</filename> specifies to fetch
1574 source from an archive that does not use this convention,
1575 or from an SCM like Git or Subversion, your recipe needs to
1576 define <filename>S</filename>.
1577 </para>
1578
1579 <para>
1580 If processing your recipe using BitBake successfully unpacks
1581 the source files, you need to be sure that the directory
1582 pointed to by <filename>${S}</filename> matches the structure
1583 of the source.
1584 </para>
1585 </section>
1586
1587 <section id='new-recipe-patching-code'>
1588 <title>Patching Code</title>
1589
1590 <para>
1591 Sometimes it is necessary to patch code after it has been
1592 fetched.
1593 Any files mentioned in <filename>SRC_URI</filename> whose
1594 names end in <filename>.patch</filename> or
1595 <filename>.diff</filename> are treated as patches.
1596 The <filename>do_patch</filename> task automatically applies
1597 these patches.
1598 </para>
1599
1600 <para>
1601 The build system should be able to apply patches with the "-p1"
1602 option (i.e. one directory level in the path will be stripped
1603 off).
1604 If your patch needs to have more directory levels stripped off,
1605 specify the number of levels using the "striplevel" option in
1606 the <filename>SRC_URI</filename> entry for the patch.
1607 Alternatively, if your patch needs to be applied in a specific
1608 subdirectory that is not specified in the patch file, use the
1609 "patchdir" option in the entry.
1610 </para>
1611 </section>
1612
1613 <section id='new-recipe-licensing'>
1614 <title>Licensing</title>
1615
1616 <para>
1617 Your recipe needs to have both the
1618 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1619 and
1620 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1621 variables:
1622 <itemizedlist>
1623 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1624 This variable specifies the license for the software.
1625 If you do not know the license under which the software
1626 you are building is distributed, you should go to the
1627 source code and look for that information.
1628 Typical files containing this information include
1629 <filename>COPYING</filename>,
1630 <filename>LICENSE</filename>, and
1631 <filename>README</filename> files.
1632 You could also find the information near the top of
1633 a source file.
1634 For example, given a piece of software licensed under
1635 the GNU General Public License version 2, you would
1636 set <filename>LICENSE</filename> as follows:
1637 <literallayout class='monospaced'>
1638 LICENSE = "GPLv2"
1639 </literallayout></para>
1640 <para>The licenses you specify within
1641 <filename>LICENSE</filename> can have any name as long
1642 as you do not use spaces, since spaces are used as
1643 separators between license names.
1644 For standard licenses, use the names of the files in
1645 <filename>meta/files/common-licenses/</filename>
1646 or the <filename>SPDXLICENSEMAP</filename> flag names
1647 defined in <filename>meta/conf/licenses.conf</filename>.
1648 </para></listitem>
1649 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1650 The OpenEmbedded build system uses this variable to
1651 make sure the license text has not changed.
1652 If it has, the build produces an error and it affords
1653 you the chance to figure it out and correct the problem.
1654 </para>
1655 <para>You need to specify all applicable licensing
1656 files for the software.
1657 At the end of the configuration step, the build process
1658 will compare the checksums of the files to be sure
1659 the text has not changed.
1660 Any differences result in an error with the message
1661 containing the current checksum.
1662 For more explanation and examples of how to set the
1663 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1664 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1665 section in the Yocto Project Reference Manual.</para>
1666 <para>To determine the correct checksum string, you
1667 can list the appropriate files in the
1668 <filename>LIC_FILES_CHKSUM</filename> variable with
1669 incorrect md5 strings, attempt to build the software,
1670 and then note the resulting error messages that will
1671 report the correct md5 strings.
1672 Here is an example that assumes the software has a
1673 <filename>COPYING</filename> file:
1674 <literallayout class='monospaced'>
1675 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
1676 </literallayout>
1677 When you try to build the software, the build system
1678 will produce an error and give you the correct string
1679 that you can substitute into the recipe file for a
1680 subsequent build.
1681 </para></listitem>
1682 </itemizedlist>
1683 </para>
1684
1685<!--
1686
1687 <para>
1688 For trying this out I created a new recipe named
1689 <filename>htop_1.0.2.bb</filename> and put it in
1690 <filename>poky/meta/recipes-extended/htop</filename>.
1691 There are two license type statements in my very simple
1692 recipe:
1693 <literallayout class='monospaced'>
1694 LICENSE = ""
1695
1696 LIC_FILES_CHKSUM = ""
1697
1698 SRC_URI[md5sum] = ""
1699 SRC_URI[sha256sum] = ""
1700 </literallayout>
1701 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
1702 Next, you delete or comment out the two <filename>SRC_URI</filename>
1703 lines at the end and then attempt to build the software with
1704 <filename>bitbake htop</filename>.
1705 Doing so causes BitBake to report some errors and and give
1706 you the actual strings you need for the last two
1707 <filename>SRC_URI</filename> lines.
1708 Prior to this, you have to dig around in the home page of the
1709 source for <filename>htop</filename> and determine that the
1710 software is released under GPLv2.
1711 You can provide that in the <filename>LICENSE</filename>
1712 statement.
1713 Now you edit your recipe to have those two strings for
1714 the <filename>SRC_URI</filename> statements:
1715 <literallayout class='monospaced'>
1716 LICENSE = "GPLv2"
1717
1718 LIC_FILES_CHKSUM = ""
1719
1720 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
1721 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
1722 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
1723 </literallayout>
1724 At this point, you can build the software again using the
1725 <filename>bitbake htop</filename> command.
1726 There is just a set of errors now associated with the
1727 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
1728 </para>
1729-->
1730
1731 </section>
1732
1733 <section id='new-recipe-configuring-the-recipe'>
1734 <title>Configuring the Recipe</title>
1735
1736 <para>
1737 Most software provides some means of setting build-time
1738 configuration options before compilation.
1739 Typically, setting these options is accomplished by running a
1740 configure script with some options, or by modifying a build
1741 configuration file.
1742 </para>
1743
1744 <para>
1745 A major part of build-time configuration is about checking for
1746 build-time dependencies and possibly enabling optional
1747 functionality as a result.
1748 You need to specify any build-time dependencies for the
1749 software you are building in your recipe's
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1751 value, in terms of other recipes that satisfy those
1752 dependencies.
1753 You can often find build-time or runtime
1754 dependencies described in the software's documentation.
1755 </para>
1756
1757 <para>
1758 The following list provides configuration items of note based
1759 on how your software is built:
1760 <itemizedlist>
1761 <listitem><para><emphasis>Autotools:</emphasis>
1762 If your source files have a
1763 <filename>configure.ac</filename> file, then your
1764 software is built using Autotools.
1765 If this is the case, you just need to worry about
1766 tweaking the configuration.</para>
1767 <para>When using Autotools, your recipe needs to inherit
1768 the
1769 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1770 class and your recipe does not have to contain a
1771 <filename>do_configure</filename> task.
1772 However, you might still want to make some adjustments.
1773 For example, you can set
1774 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1775 to pass any needed configure options that are specific
1776 to the recipe.</para></listitem>
1777 <listitem><para><emphasis>CMake:</emphasis>
1778 If your source files have a
1779 <filename>CMakeLists.txt</filename> file, then your
1780 software is built using CMake.
1781 If this is the case, you just need to worry about
1782 tweaking the configuration.</para>
1783 <para>When you use CMake, your recipe needs to inherit
1784 the
1785 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
1786 class and your recipe does not have to contain a
1787 <filename>do_configure</filename> task.
1788 You can make some adjustments by setting
1789 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1790 to pass any needed configure options that are specific
1791 to the recipe.</para></listitem>
1792 <listitem><para><emphasis>Other:</emphasis>
1793 If your source files do not have a
1794 <filename>configure.ac</filename> or
1795 <filename>CMakeLists.txt</filename> file, then your
1796 software is built using some method other than Autotools
1797 or CMake.
1798 If this is the case, you normally need to provide a
1799 <filename>do_configure</filename> task in your recipe
1800 unless, of course, there is nothing to configure.
1801 </para>
1802 <para>Even if your software is not being built by
1803 Autotools or CMake, you still might not need to deal
1804 with any configuration issues.
1805 You need to determine if configuration is even a required step.
1806 You might need to modify a Makefile or some configuration file
1807 used for the build to specify necessary build options.
1808 Or, perhaps you might need to run a provided, custom
1809 configure script with the appropriate options.</para>
1810 <para>For the case involving a custom configure
1811 script, you would run
1812 <filename>./configure --help</filename> and look for
1813 the options you need to set.</para></listitem>
1814 </itemizedlist>
1815 </para>
1816
1817 <para>
1818 Once configuration succeeds, it is always good practice to
1819 look at the <filename>log.do_configure</filename> file to
1820 ensure that the appropriate options have been enabled and no
1821 additional build-time dependencies need to be added to
1822 <filename>DEPENDS</filename>.
1823 For example, if the configure script reports that it found
1824 something not mentioned in <filename>DEPENDS</filename>, or
1825 that it did not find something that it needed for some
1826 desired optional functionality, then you would need to add
1827 those to <filename>DEPENDS</filename>.
1828 Looking at the log might also reveal items being checked for
1829 and/or enabled that you do not want, or items not being found
1830 that are in <filename>DEPENDS</filename>, in which case
1831 you would need to look at passing extra options to the
1832 configure script as needed.
1833 For reference information on configure options specific to the
1834 software you are building, you can consult the output of the
1835 <filename>./configure --help</filename> command within
1836 <filename>${S}</filename> or consult the software's upstream
1837 documentation.
1838 </para>
1839 </section>
1840
1841 <section id='new-recipe-compilation'>
1842 <title>Compilation</title>
1843
1844 <para>
1845 During a build, the <filename>do_compile</filename> task
1846 happens after source is fetched, unpacked, and configured.
1847 If the recipe passes through <filename>do_compile</filename>
1848 successfully, nothing needs to be done.
1849 </para>
1850
1851 <para>
1852 However, if the compile step fails, you need to diagnose the
1853 failure.
1854 Here are some common issues that cause failures:
1855 <itemizedlist>
1856 <listitem><para><emphasis>Parallel build failures:</emphasis>
1857 These failures manifest themselves as intermittent
1858 errors, or errors reporting that a file or directory
1859 that should be created by some other part of the build
1860 process could not be found.
1861 This type of failure can occur even if, upon inspection,
1862 the file or directory does exist after the build has
1863 failed, because that part of the build process happened
1864 in the wrong order.</para>
1865 <para>To fix the problem, you need to either satisfy
1866 the missing dependency in the Makefile or whatever
1867 script produced the Makefile, or (as a workaround)
1868 set
1869 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
1870 to an empty string:
1871 <literallayout class='monospaced'>
1872 PARALLEL_MAKE = ""
1873 </literallayout></para></listitem>
1874 <listitem><para><emphasis>Improper host path usage:</emphasis>
1875 This failure applies to recipes building for the target
1876 or <filename>nativesdk</filename> only.
1877 The failure occurs when the compilation process uses
1878 improper headers, libraries, or other files from the
1879 host system when cross-compiling for the target.
1880 </para>
1881 <para>To fix the problem, examine the
1882 <filename>log.do_compile</filename> file to identify
1883 the host paths being used (e.g.
1884 <filename>/usr/include</filename>,
1885 <filename>/usr/lib</filename>, and so forth) and then
1886 either add configure options, apply a patch, or do both.
1887 </para></listitem>
1888 <listitem><para><emphasis>Failure to find required
1889 libraries/headers:</emphasis>
1890 If a build-time dependency is missing because it has
1891 not been declared in
1892 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
1893 or because the dependency exists but the path used by
1894 the build process to find the file is incorrect and the
1895 configure step did not detect it, the compilation
1896 process could fail.
1897 For either of these failures, the compilation process
1898 notes that files could not be found.
1899 In these cases, you need to go back and add additional
1900 options to the configure script as well as possibly
1901 add additional build-time dependencies to
1902 <filename>DEPENDS</filename>.
1903 Occasionally, it is necessary to apply a patch to the
1904 source to ensure the correct paths are used.
1905 </para></listitem>
1906 </itemizedlist>
1907 </para>
1908 </section>
1909
1910 <section id='new-recipe-installing'>
1911 <title>Installing</title>
1912
1913 <para>
1914 During <filename>do_install</filename>, the task copies the
1915 built files along with their hierarchy to locations that
1916 would mirror their locations on the target device.
1917 The installation process copies files from the
1918 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
1919 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
1920 and
1921 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1922 directories to the
1923 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1924 directory to create the structure as it should appear on the
1925 target system.
1926 </para>
1927
1928 <para>
1929 How your software is built affects what you must do to be
1930 sure your software is installed correctly.
1931 The following list describes what you must do for installation
1932 depending on the type of build system used by the software
1933 being built:
1934 <itemizedlist>
1935 <listitem><para><emphasis>Autotools and CMake:</emphasis>
1936 If the software your recipe is building uses Autotools
1937 or CMake, the OpenEmbedded build
1938 system understands how to install the software.
1939 Consequently, you do not have to have a
1940 <filename>do_install</filename> task as part of your
1941 recipe.
1942 You just need to make sure the install portion of the
1943 build completes with no issues.
1944 However, if you wish to install additional files not
1945 already being installed by
1946 <filename>make install</filename>, you should do this
1947 using a <filename>do_install_append</filename> function
1948 using the install command as described in
1949 <emphasis>Manual</emphasis> later in this list.
1950 </para></listitem>
1951 <listitem><para><emphasis>Other (using
1952 <filename>make install</filename>):</emphasis>
1953 You need to define a
1954 <filename>do_install</filename> function in your
1955 recipe.
1956 The function should call
1957 <filename>oe_runmake install</filename> and will likely
1958 need to pass in the destination directory as well.
1959 How you pass that path is dependent on how the
1960 <filename>Makefile</filename> being run is written
1961 (e.g. <filename>DESTDIR=${D}</filename>,
1962 <filename>PREFIX=${D}</filename>,
1963 <filename>INSTALLROOT=${D}</filename>, and so forth).
1964 </para>
1965 <para>For an example recipe using
1966 <filename>make install</filename>, see the
1967 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
1968 section.</para></listitem>
1969 <listitem><para><emphasis>Manual:</emphasis>
1970 You need to define a
1971 <filename>do_install</filename> function in your
1972 recipe.
1973 The function must first use
1974 <filename>install -d</filename> to create the
1975 directories.
1976 Once the directories exist, your function can use
1977 <filename>install</filename> to manually install the
1978 built software into the directories.</para>
1979 <para>You can find more information on
1980 <filename>install</filename> at
1981 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
1982 </para></listitem>
1983 </itemizedlist>
1984 </para>
1985
1986 <para>
1987 For the scenarios that do not use Autotools or
1988 CMake, you need to track the installation
1989 and diagnose and fix any issues until everything installs
1990 correctly.
1991 You need to look in the default location of
1992 <filename>${D}</filename>, which is
1993 <filename>${WORKDIR}/image</filename>, to be sure your
1994 files have been installed correctly.
1995 </para>
1996
1997 <note>
1998 During the installation process, you might need to modify
1999 some of the installed files to suit the target layout.
2000 For example, you might need to replace hard-coded paths in an
2001 initscript with values of variables provided by the build
2002 system, such as replacing <filename>/usr/bin/</filename> with
2003 <filename>${bindir}</filename>.
2004 If you do perform such modifications during
2005 <filename>do_install</filename>, be sure to modify the
2006 destination file after copying rather than before copying.
2007 Modifying after copying ensures that the build system can
2008 re-execute <filename>do_install</filename> if needed.
2009 </note>
2010
2011 <note>
2012 <filename>oe_runmake install</filename>, which can be run
2013 directly or can be run indirectly by the
2014 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2015 and
2016 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2017 classes, runs <filename>make install</filename> in parallel.
2018 Sometimes, a Makefile can have missing dependencies between
2019 targets that can result in race conditions.
2020 If you experience intermittent failures during
2021 <filename>do_install</filename>, you might be able to work
2022 around them by disabling parallel Makefile installs
2023 by adding the following to the recipe:
2024 <literallayout class='monospaced'>
2025 PARALLEL_MAKEINST = ""
2026 </literallayout>
2027 See
2028 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2029 for additional information.
2030 </note>
2031 </section>
2032
2033 <section id='new-recipe-enabling-system-services'>
2034 <title>Enabling System Services</title>
2035
2036 <para>
2037 If you want to install a service, which is a process that
2038 usually starts on boot and runs in the background, then
2039 you must include some additional definitions in your recipe.
2040 </para>
2041
2042 <para>
2043 If you are adding services and the service initialization
2044 script or the service file itself is not installed, you must
2045 provide for that installation in your recipe using a
2046 <filename>do_install_append</filename> function.
2047 If your recipe already has a <filename>do_install</filename>
2048 function, update the function near its end rather than
2049 adding an additional <filename>do_install_append</filename>
2050 function.
2051 </para>
2052
2053 <para>
2054 When you create the installation for your services, you need
2055 to accomplish what is normally done by
2056 <filename>make install</filename>.
2057 In other words, make sure your installation arranges the output
2058 similar to how it is arranged on the target system.
2059 </para>
2060
2061 <para>
2062 The OpenEmbedded build system provides support for starting
2063 services two different ways:
2064 <itemizedlist>
2065 <listitem><para><emphasis>SysVinit:</emphasis>
2066 SysVinit is a system and service manager that
2067 manages the init system used to control the very basic
2068 functions of your system.
2069 The init program is the first program
2070 started by the Linux kernel when the system boots.
2071 Init then controls the startup, running and shutdown
2072 of all other programs.</para>
2073 <para>To enable a service using SysVinit, your recipe
2074 needs to inherit the
2075 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2076 class.
2077 The class helps facilitate safely installing the
2078 package on the target.</para>
2079 <para>You will need to set the
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2081 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2082 and
2083 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2084 variables within your recipe.</para></listitem>
2085 <listitem><para><emphasis>systemd:</emphasis>
2086 System Management Daemon (systemd) was designed to
2087 replace SysVinit and to provide
2088 enhanced management of services.
2089 For more information on systemd, see the systemd
2090 homepage at
2091 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2092 </para>
2093 <para>To enable a service using systemd, your recipe
2094 needs to inherit the
2095 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2096 class.
2097 See the <filename>systemd.class</filename> file
2098 located in your
2099 <link linkend='source-directory'>Source Directory</link>.
2100 section for more information.
2101 </para></listitem>
2102 </itemizedlist>
2103 </para>
2104 </section>
2105
2106 <section id='new-recipe-packaging'>
2107 <title>Packaging</title>
2108
2109 <para>
2110 The <filename>do_package</filename> task splits the files
2111 produced by the recipe into logical components.
2112 Even software that produces a single binary might still have
2113 debug symbols, documentation, and other logical components
2114 that should be split out.
2115 The <filename>do_package</filename> task ensures that files
2116 are split up and packaged correctly.
2117 </para>
2118
2119 <para>
2120 After you build your software, you need to be sure your packages
2121 are correct.
2122 Examine the
2123 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2124 directory and make sure files are where you expect them to be.
2125 </para>
2126
2127 <para>
2128 If you discover problems, you can set
2129 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2130 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2131 <filename>do_install(_append)</filename>, and so forth as
2132 needed.
2133 </para>
2134
2135 <para>
2136 See the
2137 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2138 section for an example that shows how you might split
2139 your software into more than one package.
2140 </para>
2141
2142 <para>
2143 For an example showing how to install a post-installation
2144 script, see the
2145 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2146 section.
2147 </para>
2148 </section>
2149
2150 <section id='new-recipe-post-installation-scripts'>
2151 <title>Post-Installation Scripts</title>
2152
2153 <para>
2154 Post-installation scripts run immediately after installing
2155 a package on the target, or during image creation when a
2156 package is included in an image.
2157 To add a post-installation script to a package, add a
2158 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2159 the recipe file (<filename>.bb</filename>) and use
2160 <filename>PACKAGENAME</filename> as the name of the package
2161 you want to attach to the <filename>postinst</filename>
2162 script.
2163 To apply the post-installation script to the main package
2164 for the recipe, which is usually what is required, specify
2165 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2166 in place of <filename>PACKAGENAME</filename>.
2167 </para>
2168
2169 <para>
2170 A post-installation function has the following structure:
2171 <literallayout class='monospaced'>
2172 pkg_postinst_PACKAGENAME () {
2173 #!/bin/sh -e
2174 # Commands to carry out
2175 }
2176 </literallayout>
2177 </para>
2178
2179 <para>
2180 The script defined in the post-installation function is
2181 called when the root filesystem is created.
2182 If the script succeeds, the package is marked as installed.
2183 If the script fails, the package is marked as unpacked and
2184 the script is executed when the image boots again.
2185 </para>
2186
2187 <para>
2188 Sometimes it is necessary for the execution of a
2189 post-installation script to be delayed until the first boot.
2190 For example, the script might need to be executed on the
2191 device itself.
2192 To delay script execution until boot time, use the following
2193 structure in the post-installation script:
2194 <literallayout class='monospaced'>
2195 pkg_postinst_PACKAGENAME () {
2196 #!/bin/sh -e
2197 if [ x"$D" = "x" ]; then
2198 # Actions to carry out on the device go here
2199 else
2200 exit 1
2201 fi
2202 }
2203 </literallayout>
2204 </para>
2205
2206 <para>
2207 The previous example delays execution until the image boots
2208 again because the
2209 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
2210 variable points to the directory containing the image when
2211 the root filesystem is created at build time but is unset
2212 when executed on the first boot.
2213 </para>
2214
2215 <note>
2216 Equivalent support for pre-install, pre-uninstall, and
2217 post-uninstall scripts exist by way of
2218 <filename>pkg_preinst</filename>,
2219 <filename>pkg_prerm</filename>, and
2220 <filename>pkg_postrm</filename>, respectively.
2221 These scrips work in exactly the same way as does
2222 <filename>pkg_postinst</filename> with the exception that they
2223 run at different times.
2224 Also, because of when they run, they are not applicable to
2225 being run at image creation time like
2226 <filename>pkg_postinst</filename>.
2227 </note>
2228 </section>
2229
2230 <section id='new-recipe-testing'>
2231 <title>Testing</title>
2232
2233 <para>
2234 The final step for completing your recipe is to be sure that
2235 the software you built runs correctly.
2236 To accomplish runtime testing, add the build's output
2237 packages to your image and test them on the target.
2238 </para>
2239
2240 <para>
2241 For information on how to customize your image by adding
2242 specific packages, see the
2243 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2244 section.
2245 </para>
2246 </section>
2247
2248 <section id='new-recipe-testing-examples'>
2249 <title>Examples</title>
2250
2251 <para>
2252 To help summarize how to write a recipe, this section provides
2253 some examples given various scenarios:
2254 <itemizedlist>
2255 <listitem><para>Recipes that use local files</para></listitem>
2256 <listitem><para>Using an Autotooled package</para></listitem>
2257 <listitem><para>Using a Makefile-based package</para></listitem>
2258 <listitem><para>Splitting an application into multiple packages</para></listitem>
2259 </itemizedlist>
2260 </para>
2261
2262 <section id='new-recipe-single-c-file-package-hello-world'>
2263 <title>Single .c File Package (Hello World!)</title>
2264
2265 <para>
2266 Building an application from a single file that is stored
2267 locally (e.g. under <filename>files/</filename>) requires
2268 a recipe that has the file listed in the
2269 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2270 variable.
2271 Additionally, you need to manually write the
2272 <filename>do_compile</filename> and
2273 <filename>do_install</filename> tasks.
2274 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2275 variable defines the directory containing the source code,
2276 which is set to
2277 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2278 in this case - the directory BitBake uses for the build.
2279 <literallayout class='monospaced'>
2280 SUMMARY = "Simple helloworld application"
2281 SECTION = "examples"
2282 LICENSE = "MIT"
2283 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2284
2285 SRC_URI = "file://helloworld.c"
2286
2287 S = "${WORKDIR}"
2288
2289 do_compile() {
2290 ${CC} helloworld.c -o helloworld
2291 }
2292
2293 do_install() {
2294 install -d ${D}${bindir}
2295 install -m 0755 helloworld ${D}${bindir}
2296 }
2297 </literallayout>
2298 </para>
2299
2300 <para>
2301 By default, the <filename>helloworld</filename>,
2302 <filename>helloworld-dbg</filename>, and
2303 <filename>helloworld-dev</filename> packages are built.
2304 For information on how to customize the packaging process,
2305 see the
2306 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2307 section.
2308 </para>
2309 </section>
2310
2311 <section id='new-recipe-autotooled-package'>
2312 <title>Autotooled Package</title>
2313 <para>
2314 Applications that use Autotools such as <filename>autoconf</filename> and
2315 <filename>automake</filename> require a recipe that has a source archive listed in
2316 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2317 also inherit the
2318 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2319 class, which contains the definitions of all the steps
2320 needed to build an Autotool-based application.
2321 The result of the build is automatically packaged.
2322 And, if the application uses NLS for localization, packages with local information are
2323 generated (one package per language).
2324 Following is one example: (<filename>hello_2.3.bb</filename>)
2325 <literallayout class='monospaced'>
2326 SUMMARY = "GNU Helloworld application"
2327 SECTION = "examples"
2328 LICENSE = "GPLv2+"
2329 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2330
2331 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2332
2333 inherit autotools gettext
2334 </literallayout>
2335 </para>
2336
2337 <para>
2338 The variable
2339 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2340 is used to track source license changes as described in the
2341 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2342 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2343 </para>
2344 </section>
2345
2346 <section id='new-recipe-makefile-based-package'>
2347 <title>Makefile-Based Package</title>
2348
2349 <para>
2350 Applications that use GNU <filename>make</filename> also require a recipe that has
2351 the source archive listed in
2352 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2353 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2354 starts the <filename>make</filename> command to compile the application.
2355 If you need additional <filename>make</filename> options, you should store them in the
2356 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2357 variable.
2358 BitBake passes these options into the <filename>make</filename> GNU invocation.
2359 Note that a <filename>do_install</filename> task is still required.
2360 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2361 </para>
2362
2363 <para>
2364 Some applications might require extra parameters to be passed to the compiler.
2365 For example, the application might need an additional header path.
2366 You can accomplish this by adding to the
2367 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2368 The following example shows this:
2369 <literallayout class='monospaced'>
2370 CFLAGS_prepend = "-I ${S}/include "
2371 </literallayout>
2372 </para>
2373
2374 <para>
2375 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2376 <literallayout class='monospaced'>
2377 SUMMARY = "Tools for managing memory technology devices."
2378 SECTION = "base"
2379 DEPENDS = "zlib lzo e2fsprogs util-linux"
2380 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2381 LICENSE = "GPLv2+"
2382 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2383 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2384
2385 SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2386 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2387
2388 S = "${WORKDIR}/git/"
2389
2390 PR = "r1"
2391
2392 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2393 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2394
2395 do_install () {
2396 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2397 INCLUDEDIR=${includedir}
2398 install -d ${D}${includedir}/mtd/
2399 for f in ${S}/include/mtd/*.h; do
2400 install -m 0644 $f ${D}${includedir}/mtd/
2401 done
2402 }
2403
2404 PARALLEL_MAKE = ""
2405
2406 BBCLASSEXTEND = "native"
2407 </literallayout>
2408 </para>
2409 </section>
2410
2411 <section id='splitting-an-application-into-multiple-packages'>
2412 <title>Splitting an Application into Multiple Packages</title>
2413
2414 <para>
2415 You can use the variables
2416 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2417 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2418 to split an application into multiple packages.
2419 </para>
2420
2421 <para>
2422 Following is an example that uses the <filename>libxpm</filename> recipe.
2423 By default, this recipe generates a single package that contains the library along
2424 with a few binaries.
2425 You can modify the recipe to split the binaries into separate packages:
2426 <literallayout class='monospaced'>
2427 require xorg-lib-common.inc
2428
2429 SUMMARY = "X11 Pixmap library"
2430 LICENSE = "X-BSD"
2431 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2432 DEPENDS += "libxext libsm libxt"
2433 PR = "r3"
2434 PE = "1"
2435
2436 XORG_PN = "libXpm"
2437
2438 PACKAGES =+ "sxpm cxpm"
2439 FILES_cxpm = "${bindir}/cxpm"
2440 FILES_sxpm = "${bindir}/sxpm"
2441 </literallayout>
2442 </para>
2443
2444 <para>
2445 In the previous example, we want to ship the <filename>sxpm</filename>
2446 and <filename>cxpm</filename> binaries in separate packages.
2447 Since <filename>bindir</filename> would be packaged into the main
2448 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2449 package by default, we prepend the <filename>PACKAGES</filename>
2450 variable so additional package names are added to the start of list.
2451 This results in the extra <filename>FILES_*</filename>
2452 variables then containing information that define which files and
2453 directories go into which packages.
2454 Files included by earlier packages are skipped by latter packages.
2455 Thus, the main <filename>PN</filename> package
2456 does not include the above listed files.
2457 </para>
2458 </section>
2459 </section>
2460 </section>
2461
2462 <section id="platdev-newmachine">
2463 <title>Adding a New Machine</title>
2464
2465 <para>
2466 Adding a new machine to the Yocto Project is a straight forward
2467 process.
2468 This section describes how to add machines that are similar
2469 to those that the Yocto Project already supports.
2470 <note>
2471 Although well within the capabilities of the Yocto Project,
2472 adding a totally new architecture might require
2473 changes to <filename>gcc/eglibc</filename> and to the site
2474 information, which is beyond the scope of this manual.
2475 </note>
2476 </para>
2477
2478 <para>
2479 For a complete example that shows how to add a new machine,
2480 see the
2481 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
2482 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
2483 </para>
2484
2485 <section id="platdev-newmachine-conffile">
2486 <title>Adding the Machine Configuration File</title>
2487
2488 <para>
2489 To add a new machine, you need to add a new machine
2490 configuration file to the layer's
2491 <filename>conf/machine</filename> directory.
2492 This configuration file provides details about the device
2493 you are adding.
2494 </para>
2495
2496 <para>
2497 The OpenEmbedded build system uses the root name of the
2498 machine configuration file to reference the new machine.
2499 For example, given a machine configuration file named
2500 <filename>crownbay.conf</filename>, the build system
2501 recognizes the machine as "crownbay".
2502 </para>
2503
2504 <para>
2505 The most important variables you must set in your machine
2506 configuration file are as follows:
2507 <itemizedlist>
2508 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
2509 (e.g. "arm")</para></listitem>
2510 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
2511 (see below)</para></listitem>
2512 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
2513 (e.g. "apm screen wifi")</para></listitem>
2514 </itemizedlist>
2515 </para>
2516
2517 <para>
2518 You might also need these variables:
2519 <itemizedlist>
2520 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
2521 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
2522 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
2523 (e.g. "zImage")</para></listitem>
2524 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
2525 (e.g. "tar.gz jffs2")</para></listitem>
2526 </itemizedlist>
2527 </para>
2528
2529 <para>
2530 You can find full details on these variables in the reference
2531 section.
2532 You can leverage existing machine <filename>.conf</filename>
2533 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
2534 </para>
2535 </section>
2536
2537 <section id="platdev-newmachine-kernel">
2538 <title>Adding a Kernel for the Machine</title>
2539
2540 <para>
2541 The OpenEmbedded build system needs to be able to build a kernel
2542 for the machine.
2543 You need to either create a new kernel recipe for this machine,
2544 or extend an existing kernel recipe.
2545 You can find several kernel recipe examples in the
2546 Source Directory at
2547 <filename>meta/recipes-kernel/linux</filename>
2548 that you can use as references.
2549 </para>
2550
2551 <para>
2552 If you are creating a new kernel recipe, normal recipe-writing
2553 rules apply for setting up a
2554 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2555 Thus, you need to specify any necessary patches and set
2556 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2557 to point at the source code.
2558 You need to create a <filename>do_configure</filename> task that
2559 configures the unpacked kernel with a
2560 <filename>defconfig</filename> file.
2561 You can do this by using a <filename>make defconfig</filename>
2562 command or, more commonly, by copying in a suitable
2563 <filename>defconfig</filename> file and then running
2564 <filename>make oldconfig</filename>.
2565 By making use of <filename>inherit kernel</filename> and
2566 potentially some of the <filename>linux-*.inc</filename> files,
2567 most other functionality is centralized and the defaults of the
2568 class normally work well.
2569 </para>
2570
2571 <para>
2572 If you are extending an existing kernel recipe, it is usually
2573 a matter of adding a suitable <filename>defconfig</filename>
2574 file.
2575 The file needs to be added into a location similar to
2576 <filename>defconfig</filename> files used for other machines
2577 in a given kernel recipe.
2578 A possible way to do this is by listing the file in the
2579 <filename>SRC_URI</filename> and adding the machine to the
2580 expression in
2581 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
2582 <literallayout class='monospaced'>
2583 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2584 </literallayout>
2585 </para>
2586 </section>
2587
2588 <section id="platdev-newmachine-formfactor">
2589 <title>Adding a Formfactor Configuration File</title>
2590
2591 <para>
2592 A formfactor configuration file provides information about the
2593 target hardware for which the image is being built and information that
2594 the build system cannot obtain from other sources such as the kernel.
2595 Some examples of information contained in a formfactor configuration file include
2596 framebuffer orientation, whether or not the system has a keyboard,
2597 the positioning of the keyboard in relation to the screen, and
2598 the screen resolution.
2599 </para>
2600
2601 <para>
2602 The build system uses reasonable defaults in most cases.
2603 However, if customization is
2604 necessary, you need to create a <filename>machconfig</filename> file
2605 in the <filename>meta/recipes-bsp/formfactor/files</filename>
2606 directory.
2607 This directory contains directories for specific machines such as
2608 <filename>qemuarm</filename> and <filename>qemux86</filename>.
2609 For information about the settings available and the defaults, see the
2610 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
2611 same area.
2612 </para>
2613
2614 <para>
2615 Following is an example for "qemuarm" machine:
2616 <literallayout class='monospaced'>
2617 HAVE_TOUCHSCREEN=1
2618 HAVE_KEYBOARD=1
2619
2620 DISPLAY_CAN_ROTATE=0
2621 DISPLAY_ORIENTATION=0
2622 #DISPLAY_WIDTH_PIXELS=640
2623 #DISPLAY_HEIGHT_PIXELS=480
2624 #DISPLAY_BPP=16
2625 DISPLAY_DPI=150
2626 DISPLAY_SUBPIXEL_ORDER=vrgb
2627 </literallayout>
2628 </para>
2629 </section>
2630 </section>
2631
2632 <section id="platdev-working-with-libraries">
2633 <title>Working With Libraries</title>
2634
2635 <para>
2636 Libraries are an integral part of your system.
2637 This section describes some common practices you might find
2638 helpful when working with libraries to build your system:
2639 <itemizedlist>
2640 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
2641 </para></listitem>
2642 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
2643 </para></listitem>
2644 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
2645 </para></listitem>
2646 </itemizedlist>
2647 </para>
2648
2649 <section id='including-static-library-files'>
2650 <title>Including Static Library Files</title>
2651
2652 <para>
2653 If you are building a library and the library offers static linking, you can control
2654 which static library files (<filename>*.a</filename> files) get included in the
2655 built library.
2656 </para>
2657
2658 <para>
2659 The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
2660 and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
2661 variables in the
2662 <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
2663 by the <filename>do_install</filename> task are packaged.
2664 By default, the <filename>PACKAGES</filename> variable contains
2665 <filename>${PN}-staticdev</filename>, which includes all static library files.
2666 <note>
2667 Some previously released versions of the Yocto Project
2668 defined the static library files through
2669 <filename>${PN}-dev</filename>.
2670 </note>
2671 Following, is part of the BitBake configuration file.
2672 You can see where the static library files are defined:
2673 <literallayout class='monospaced'>
2674 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
2675 PACKAGES_DYNAMIC = "${PN}-locale-*"
2676 FILES = ""
2677
2678 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
2679 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
2680 ${base_bindir}/* ${base_sbindir}/* \
2681 ${base_libdir}/*${SOLIBS} \
2682 ${datadir}/${BPN} ${libdir}/${BPN}/* \
2683 ${datadir}/pixmaps ${datadir}/applications \
2684 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
2685 ${libdir}/bonobo/servers"
2686
2687 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
2688 ${datadir}/gnome/help"
2689 SECTION_${PN}-doc = "doc"
2690
2691 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
2692 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
2693 ${datadir}/aclocal ${base_libdir}/*.o"
2694 SECTION_${PN}-dev = "devel"
2695 ALLOW_EMPTY_${PN}-dev = "1"
2696 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
2697
2698 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
2699 SECTION_${PN}-staticdev = "devel"
2700 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
2701 </literallayout>
2702 </para>
2703 </section>
2704
2705 <section id="combining-multiple-versions-library-files-into-one-image">
2706 <title>Combining Multiple Versions of Library Files into One Image</title>
2707
2708 <para>
2709 The build system offers the ability to build libraries with different
2710 target optimizations or architecture formats and combine these together
2711 into one system image.
2712 You can link different binaries in the image
2713 against the different libraries as needed for specific use cases.
2714 This feature is called "Multilib."
2715 </para>
2716
2717 <para>
2718 An example would be where you have most of a system compiled in 32-bit
2719 mode using 32-bit libraries, but you have something large, like a database
2720 engine, that needs to be a 64-bit application and uses 64-bit libraries.
2721 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
2722 </para>
2723
2724 <para>
2725 While the Multilib feature is most commonly used for 32 and 64-bit differences,
2726 the approach the build system uses facilitates different target optimizations.
2727 You could compile some binaries to use one set of libraries and other binaries
2728 to use other different sets of libraries.
2729 The libraries could differ in architecture, compiler options, or other
2730 optimizations.
2731 </para>
2732
2733 <para>
2734 This section overviews the Multilib process only.
2735 For more details on how to implement Multilib, see the
2736 <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
2737 page.
2738 </para>
2739
2740 <para>
2741 Aside from this wiki page, several examples exist in the
2742 <filename>meta-skeleton</filename> layer found in the
2743 <link linkend='source-directory'>Source Directory</link>:
2744 <itemizedlist>
2745 <listitem><para><filename>conf/multilib-example.conf</filename>
2746 configuration file</para></listitem>
2747 <listitem><para><filename>conf/multilib-example2.conf</filename>
2748 configuration file</para></listitem>
2749 <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
2750 recipe</para></listitem>
2751 </itemizedlist>
2752 </para>
2753
2754 <section id='preparing-to-use-multilib'>
2755 <title>Preparing to Use Multilib</title>
2756
2757 <para>
2758 User-specific requirements drive the Multilib feature.
2759 Consequently, there is no one "out-of-the-box" configuration that likely
2760 exists to meet your needs.
2761 </para>
2762
2763 <para>
2764 In order to enable Multilib, you first need to ensure your recipe is
2765 extended to support multiple libraries.
2766 Many standard recipes are already extended and support multiple libraries.
2767 You can check in the <filename>meta/conf/multilib.conf</filename>
2768 configuration file in the
2769 <link linkend='source-directory'>Source Directory</link> to see how this is
2770 done using the
2771 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
2772 variable.
2773 Eventually, all recipes will be covered and this list will
2774 not be needed.
2775 </para>
2776
2777 <para>
2778 For the most part, the Multilib class extension works automatically to
2779 extend the package name from <filename>${PN}</filename> to
2780 <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
2781 is the particular multilib (e.g. "lib32-" or "lib64-").
2782 Standard variables such as
2783 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2784 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
2785 <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
2786 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
2787 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2788 and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
2789 If you are extending any manual code in the recipe, you can use the
2790 <filename>${MLPREFIX}</filename> variable to ensure those names are extended
2791 correctly.
2792 This automatic extension code resides in <filename>multilib.bbclass</filename>.
2793 </para>
2794 </section>
2795
2796 <section id='using-multilib'>
2797 <title>Using Multilib</title>
2798
2799 <para>
2800 After you have set up the recipes, you need to define the actual
2801 combination of multiple libraries you want to build.
2802 You accomplish this through your <filename>local.conf</filename>
2803 configuration file in the
2804 <link linkend='build-directory'>Build Directory</link>.
2805 An example configuration would be as follows:
2806 <literallayout class='monospaced'>
2807 MACHINE = "qemux86-64"
2808 require conf/multilib.conf
2809 MULTILIBS = "multilib:lib32"
2810 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
2811 IMAGE_INSTALL = "lib32-connman"
2812 </literallayout>
2813 This example enables an
2814 additional library named <filename>lib32</filename> alongside the
2815 normal target packages.
2816 When combining these "lib32" alternatives, the example uses "x86" for tuning.
2817 For information on this particular tuning, see
2818 <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
2819 </para>
2820
2821 <para>
2822 The example then includes <filename>lib32-connman</filename>
2823 in all the images, which illustrates one method of including a
2824 multiple library dependency.
2825 You can use a normal image build to include this dependency,
2826 for example:
2827 <literallayout class='monospaced'>
2828 $ bitbake core-image-sato
2829 </literallayout>
2830 You can also build Multilib packages specifically with a command like this:
2831 <literallayout class='monospaced'>
2832 $ bitbake lib32-connman
2833 </literallayout>
2834 </para>
2835 </section>
2836
2837 <section id='additional-implementation-details'>
2838 <title>Additional Implementation Details</title>
2839
2840 <para>
2841 Different packaging systems have different levels of native Multilib
2842 support.
2843 For the RPM Package Management System, the following implementation details
2844 exist:
2845 <itemizedlist>
2846 <listitem><para>A unique architecture is defined for the Multilib packages,
2847 along with creating a unique deploy folder under
2848 <filename>tmp/deploy/rpm</filename> in the
2849 <link linkend='build-directory'>Build Directory</link>.
2850 For example, consider <filename>lib32</filename> in a
2851 <filename>qemux86-64</filename> image.
2852 The possible architectures in the system are "all", "qemux86_64",
2853 "lib32_qemux86_64", and "lib32_x86".</para></listitem>
2854 <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
2855 <filename>${PN}</filename> during RPM packaging.
2856 The naming for a normal RPM package and a Multilib RPM package in a
2857 <filename>qemux86-64</filename> system resolves to something similar to
2858 <filename>bash-4.1-r2.x86_64.rpm</filename> and
2859 <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
2860 </para></listitem>
2861 <listitem><para>When installing a Multilib image, the RPM backend first
2862 installs the base image and then installs the Multilib libraries.
2863 </para></listitem>
2864 <listitem><para>The build system relies on RPM to resolve the identical files in the
2865 two (or more) Multilib packages.</para></listitem>
2866 </itemizedlist>
2867 </para>
2868
2869 <para>
2870 For the IPK Package Management System, the following implementation details exist:
2871 <itemizedlist>
2872 <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
2873 <filename>${PN}</filename> during IPK packaging.
2874 The naming for a normal RPM package and a Multilib IPK package in a
2875 <filename>qemux86-64</filename> system resolves to something like
2876 <filename>bash_4.1-r2.x86_64.ipk</filename> and
2877 <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
2878 </para></listitem>
2879 <listitem><para>The IPK deploy folder is not modified with
2880 <filename>${MLPREFIX}</filename> because packages with and without
2881 the Multilib feature can exist in the same folder due to the
2882 <filename>${PN}</filename> differences.</para></listitem>
2883 <listitem><para>IPK defines a sanity check for Multilib installation
2884 using certain rules for file comparison, overridden, etc.
2885 </para></listitem>
2886 </itemizedlist>
2887 </para>
2888 </section>
2889 </section>
2890
2891 <section id='installing-multiple-versions-of-the-same-library'>
2892 <title>Installing Multiple Versions of the Same Library</title>
2893
2894 <para>
2895 Situations can exist where you need to install and use
2896 multiple versions of the same library on the same system
2897 at the same time.
2898 These situations almost always exist when a library API
2899 changes and you have multiple pieces of software that
2900 depend on the separate versions of the library.
2901 To accommodate these situations, you can install multiple
2902 versions of the same library in parallel on the same system.
2903 </para>
2904
2905 <para>
2906 The process is straight forward as long as the libraries use
2907 proper versioning.
2908 With properly versioned libraries, all you need to do to
2909 individually specify the libraries is create separate,
2910 appropriately named recipes where the
2911 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
2912 name includes a portion that differentiates each library version
2913 (e.g.the major part of the version number).
2914 Thus, instead of having a single recipe that loads one version
2915 of a library (e.g. <filename>clutter</filename>), you provide
2916 multiple recipes that result in different versions
2917 of the libraries you want.
2918 As an example, the following two recipes would allow the
2919 two separate versions of the <filename>clutter</filename>
2920 library to co-exist on the same system:
2921 <literallayout class='monospaced'>
2922 clutter-1.6_1.6.20.bb
2923 clutter-1.8_1.8.4.bb
2924 </literallayout>
2925 Additionally, if you have other recipes that depend on a given
2926 library, you need to use the
2927 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2928 variable to create the dependency.
2929 Continuing with the same example, if you want to have a recipe
2930 depend on the 1.8 version of the <filename>clutter</filename>
2931 library, use the following in your recipe:
2932 <literallayout class='monospaced'>
2933 DEPENDS = "clutter-1.8"
2934 </literallayout>
2935 </para>
2936 </section>
2937 </section>
2938
2939 <section id='configuring-the-kernel'>
2940 <title>Configuring the Kernel</title>
2941
2942 <para>
2943 Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
2944 file has all the right information in it for the image you are building.
2945 You can use the <filename>menuconfig</filename> tool and configuration fragments to
2946 make sure your <filename>.config</filename> file is just how you need it.
2947 This section describes how to use <filename>menuconfig</filename>, create and use
2948 configuration fragments, and how to interactively tweak your <filename>.config</filename>
2949 file to create the leanest kernel configuration file possible.
2950 </para>
2951
2952 <para>
2953 For more information on kernel configuration, see the
2954 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
2955 section in the Yocto Project Linux Kernel Development Manual.
2956 </para>
2957
2958 <section id='using-menuconfig'>
2959 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
2960
2961 <para>
2962 The easiest way to define kernel configurations is to set them through the
2963 <filename>menuconfig</filename> tool.
2964 This tool provides an interactive method with which
2965 to set kernel configurations.
2966 For general information on <filename>menuconfig</filename>, see
2967 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
2968 </para>
2969
2970 <para>
2971 To use the <filename>menuconfig</filename> tool in the Yocto Project development
2972 environment, you must launch it using BitBake.
2973 Thus, the environment must be set up using the
2974 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
2975 or
2976 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
2977 script found in the
2978 <link linkend='build-directory'>Build Directory</link>.
2979 The following commands run <filename>menuconfig</filename> assuming the
2980 <link linkend='source-directory'>Source Directory</link>
2981 top-level folder is <filename>~/poky</filename>:
2982 <literallayout class='monospaced'>
2983 $ cd poky
2984 $ source oe-init-build-env
2985 $ bitbake linux-yocto -c menuconfig
2986 </literallayout>
2987 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
2988 interactively examine and configure all the kernel configuration parameters.
2989 After making your changes, simply exit the tool and save your changes to
2990 create an updated version of the <filename>.config</filename> configuration file.
2991 </para>
2992
2993 <para>
2994 Consider an example that configures the <filename>linux-yocto-3.14</filename>
2995 kernel.
2996 The OpenEmbedded build system recognizes this kernel as
2997 <filename>linux-yocto</filename>.
2998 Thus, the following commands from the shell in which you previously sourced the
2999 environment initialization script cleans the shared state cache and the
3000 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
3001 directory and then runs <filename>menuconfig</filename>:
3002 <literallayout class='monospaced'>
3003 $ bitbake linux-yocto -c menuconfig
3004 </literallayout>
3005 </para>
3006
3007 <para>
3008 Once <filename>menuconfig</filename> launches, use the interface
3009 to navigate through the selections to find the configuration settings in
3010 which you are interested.
3011 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
3012 You can find it at <filename>Processor Type and Features</filename> under
3013 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
3014 After highlighting the selection, use the arrow keys to select or deselect
3015 the setting.
3016 When you are finished with all your selections, exit out and save them.
3017 </para>
3018
3019 <para>
3020 Saving the selections updates the <filename>.config</filename> configuration file.
3021 This is the file that the OpenEmbedded build system uses to configure the
3022 kernel during the build.
3023 You can find and examine this file in the Build Directory in
3024 <filename>tmp/work/</filename>.
3025 The actual <filename>.config</filename> is located in the area where the
3026 specific kernel is built.
3027 For example, if you were building a Linux Yocto kernel based on the
3028 Linux 3.14 kernel and you were building a QEMU image targeted for
3029 <filename>x86</filename> architecture, the
3030 <filename>.config</filename> file would be located here:
3031 <literallayout class='monospaced'>
3032 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f...
3033 ...656ed30-r1/linux-qemux86-standard-build
3034 </literallayout>
3035 <note>
3036 The previous example directory is artificially split and many of the characters
3037 in the actual filename are omitted in order to make it more readable.
3038 Also, depending on the kernel you are using, the exact pathname
3039 for <filename>linux-yocto-3.14...</filename> might differ.
3040 </note>
3041 </para>
3042
3043 <para>
3044 Within the <filename>.config</filename> file, you can see the kernel settings.
3045 For example, the following entry shows that symmetric multi-processor support
3046 is not set:
3047 <literallayout class='monospaced'>
3048 # CONFIG_SMP is not set
3049 </literallayout>
3050 </para>
3051
3052 <para>
3053 A good method to isolate changed configurations is to use a combination of the
3054 <filename>menuconfig</filename> tool and simple shell commands.
3055 Before changing configurations with <filename>menuconfig</filename>, copy the
3056 existing <filename>.config</filename> and rename it to something else,
3057 use <filename>menuconfig</filename> to make
3058 as many changes as you want and save them, then compare the renamed configuration
3059 file against the newly created file.
3060 You can use the resulting differences as your base to create configuration fragments
3061 to permanently save in your kernel layer.
3062 <note>
3063 Be sure to make a copy of the <filename>.config</filename> and don't just
3064 rename it.
3065 The build system needs an existing <filename>.config</filename>
3066 from which to work.
3067 </note>
3068 </para>
3069 </section>
3070
3071 <section id='creating-config-fragments'>
3072 <title>Creating Configuration Fragments</title>
3073
3074 <para>
3075 Configuration fragments are simply kernel options that appear in a file
3076 placed where the OpenEmbedded build system can find and apply them.
3077 Syntactically, the configuration statement is identical to what would appear
3078 in the <filename>.config</filename> file, which is in the
3079 <link linkend='build-directory'>Build Directory</link> in
3080 <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
3081 </para>
3082
3083 <para>
3084 It is simple to create a configuration fragment.
3085 For example, issuing the following from the shell creates a configuration fragment
3086 file named <filename>my_smp.cfg</filename> that enables multi-processor support
3087 within the kernel:
3088 <literallayout class='monospaced'>
3089 $ echo "CONFIG_SMP=y" >> my_smp.cfg
3090 </literallayout>
3091 <note>
3092 All configuration files must use the <filename>.cfg</filename> extension in order
3093 for the OpenEmbedded build system to recognize them as a configuration fragment.
3094 </note>
3095 </para>
3096
3097 <para>
3098 Where do you put your configuration files?
3099 You can place these configuration files in the same area pointed to by
3100 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
3101 The OpenEmbedded build system will pick up the configuration and add it to the
3102 kernel's configuration.
3103 For example, suppose you had a set of configuration options in a file called
3104 <filename>myconfig.cfg</filename>.
3105 If you put that file inside a directory named <filename>linux-yocto</filename>
3106 that resides in the same directory as the kernel's append file and then add
3107 a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
3108 those configuration options will be picked up and applied when the kernel is built.
3109 <literallayout class='monospaced'>
3110 SRC_URI += "file://myconfig.cfg"
3111 </literallayout>
3112 </para>
3113
3114 <para>
3115 As mentioned earlier, you can group related configurations into multiple files and
3116 name them all in the <filename>SRC_URI</filename> statement as well.
3117 For example, you could group separate configurations specifically for Ethernet and graphics
3118 into their own files and add those by using a <filename>SRC_URI</filename> statement like the
3119 following in your append file:
3120 <literallayout class='monospaced'>
3121 SRC_URI += "file://myconfig.cfg \
3122 file://eth.cfg \
3123 file://gfx.cfg"
3124 </literallayout>
3125 </para>
3126 </section>
3127
3128 <section id='fine-tuning-the-kernel-configuration-file'>
3129 <title>Fine-Tuning the Kernel Configuration File</title>
3130
3131 <para>
3132 You can make sure the <filename>.config</filename> file is as lean or efficient as
3133 possible by reading the output of the kernel configuration fragment audit,
3134 noting any issues, making changes to correct the issues, and then repeating.
3135 </para>
3136
3137 <para>
3138 As part of the kernel build process, the
3139 <filename>kernel_configcheck</filename> task runs.
3140 This task validates the kernel configuration by checking the final
3141 <filename>.config</filename> file against the input files.
3142 During the check, the task produces warning messages for the following
3143 issues:
3144 <itemizedlist>
3145 <listitem><para>Requested options that did not make the final
3146 <filename>.config</filename> file.</para></listitem>
3147 <listitem><para>Configuration items that appear twice in the same
3148 configuration fragment.</para></listitem>
3149 <listitem><para>Configuration items tagged as "required" that were overridden.
3150 </para></listitem>
3151 <listitem><para>A board overrides a non-board specific option.</para></listitem>
3152 <listitem><para>Listed options not valid for the kernel being processed.
3153 In other words, the option does not appear anywhere.</para></listitem>
3154 </itemizedlist>
3155 <note>
3156 The <filename>kernel_configcheck</filename> task can also optionally report
3157 if an option is overridden during processing.
3158 </note>
3159 </para>
3160
3161 <para>
3162 For each output warning, a message points to the file
3163 that contains a list of the options and a pointer to the config
3164 fragment that defines them.
3165 Collectively, the files are the key to streamlining the configuration.
3166 </para>
3167
3168 <para>
3169 To streamline the configuration, do the following:
3170 <orderedlist>
3171 <listitem><para>Start with a full configuration that you know
3172 works - it builds and boots successfully.
3173 This configuration file will be your baseline.</para></listitem>
3174 <listitem><para>Separately run the <filename>configme</filename> and
3175 <filename>kernel_configcheck</filename> tasks.</para></listitem>
3176 <listitem><para>Take the resulting list of files from the
3177 <filename>kernel_configcheck</filename> task warnings and do the following:
3178 <itemizedlist>
3179 <listitem><para>Drop values that are redefined in the fragment but do not
3180 change the final <filename>.config</filename> file.</para></listitem>
3181 <listitem><para>Analyze and potentially drop values from the
3182 <filename>.config</filename> file that override required
3183 configurations.</para></listitem>
3184 <listitem><para>Analyze and potentially remove non-board specific options.
3185 </para></listitem>
3186 <listitem><para>Remove repeated and invalid options.</para></listitem>
3187 </itemizedlist></para></listitem>
3188 <listitem><para>After you have worked through the output of the kernel configuration
3189 audit, you can re-run the <filename>configme</filename>
3190 and <filename>kernel_configcheck</filename> tasks to see the results of your
3191 changes.
3192 If you have more issues, you can deal with them as described in the
3193 previous step.</para></listitem>
3194 </orderedlist>
3195 </para>
3196
3197 <para>
3198 Iteratively working through steps two through four eventually yields
3199 a minimal, streamlined configuration file.
3200 Once you have the best <filename>.config</filename>, you can build the Linux
3201 Yocto kernel.
3202 </para>
3203 </section>
3204 </section>
3205
3206 <section id="patching-the-kernel">
3207 <title>Patching the Kernel</title>
3208
3209 <para>
3210 Patching the kernel involves changing or adding configurations to an existing kernel,
3211 changing or adding recipes to the kernel that are needed to support specific hardware features,
3212 or even altering the source code itself.
3213 <note>
3214 You can use the <filename>yocto-kernel</filename> script
3215 found in the <link linkend='source-directory'>Source Directory</link>
3216 under <filename>scripts</filename> to manage kernel patches and configuration.
3217 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
3218 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
3219 more information.</note>
3220 </para>
3221
3222 <para>
3223 This example creates a simple patch by adding some QEMU emulator console
3224 output at boot time through <filename>printk</filename> statements in the kernel's
3225 <filename>calibrate.c</filename> source code file.
3226 Applying the patch and booting the modified image causes the added
3227 messages to appear on the emulator's console.
3228 </para>
3229
3230 <para>
3231 The example assumes a clean build exists for the <filename>qemux86</filename>
3232 machine in a
3233 <link linkend='source-directory'>Source Directory</link>
3234 named <filename>poky</filename>.
3235 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
3236 <filename>build</filename> and is located in <filename>poky</filename> and
3237 the kernel is based on the Linux 3.4 kernel.
3238 For general information on how to configure the most efficient build, see the
3239 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
3240 in the Yocto Project Quick Start.
3241 </para>
3242
3243 <para>
3244 Also, for more information on patching the kernel, see the
3245 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
3246 section in the Yocto Project Linux Kernel Development Manual.
3247 </para>
3248
3249 <section id='create-a-layer-for-your-changes'>
3250 <title>Create a Layer for your Changes</title>
3251
3252 <para>
3253 The first step is to create a layer so you can isolate your
3254 changes.
3255 Rather than use the <filename>yocto-layer</filename> script
3256 to create the layer, this example steps through the process
3257 by hand.
3258 If you want information on the script that creates a general
3259 layer, see the
3260 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3261 section.
3262 </para>
3263
3264 <para>
3265 These two commands create a directory you can use for your
3266 layer:
3267 <literallayout class='monospaced'>
3268 $ cd ~/poky
3269 $ mkdir meta-mylayer
3270 </literallayout>
3271 Creating a directory that follows the Yocto Project layer naming
3272 conventions sets up the layer for your changes.
3273 The layer is where you place your configuration files, append
3274 files, and patch files.
3275 To learn more about creating a layer and filling it with the
3276 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
3277 and Creating Layers</link>" section.
3278 </para>
3279 </section>
3280
3281 <section id='finding-the-kernel-source-code'>
3282 <title>Finding the Kernel Source Code</title>
3283
3284 <para>
3285 Each time you build a kernel image, the kernel source code is fetched
3286 and unpacked into the following directory:
3287 <literallayout class='monospaced'>
3288 ${S}/linux
3289 </literallayout>
3290 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
3291 section and the
3292 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
3293 for more information about where source is kept during a build.
3294 </para>
3295
3296 <para>
3297 For this example, we are going to patch the
3298 <filename>init/calibrate.c</filename> file
3299 by adding some simple console <filename>printk</filename> statements that we can
3300 see when we boot the image using QEMU.
3301 </para>
3302 </section>
3303
3304 <section id='creating-the-patch'>
3305 <title>Creating the Patch</title>
3306
3307 <para>
3308 Two methods exist by which you can create the patch:
3309 <link linkend='using-a-git-workflow'>Git workflow</link> and
3310 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
3311 For kernel patches, the Git workflow is more appropriate.
3312 This section assumes the Git workflow and shows the steps specific to
3313 this example.
3314 <orderedlist>
3315 <listitem><para><emphasis>Change the working directory</emphasis>:
3316 Change to where the kernel source code is before making
3317 your edits to the <filename>calibrate.c</filename> file:
3318 <literallayout class='monospaced'>
3319 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
3320 </literallayout>
3321 Because you are working in an established Git repository,
3322 you must be in this directory in order to commit your changes
3323 and create the patch file.
3324 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
3325 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
3326 represent the version and revision for the
3327 <filename>linux-yocto</filename> recipe.
3328 The <filename>PV</filename> variable includes the Git meta and machine
3329 hashes, which make the directory name longer than you might
3330 expect.
3331 </note></para></listitem>
3332 <listitem><para><emphasis>Edit the source file</emphasis>:
3333 Edit the <filename>init/calibrate.c</filename> file to have the
3334 following changes:
3335 <literallayout class='monospaced'>
3336 void calibrate_delay(void)
3337 {
3338 unsigned long lpj;
3339 static bool printed;
3340 int this_cpu = smp_processor_id();
3341
3342 printk("*************************************\n");
3343 printk("* *\n");
3344 printk("* HELLO YOCTO KERNEL *\n");
3345 printk("* *\n");
3346 printk("*************************************\n");
3347
3348 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
3349 .
3350 .
3351 .
3352 </literallayout></para></listitem>
3353 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
3354 These Git commands display the modified file, stage it, and then
3355 commit the file:
3356 <literallayout class='monospaced'>
3357 $ git status
3358 $ git add init/calibrate.c
3359 $ git commit -m "calibrate: Add printk example"
3360 </literallayout></para></listitem>
3361 <listitem><para><emphasis>Generate the patch file</emphasis>:
3362 This Git command creates the a patch file named
3363 <filename>0001-calibrate-Add-printk-example.patch</filename>
3364 in the current directory.
3365 <literallayout class='monospaced'>
3366 $ git format-patch -1
3367 </literallayout>
3368 </para></listitem>
3369 </orderedlist>
3370 </para>
3371 </section>
3372
3373 <section id='set-up-your-layer-for-the-build'>
3374 <title>Set Up Your Layer for the Build</title>
3375
3376 <para>These steps get your layer set up for the build:
3377 <orderedlist>
3378 <listitem><para><emphasis>Create additional structure</emphasis>:
3379 Create the additional layer structure:
3380 <literallayout class='monospaced'>
3381 $ cd ~/poky/meta-mylayer
3382 $ mkdir conf
3383 $ mkdir recipes-kernel
3384 $ mkdir recipes-kernel/linux
3385 $ mkdir recipes-kernel/linux/linux-yocto
3386 </literallayout>
3387 The <filename>conf</filename> directory holds your configuration files, while the
3388 <filename>recipes-kernel</filename> directory holds your append file and
3389 your patch file.</para></listitem>
3390 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
3391 Move to the <filename>meta-mylayer/conf</filename> directory and create
3392 the <filename>layer.conf</filename> file as follows:
3393 <literallayout class='monospaced'>
3394 # We have a conf and classes directory, add to BBPATH
3395 BBPATH .= ":${LAYERDIR}"
3396
3397 # We have recipes-* directories, add to BBFILES
3398 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
3399 ${LAYERDIR}/recipes-*/*/*.bbappend"
3400
3401 BBFILE_COLLECTIONS += "mylayer"
3402 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
3403 BBFILE_PRIORITY_mylayer = "5"
3404 </literallayout>
3405 Notice <filename>mylayer</filename> as part of the last three
3406 statements.</para></listitem>
3407 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
3408 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
3409 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
3410 <literallayout class='monospaced'>
3411 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3412
3413 SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
3414 </literallayout>
3415 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
3416 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
3417 statements enable the OpenEmbedded build system to find the patch file.
3418 For more information on using append files, see the
3419 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3420 section.
3421 </para></listitem>
3422 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
3423 Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
3424 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
3425 directory.</para></listitem>
3426 </orderedlist>
3427 </para>
3428 </section>
3429
3430 <section id='set-up-for-the-build'>
3431 <title>Set Up for the Build</title>
3432
3433 <para>
3434 Do the following to make sure the build parameters are set up for the example.
3435 Once you set up these build parameters, they do not have to change unless you
3436 change the target architecture of the machine you are building:
3437 <itemizedlist>
3438 <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
3439 selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
3440 definition within the <filename>local.conf</filename> file in the
3441 <link linkend='build-directory'>Build Directory</link>
3442 specifies the target architecture used when building the Linux kernel.
3443 By default, <filename>MACHINE</filename> is set to
3444 <filename>qemux86</filename>, which specifies a 32-bit
3445 <trademark class='registered'>Intel</trademark> Architecture
3446 target machine suitable for the QEMU emulator.</para></listitem>
3447 <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
3448 layer:</emphasis> The
3449 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
3450 variable in the
3451 <filename>bblayers.conf</filename> file found in the
3452 <filename>poky/build/conf</filename> directory needs to have the path to your local
3453 <filename>meta-mylayer</filename> layer.
3454 By default, the <filename>BBLAYERS</filename> variable contains paths to
3455 <filename>meta</filename>, <filename>meta-yocto</filename>, and
3456 <filename>meta-yocto-bsp</filename> in the
3457 <filename>poky</filename> Git repository.
3458 Add the path to your <filename>meta-mylayer</filename> location:
3459 <literallayout class='monospaced'>
3460 BBLAYERS ?= " \
3461 $HOME/poky/meta \
3462 $HOME/poky/meta-yocto \
3463 $HOME/poky/meta-yocto-bsp \
3464 $HOME/poky/meta-mylayer \
3465 "
3466
3467 BBLAYERS_NON_REMOVABLE ?= " \
3468 $HOME/poky/meta \
3469 $HOME/poky/meta-yocto \
3470 "
3471 </literallayout></para></listitem>
3472 </itemizedlist>
3473 </para>
3474 </section>
3475
3476 <section id='build-the-modified-qemu-kernel-image'>
3477 <title>Build the Modified QEMU Kernel Image</title>
3478
3479 <para>
3480 The following steps build your modified kernel image:
3481 <orderedlist>
3482 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
3483 Your environment should be set up since you previously sourced
3484 the
3485 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
3486 script.
3487 If it is not, source the script again from <filename>poky</filename>.
3488 <literallayout class='monospaced'>
3489 $ cd ~/poky
3490 $ source &OE_INIT_FILE;
3491 </literallayout>
3492 </para></listitem>
3493 <listitem><para><emphasis>Clean up</emphasis>:
3494 Be sure to clean the shared state out by running the
3495 <filename>cleansstate</filename> BitBake task as follows from your Build Directory:
3496 <literallayout class='monospaced'>
3497 $ bitbake -c cleansstate linux-yocto
3498 </literallayout></para>
3499 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
3500 directory inside the
3501 <link linkend='build-directory'>Build Directory</link>.
3502 Always use the various BitBake clean tasks to clear out previous
3503 build artifacts.
3504 </note></para></listitem>
3505 <listitem><para><emphasis>Build the image</emphasis>:
3506 Next, build the kernel image using this command:
3507 <literallayout class='monospaced'>
3508 $ bitbake -k linux-yocto
3509 </literallayout></para></listitem>
3510 </orderedlist>
3511 </para>
3512 </section>
3513
3514 <section id='boot-the-image-and-verify-your-changes'>
3515 <title>Boot the Image and Verify Your Changes</title>
3516
3517 <para>
3518 These steps boot the image and allow you to see the changes
3519 <orderedlist>
3520 <listitem><para><emphasis>Boot the image</emphasis>:
3521 Boot the modified image in the QEMU emulator
3522 using this command:
3523 <literallayout class='monospaced'>
3524 $ runqemu qemux86
3525 </literallayout></para></listitem>
3526 <listitem><para><emphasis>Verify the changes</emphasis>:
3527 Log into the machine using <filename>root</filename> with no password and then
3528 use the following shell command to scroll through the console's boot output.
3529 <literallayout class='monospaced'>
3530 # dmesg | less
3531 </literallayout>
3532 You should see the results of your <filename>printk</filename> statements
3533 as part of the output.</para></listitem>
3534 </orderedlist>
3535 </para>
3536 </section>
3537 </section>
3538
3539 <section id='making-images-more-secure'>
3540 <title>Making Images More Secure</title>
3541
3542 <para>
3543 The Yocto Project has security flags that you can enable that
3544 help make your build output more secure.
3545 The security flags are in the
3546 <filename>meta/conf/distro/include/security_flags.inc</filename>
3547 file in your
3548 <link linkend='source-directory'>Source Directory</link>
3549 (e.g. <filename>poky</filename>).
3550 </para>
3551
3552 <para>
3553 These GCC/LD flags enable more secure code generation.
3554 By including the <filename>security_flags.inc</filename>
3555 file, you enable flags to the compiler and linker that cause
3556 them to generate more secure code.
3557 <note>
3558 These flags are enabled by default in the
3559 <filename>poky-lsb</filename> distribution.
3560 </note>
3561 Use the following line in your
3562 <filename>local.conf</filename> file
3563 to enable the security compiler and
3564 linker flags to your build:
3565 <literallayout class='monospaced'>
3566 require conf/distro/include/security_flags.inc
3567 </literallayout>
3568 </para>
3569 </section>
3570
3571 <section id='creating-your-own-distribution'>
3572 <title>Creating Your Own Distribution</title>
3573
3574 <para>
3575 When you build an image using the Yocto Project and
3576 do not alter any distribution
3577 <link linkend='metadata'>Metadata</link>, you are creating a
3578 Poky distribution.
3579 If you wish to gain more control over package alternative
3580 selections, compile-time options, and other low-level
3581 configurations, you can create your own distribution.
3582 </para>
3583
3584 <para>
3585 To create your own distribution, the basic steps consist of
3586 creating your own distribution layer, creating your own
3587 distribution configuration file, and then adding any needed
3588 code and Metadata to the layer.
3589 The following steps provide some more detail:
3590 <itemizedlist>
3591 <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
3592 Create your distribution layer so that you can keep your
3593 Metadata and code for the distribution separate.
3594 It is strongly recommended that you create and use your own
3595 layer for configuration and code.
3596 Using your own layer as compared to just placing
3597 configurations in a <filename>local.conf</filename>
3598 configuration file makes it easier to reproduce the same
3599 build configuration when using multiple build machines.
3600 See the
3601 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
3602 section for information on how to quickly set up a layer.
3603 </para></listitem>
3604 <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
3605 The distribution configuration file needs to be created in
3606 the <filename>conf/distro</filename> directory of your
3607 layer.
3608 You need to name it using your distribution name
3609 (e.g. <filename>mydistro.conf</filename>).
3610 <note>
3611 The
3612 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3613 variable in your
3614 <filename>local.conf</filename> file determines the
3615 name of your distribution.
3616 </note></para>
3617 <para>You can split out parts of your configuration file
3618 into include files and then "require" them from within
3619 your distribution configuration file.
3620 Be sure to place the include files in the
3621 <filename>conf/distro/include</filename> directory of
3622 your layer.
3623 A common example usage of include files would be to
3624 separate out the selection of desired version and revisions
3625 for individual recipes.
3626</para>
3627 <para>Your configuration file needs to set the following
3628 required variables:
3629 <literallayout class='monospaced'>
3630 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
3631 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink>
3632 </literallayout>
3633 These following variables are optional and you typically
3634 set them from the distribution configuration file:
3635 <literallayout class='monospaced'>
3636 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
3637 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink>
3638 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink>
3639 <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink>
3640 </literallayout>
3641 <tip>
3642 If you want to base your distribution configuration file
3643 on the very basic configuration from OE-Core, you
3644 can use
3645 <filename>conf/distro/defaultsetup.conf</filename> as
3646 a reference and just include variables that differ
3647 as compared to <filename>defaultsetup.conf</filename>.
3648 Alternatively, you can create a distribution
3649 configuration file from scratch using the
3650 <filename>defaultsetup.conf</filename> file
3651 or configuration files from other distributions
3652 such as Poky or Angstrom as references.
3653 </tip></para></listitem>
3654 <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
3655 Be sure to define any other variables for which you want to
3656 create a default or enforce as part of the distribution
3657 configuration.
3658 You can include nearly any variable from the
3659 <filename>local.conf</filename> file.
3660 The variables you use are not limited to the list in the
3661 previous bulleted item.</para></listitem>
3662 <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
3663 In your <filename>local.conf</filename> file in the
3664 <link linkend='build-directory'>Build Directory</link>,
3665 set your
3666 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3667 variable to point to your distribution's configuration file.
3668 For example, if your distribution's configuration file is
3669 named <filename>mydistro.conf</filename>, then you point
3670 to it as follows:
3671 <literallayout class='monospaced'>
3672 DISTRO = "mydistro"
3673 </literallayout></para></listitem>
3674 <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
3675 Use your layer to hold other information needed for the
3676 distribution:
3677 <itemizedlist>
3678 <listitem><para>Add recipes for installing
3679 distro-specific configuration files that are not
3680 already installed by another recipe.
3681 If you have distro-specific configuration files
3682 that are included by an existing recipe, you should
3683 add an append file (<filename>.bbappend</filename>)
3684 for those.
3685 For general information and recommendations
3686 on how to add recipes to your layer, see the
3687 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
3688 and
3689 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
3690 sections.</para></listitem>
3691 <listitem><para>Add any image recipes that are specific
3692 to your distribution.</para></listitem>
3693 <listitem><para>Add a <filename>psplash</filename>
3694 append file for a branded splash screen.
3695 For information on append files, see the
3696 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
3697 section.</para></listitem>
3698 <listitem><para>Add any other append files to make
3699 custom changes that are specific to individual
3700 recipes.</para></listitem>
3701 </itemizedlist></para></listitem>
3702 </itemizedlist>
3703 </para>
3704 </section>
3705
3706 <section id='building-a-tiny-system'>
3707 <title>Building a Tiny System</title>
3708
3709 <para>
3710 Very small distributions have some significant advantages such
3711 as requiring less on-die or in-package memory (cheaper), better
3712 performance through efficient cache usage, lower power requirements
3713 due to less memory, faster boot times, and reduced development
3714 overhead.
3715 Some real-world examples where a very small distribution gives
3716 you distinct advantages are digital cameras, medical devices,
3717 and small headless systems.
3718 </para>
3719
3720 <para>
3721 This section presents information that shows you how you can
3722 trim your distribution to even smaller sizes than the
3723 <filename>poky-tiny</filename> distribution, which is around
3724 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
3725 </para>
3726
3727 <section id='tiny-system-overview'>
3728 <title>Overview</title>
3729
3730 <para>
3731 The following list presents the overall steps you need to
3732 consider and perform to create distributions with smaller
3733 root filesystems, achieve faster boot times, maintain your critical
3734 functionality, and avoid initial RAM disks:
3735 <itemizedlist>
3736 <listitem><para>
3737 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
3738 </para></listitem>
3739 <listitem><para>
3740 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
3741 </para></listitem>
3742 <listitem><para>
3743 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
3744 </para></listitem>
3745 <listitem><para>
3746 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
3747 </para></listitem>
3748 <listitem><para>
3749 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
3750 </para></listitem>
3751 <listitem><para>
3752 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
3753 </para></listitem>
3754 <listitem><para>
3755 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
3756 </para></listitem>
3757 </itemizedlist>
3758 </para>
3759 </section>
3760
3761 <section id='goals-and-guiding-principles'>
3762 <title>Goals and Guiding Principles</title>
3763
3764 <para>
3765 Before you can reach your destination, you need to know
3766 where you are going.
3767 Here is an example list that you can use as a guide when
3768 creating very small distributions:
3769 <itemizedlist>
3770 <listitem><para>Determine how much space you need
3771 (e.g. a kernel that is 1 Mbyte or less and
3772 a root filesystem that is 3 Mbytes or less).
3773 </para></listitem>
3774 <listitem><para>Find the areas that are currently
3775 taking 90% of the space and concentrate on reducing
3776 those areas.
3777 </para></listitem>
3778 <listitem><para>Do not create any difficult "hacks"
3779 to achieve your goals.</para></listitem>
3780 <listitem><para>Leverage the device-specific
3781 options.</para></listitem>
3782 <listitem><para>Work in a separate layer so that you
3783 keep changes isolated.
3784 For information on how to create layers, see
3785 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
3786 </para></listitem>
3787 </itemizedlist>
3788 </para>
3789 </section>
3790
3791 <section id='understand-what-gives-your-image-size'>
3792 <title>Understand What Contributes to Your Image Size</title>
3793
3794 <para>
3795 It is easiest to have something to start with when creating
3796 your own distribution.
3797 You can use the Yocto Project out-of-the-box to create the
3798 <filename>poky-tiny</filename> distribution.
3799 Ultimately, you will want to make changes in your own
3800 distribution that are likely modeled after
3801 <filename>poky-tiny</filename>.
3802 <note>
3803 To use <filename>poky-tiny</filename> in your build,
3804 set the
3805 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
3806 variable in your
3807 <filename>local.conf</filename> file to "poky-tiny"
3808 as described in the
3809 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
3810 section.
3811 </note>
3812 </para>
3813
3814 <para>
3815 Understanding some memory concepts will help you reduce the
3816 system size.
3817 Memory consists of static, dynamic, and temporary memory.
3818 Static memory is the TEXT (code), DATA (initialized data
3819 in the code), and BSS (uninitialized data) sections.
3820 Dynamic memory represents memory that is allocated at runtime:
3821 stacks, hash tables, and so forth.
3822 Temporary memory is recovered after the boot process.
3823 This memory consists of memory used for decompressing
3824 the kernel and for the <filename>__init__</filename>
3825 functions.
3826 </para>
3827
3828 <para>
3829 To help you see where you currently are with kernel and root
3830 filesystem sizes, you can use two tools found in the
3831 <link linkend='source-directory'>Source Directory</link> in
3832 the <filename>scripts/tiny/</filename> directory:
3833 <itemizedlist>
3834 <listitem><para><filename>ksize.py</filename>: Reports
3835 component sizes for the kernel build objects.
3836 </para></listitem>
3837 <listitem><para><filename>dirsize.py</filename>: Reports
3838 component sizes for the root filesystem.</para></listitem>
3839 </itemizedlist>
3840 This next tool and command help you organize configuration
3841 fragments and view file dependencies in a human-readable form:
3842 <itemizedlist>
3843 <listitem><para><filename>merge_config.sh</filename>:
3844 Helps you manage configuration files and fragments
3845 within the kernel.
3846 With this tool, you can merge individual configuration
3847 fragments together.
3848 The tool allows you to make overrides and warns you
3849 of any missing configuration options.
3850 The tool is ideal for allowing you to iterate on
3851 configurations, create minimal configurations, and
3852 create configuration files for different machines
3853 without having to duplicate your process.</para>
3854 <para>The <filename>merge_config.sh</filename> script is
3855 part of the Linux Yocto kernel Git repositories
3856 (i.e. <filename>linux-yocto-3.14</filename>,
3857 <filename>linux-yocto-3.10</filename>,
3858 <filename>linux-yocto-3.8</filename>, and so forth)
3859 in the
3860 <filename>scripts/kconfig</filename> directory.</para>
3861 <para>For more information on configuration fragments,
3862 see the
3863 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
3864 section of the Yocto Project Linux Kernel Development
3865 Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
3866 section, which is in this manual.</para></listitem>
3867 <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
3868 Using the BitBake command with these options brings up
3869 a Dependency Explorer from which you can view file
3870 dependencies.
3871 Understanding these dependencies allows you to make
3872 informed decisions when cutting out various pieces of the
3873 kernel and root filesystem.</para></listitem>
3874 </itemizedlist>
3875 </para>
3876 </section>
3877
3878 <section id='trim-the-root-filesystem'>
3879 <title>Trim the Root Filesystem</title>
3880
3881 <para>
3882 The root filesystem is made up of packages for booting,
3883 libraries, and applications.
3884 To change things, you can configure how the packaging happens,
3885 which changes the way you build them.
3886 You can also tweak the filesystem itself or select a different
3887 filesystem.
3888 </para>
3889
3890 <para>
3891 First, find out what is hogging your root filesystem by running the
3892 <filename>dirsize.py</filename> script from your root directory:
3893 <literallayout class='monospaced'>
3894 $ cd &lt;root-directory-of-image&gt;
3895 $ dirsize.py 100000 > dirsize-100k.log
3896 $ cat dirsize-100k.log
3897 </literallayout>
3898 You can apply a filter to the script to ignore files under
3899 a certain size.
3900 The previous example filters out any files below 100 Kbytes.
3901 The sizes reported by the tool are uncompressed, and thus
3902 will be smaller by a relatively constant factor in a
3903 compressed root filesystem.
3904 When you examine your log file, you can focus on areas of the
3905 root filesystem that take up large amounts of memory.
3906 </para>
3907
3908 <para>
3909 You need to be sure that what you eliminate does not cripple
3910 the functionality you need.
3911 One way to see how packages relate to each other is by using
3912 the Dependency Explorer UI with the BitBake command:
3913 <literallayout class='monospaced'>
3914 $ cd &lt;image-directory&gt;
3915 $ bitbake -u depexp -g &lt;image&gt;
3916 </literallayout>
3917 Use the interface to select potential packages you wish to
3918 eliminate and see their dependency relationships.
3919 </para>
3920
3921 <para>
3922 When deciding how to reduce the size, get rid of packages that
3923 result in minimal impact on the feature set.
3924 For example, you might not need a VGA display.
3925 Or, you might be able to get by with <filename>devtmpfs</filename>
3926 and <filename>mdev</filename> instead of
3927 <filename>udev</filename>.
3928 </para>
3929
3930 <para>
3931 Use your <filename>local.conf</filename> file to make changes.
3932 For example, to eliminate <filename>udev</filename> and
3933 <filename>glib</filename>, set the following in the
3934 local configuration file:
3935 <literallayout class='monospaced'>
3936 VIRTUAL-RUNTIME_dev_manager = ""
3937 </literallayout>
3938 </para>
3939
3940 <para>
3941 Finally, you should consider exactly the type of root
3942 filesystem you need to meet your needs while also reducing
3943 its size.
3944 For example, consider <filename>cramfs</filename>,
3945 <filename>squashfs</filename>, <filename>ubifs</filename>,
3946 <filename>ext2</filename>, or an <filename>initramfs</filename>
3947 using <filename>initramfs</filename>.
3948 Be aware that <filename>ext3</filename> requires a 1 Mbyte
3949 journal.
3950 If you are okay with running read-only, you do not need this
3951 journal.
3952 </para>
3953
3954 <note>
3955 After each round of elimination, you need to rebuild your
3956 system and then use the tools to see the effects of your
3957 reductions.
3958 </note>
3959
3960
3961 </section>
3962
3963 <section id='trim-the-kernel'>
3964 <title>Trim the Kernel</title>
3965
3966 <para>
3967 The kernel is built by including policies for hardware-independent
3968 aspects.
3969 What subsystems do you enable?
3970 For what architecture are you building?
3971 Which drivers do you build by default?
3972 <note>You can modify the kernel source if you want to help
3973 with boot time.
3974 </note>
3975 </para>
3976
3977 <para>
3978 Run the <filename>ksize.py</filename> script from the top-level
3979 Linux build directory to get an idea of what is making up
3980 the kernel:
3981 <literallayout class='monospaced'>
3982 $ cd &lt;top-level-linux-build-directory&gt;
3983 $ ksize.py > ksize.log
3984 $ cat ksize.log
3985 </literallayout>
3986 When you examine the log, you will see how much space is
3987 taken up with the built-in <filename>.o</filename> files for
3988 drivers, networking, core kernel files, filesystem, sound,
3989 and so forth.
3990 The sizes reported by the tool are uncompressed, and thus
3991 will be smaller by a relatively constant factor in a compressed
3992 kernel image.
3993 Look to reduce the areas that are large and taking up around
3994 the "90% rule."
3995 </para>
3996
3997 <para>
3998 To examine, or drill down, into any particular area, use the
3999 <filename>-d</filename> option with the script:
4000 <literallayout class='monospaced'>
4001 $ ksize.py -d > ksize.log
4002 </literallayout>
4003 Using this option breaks out the individual file information
4004 for each area of the kernel (e.g. drivers, networking, and
4005 so forth).
4006 </para>
4007
4008 <para>
4009 Use your log file to see what you can eliminate from the kernel
4010 based on features you can let go.
4011 For example, if you are not going to need sound, you do not
4012 need any drivers that support sound.
4013 </para>
4014
4015 <para>
4016 After figuring out what to eliminate, you need to reconfigure
4017 the kernel to reflect those changes during the next build.
4018 You could run <filename>menuconfig</filename> and make all your
4019 changes at once.
4020 However, that makes it difficult to see the effects of your
4021 individual eliminations and also makes it difficult to replicate
4022 the changes for perhaps another target device.
4023 A better method is to start with no configurations using
4024 <filename>allnoconfig</filename>, create configuration
4025 fragments for individual changes, and then manage the
4026 fragments into a single configuration file using
4027 <filename>merge_config.sh</filename>.
4028 The tool makes it easy for you to iterate using the
4029 configuration change and build cycle.
4030 </para>
4031
4032 <para>
4033 Each time you make configuration changes, you need to rebuild
4034 the kernel and check to see what impact your changes had on
4035 the overall size.
4036 </para>
4037 </section>
4038
4039 <section id='remove-package-management-requirements'>
4040 <title>Remove Package Management Requirements</title>
4041
4042 <para>
4043 Packaging requirements add size to the image.
4044 One way to reduce the size of the image is to remove all the
4045 packaging requirements from the image.
4046 This reduction includes both removing the package manager
4047 and its unique dependencies as well as removing the package
4048 management data itself.
4049 </para>
4050
4051 <para>
4052 To eliminate all the packaging requirements for an image,
4053 be sure that "package-management" is not part of your
4054 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4055 statement for the image.
4056 When you remove this feature, you are removing the package
4057 manager as well as its dependencies from the root filesystem.
4058 </para>
4059 </section>
4060
4061 <section id='look-for-other-ways-to-minimize-size'>
4062 <title>Look for Other Ways to Minimize Size</title>
4063
4064 <para>
4065 Depending on your particular circumstances, other areas that you
4066 can trim likely exist.
4067 The key to finding these areas is through tools and methods
4068 described here combined with experimentation and iteration.
4069 Here are a couple of areas to experiment with:
4070 <itemizedlist>
4071 <listitem><para><filename>eglibc</filename>:
4072 In general, follow this process:
4073 <orderedlist>
4074 <listitem><para>Remove <filename>eglibc</filename>
4075 features from
4076 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
4077 that you think you do not need.</para></listitem>
4078 <listitem><para>Build your distribution.
4079 </para></listitem>
4080 <listitem><para>If the build fails due to missing
4081 symbols in a package, determine if you can
4082 reconfigure the package to not need those
4083 features.
4084 For example, change the configuration to not
4085 support wide character support as is done for
4086 <filename>ncurses</filename>.
4087 Or, if support for those characters is needed,
4088 determine what <filename>eglibc</filename>
4089 features provide the support and restore the
4090 configuration.
4091 </para></listitem>
4092 <listitem><para>Rebuild and repeat the process.
4093 </para></listitem>
4094 </orderedlist></para></listitem>
4095 <listitem><para><filename>busybox</filename>:
4096 For BusyBox, use a process similar as described for
4097 <filename>eglibc</filename>.
4098 A difference is you will need to boot the resulting
4099 system to see if you are able to do everything you
4100 expect from the running system.
4101 You need to be sure to integrate configuration fragments
4102 into Busybox because BusyBox handles its own core
4103 features and then allows you to add configuration
4104 fragments on top.
4105 </para></listitem>
4106 </itemizedlist>
4107 </para>
4108 </section>
4109
4110 <section id='iterate-on-the-process'>
4111 <title>Iterate on the Process</title>
4112
4113 <para>
4114 If you have not reached your goals on system size, you need
4115 to iterate on the process.
4116 The process is the same.
4117 Use the tools and see just what is taking up 90% of the root
4118 filesystem and the kernel.
4119 Decide what you can eliminate without limiting your device
4120 beyond what you need.
4121 </para>
4122
4123 <para>
4124 Depending on your system, a good place to look might be
4125 Busybox, which provides a stripped down
4126 version of Unix tools in a single, executable file.
4127 You might be able to drop virtual terminal services or perhaps
4128 ipv6.
4129 </para>
4130 </section>
4131 </section>
4132
4133 <section id='working-with-packages'>
4134 <title>Working with Packages</title>
4135
4136 <para>
4137 This section describes a few tasks that involve packages:
4138 <itemizedlist>
4139 <listitem><para>
4140 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
4141 </para></listitem>
4142 <listitem><para>
4143 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
4144 </para></listitem>
4145 <listitem><para>
4146 <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link>
4147 </para></listitem>
4148 <listitem><para>
4149 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
4150 </para></listitem>
4151 <listitem><para>
4152 <link linkend='using-runtime-package-management'>Using Runtime Package Management</link>
4153 </para></listitem>
4154 <listitem><para>
4155 <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link>
4156 </para></listitem>
4157 </itemizedlist>
4158 </para>
4159
4160 <section id='excluding-packages-from-an-image'>
4161 <title>Excluding Packages from an Image</title>
4162
4163 <para>
4164 You might find it necessary to prevent specific packages
4165 from being installed into an image.
4166 If so, you can use several variables to direct the build
4167 system to essentially ignore installing recommended packages
4168 or to not install a package at all.
4169 </para>
4170
4171 <para>
4172 The following list introduces variables you can use to
4173 prevent packages from being installed into your image.
4174 Each of these variables only works with IPK and RPM
4175 package types.
4176 Support for Debian packages does not exist.
4177 Also, you can use these variables from your
4178 <filename>local.conf</filename> file or attach them to a
4179 specific image recipe by using a recipe name override.
4180 For more detail on the variables, see the descriptions in the
4181 Yocto Project Reference Manual's glossary chapter.
4182 <itemizedlist>
4183 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
4184 Use this variable to specify "recommended-only"
4185 packages that you do not want installed.
4186 </para></listitem>
4187 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
4188 Use this variable to prevent all "recommended-only"
4189 packages from being installed.
4190 </para></listitem>
4191 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
4192 Use this variable to prevent specific packages from
4193 being installed regardless of whether they are
4194 "recommended-only" or not.
4195 You need to realize that the build process could
4196 fail with an error when you
4197 prevent the installation of a package whose presence
4198 is required by an installed package.
4199 </para></listitem>
4200 </itemizedlist>
4201 </para>
4202 </section>
4203
4204 <section id='incrementing-a-package-revision-number'>
4205 <title>Incrementing a Package Revision Number</title>
4206
4207 <para>
4208 If a committed change results in changing the package output,
4209 then the value of the
4210 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4211 variable needs to be increased (or "bumped").
4212 Increasing <filename>PR</filename> occurs one of two ways:
4213 <itemizedlist>
4214 <listitem><para>Automatically using a Package Revision
4215 Service (PR Service).</para></listitem>
4216 <listitem><para>Manually incrementing the
4217 <filename>PR</filename> variable.</para></listitem>
4218 </itemizedlist>
4219 </para>
4220
4221 <para>
4222 Given that one of the challenges any build system and its
4223 users face is how to maintain a package feed that is compatible
4224 with existing package manager applications such as
4225 RPM, APT, and OPKG, using an automated system is much
4226 preferred over a manual system.
4227 In either system, the main requirement is that version
4228 numbering increases in a linear fashion and that a number of
4229 version components exist that support that linear progression.
4230 </para>
4231
4232 <para>
4233 The following two sections provide information on the PR Service
4234 and on manual <filename>PR</filename> bumping.
4235 </para>
4236
4237 <section id='working-with-a-pr-service'>
4238 <title>Working With a PR Service</title>
4239
4240 <para>
4241 As mentioned, attempting to maintain revision numbers in the
4242 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4243 is error prone, inaccurate, and causes problems for people
4244 submitting recipes.
4245 Conversely, the PR Service automatically generates
4246 increasing numbers, particularly the revision field,
4247 which removes the human element.
4248 <note>
4249 For additional information on using a PR Service, you
4250 can see the
4251 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
4252 wiki page.
4253 </note>
4254 </para>
4255
4256 <para>
4257 The Yocto Project uses variables in order of
4258 decreasing priority to facilitate revision numbering (i.e.
4259 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
4260 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
4261 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4262 for epoch, version, and revision, respectively).
4263 The values are highly dependent on the policies and
4264 procedures of a given distribution and package feed.
4265 </para>
4266
4267 <para>
4268 Because the OpenEmbedded build system uses
4269 "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
4270 which are unique to a given build, the build system
4271 knows when to rebuild packages.
4272 All the inputs into a given task are represented by a
4273 signature, which can trigger a rebuild when different.
4274 Thus, the build system itself does not rely on the
4275 <filename>PR</filename> numbers to trigger a rebuild.
4276 The signatures, however, can be used to generate
4277 <filename>PR</filename> values.
4278 </para>
4279
4280 <para>
4281 The PR Service works with both
4282 <filename>OEBasic</filename> and
4283 <filename>OEBasicHash</filename> generators.
4284 The value of <filename>PR</filename> bumps when the
4285 checksum changes and the different generator mechanisms
4286 change signatures under different circumstances.
4287 </para>
4288
4289 <para>
4290 As implemented, the build system includes values from
4291 the PR Service into the <filename>PR</filename> field as
4292 an addition using the form "<filename>.x</filename>" so
4293 <filename>r0</filename> becomes <filename>r0.1</filename>,
4294 <filename>r0.2</filename> and so forth.
4295 This scheme allows existing <filename>PR</filename> values
4296 to be used for whatever reasons, which include manual
4297 <filename>PR</filename> bumps, should it be necessary.
4298 </para>
4299
4300 <para>
4301 By default, the PR Service is not enabled or running.
4302 Thus, the packages generated are just "self consistent".
4303 The build system adds and removes packages and
4304 there are no guarantees about upgrade paths but images
4305 will be consistent and correct with the latest changes.
4306 </para>
4307
4308 <para>
4309 The simplest form for a PR Service is for it to exist
4310 for a single host development system that builds the
4311 package feed (building system).
4312 For this scenario, you can enable a local PR Service by
4313 setting
4314 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>
4315 in your <filename>local.conf</filename> file in the
4316 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4317 <literallayout class='monospaced'>
4318 PRSERV_HOST = "localhost:0"
4319 </literallayout>
4320 Once the service is started, packages will automatically
4321 get increasing <filename>PR</filename> values and
4322 BitBake will take care of starting and stopping the server.
4323 </para>
4324
4325 <para>
4326 If you have a more complex setup where multiple host
4327 development systems work against a common, shared package
4328 feed, you have a single PR Service running and it is
4329 connected to each building system.
4330 For this scenario, you need to start the PR Service using
4331 the <filename>bitbake-prserv</filename> command:
4332 <literallayout class='monospaced'>
4333 bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
4334 </literallayout>
4335 In addition to hand-starting the service, you need to
4336 update the <filename>local.conf</filename> file of each
4337 building system as described earlier so each system
4338 points to the server and port.
4339 </para>
4340
4341 <para>
4342 It is also recommended you use build history, which adds
4343 some sanity checks to package versions, in conjunction with
4344 the server that is running the PR Service.
4345 To enable build history, add the following to each building
4346 system's <filename>local.conf</filename> file:
4347 <literallayout class='monospaced'>
4348 # It is recommended to activate "buildhistory" for testing the PR service
4349 INHERIT += "buildhistory"
4350 BUILDHISTORY_COMMIT = "1"
4351 </literallayout>
4352 For information on build history, see the
4353 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
4354 section in the Yocto Project Reference Manual.
4355 </para>
4356
4357 <note>
4358 <para>The OpenEmbedded build system does not maintain
4359 <filename>PR</filename> information as part of the
4360 shared state (sstate) packages.
4361 If you maintain an sstate feed, its expected that either
4362 all your building systems that contribute to the sstate
4363 feed use a shared PR Service, or you do not run a PR
4364 Service on any of your building systems.
4365 Having some systems use a PR Service while others do
4366 not leads to obvious problems.</para>
4367 <para>For more information on shared state, see the
4368 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
4369 section in the Yocto Project Reference Manual.</para>
4370 </note>
4371 </section>
4372
4373 <section id='manually-bumping-pr'>
4374 <title>Manually Bumping PR</title>
4375
4376 <para>
4377 The alternative to setting up a PR Service is to manually
4378 bump the
4379 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
4380 variable.
4381 </para>
4382
4383 <para>
4384 If a committed change results in changing the package output,
4385 then the value of the PR variable needs to be increased
4386 (or "bumped") as part of that commit.
4387 For new recipes you should add the <filename>PR</filename>
4388 variable and set its initial value equal to "r0", which is the default.
4389 Even though the default value is "r0", the practice of adding it to a new recipe makes
4390 it harder to forget to bump the variable when you make changes
4391 to the recipe in future.
4392 </para>
4393
4394 <para>
4395 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
4396 you can also use the
4397 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
4398 variable to ensure that
4399 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
4400 <filename>.inc</filename> file itself is changed.
4401 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
4402 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
4403 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
4404 If the <filename>.inc</filename> file is changed then its
4405 <filename>INC_PR</filename> should be incremented.
4406 </para>
4407
4408 <para>
4409 When upgrading the version of a package, assuming the
4410 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
4411 changes, the <filename>PR</filename> variable should be
4412 reset to "r0" (or "$(INC_PR).0" if you are using
4413 <filename>INC_PR</filename>).
4414 </para>
4415
4416 <para>
4417 Usually, version increases occur only to packages.
4418 However, if for some reason <filename>PV</filename> changes but does not
4419 increase, you can increase the
4420 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
4421 variable (Package Epoch).
4422 The <filename>PE</filename> variable defaults to "0".
4423 </para>
4424
4425 <para>
4426 Version numbering strives to follow the
4427 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
4428 Debian Version Field Policy Guidelines</ulink>.
4429 These guidelines define how versions are compared and what "increasing" a version means.
4430 </para>
4431 </section>
4432 </section>
4433
4434 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
4435 <title>Handling a Package Name Alias</title>
4436 <para>
4437 Sometimes a package name you are using might exist under an alias or as a similarly named
4438 package in a different distribution.
4439 The OpenEmbedded build system implements a <filename>distro_check</filename>
4440 task that automatically connects to major distributions
4441 and checks for these situations.
4442 If the package exists under a different name in a different distribution, you get a
4443 <filename>distro_check</filename> mismatch.
4444 You can resolve this problem by defining a per-distro recipe name alias using the
4445 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
4446 variable.
4447 </para>
4448
4449 <para>
4450 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
4451 variable:
4452 <literallayout class='monospaced'>
4453 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
4454 distro2=package_name_alias2 \
4455 distro3=package_name_alias3 \
4456 ..."
4457 </literallayout>
4458 </para>
4459
4460 <para>
4461 If you have more than one distribution alias, separate them with a space.
4462 Note that the build system currently automatically checks the
4463 Fedora, OpenSUSE, Debian, Ubuntu,
4464 and Mandriva distributions for source package recipes without having to specify them
4465 using the <filename>DISTRO_PN_ALIAS</filename> variable.
4466 For example, the following command generates a report that lists the Linux distributions
4467 that include the sources for each of the recipes.
4468 <literallayout class='monospaced'>
4469 $ bitbake world -f -c distro_check
4470 </literallayout>
4471 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
4472 file found in the
4473 <link linkend='source-directory'>Source Directory</link>.
4474 </para>
4475 </section>
4476
4477 <section id='handling-optional-module-packaging'>
4478 <title>Handling Optional Module Packaging</title>
4479
4480 <para>
4481 Many pieces of software split functionality into optional
4482 modules (or plug-ins) and the plug-ins that are built
4483 might depend on configuration options.
4484 To avoid having to duplicate the logic that determines what
4485 modules are available in your recipe or to avoid having
4486 to package each module by hand, the OpenEmbedded build system
4487 provides functionality to handle module packaging dynamically.
4488 </para>
4489
4490 <para>
4491 To handle optional module packaging, you need to do two things:
4492 <itemizedlist>
4493 <listitem><para>Ensure the module packaging is actually
4494 done.</para></listitem>
4495 <listitem><para>Ensure that any dependencies on optional
4496 modules from other recipes are satisfied by your recipe.
4497 </para></listitem>
4498 </itemizedlist>
4499 </para>
4500
4501 <section id='making-sure-the-packaging-is-done'>
4502 <title>Making Sure the Packaging is Done</title>
4503
4504 <para>
4505 To ensure the module packaging actually gets done, you use
4506 the <filename>do_split_packages</filename> function within
4507 the <filename>populate_packages</filename> Python function
4508 in your recipe.
4509 The <filename>do_split_packages</filename> function
4510 searches for a pattern of files or directories under a
4511 specified path and creates a package for each one it finds
4512 by appending to the
4513 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
4514 variable and setting the appropriate values for
4515 <filename>FILES_packagename</filename>,
4516 <filename>RDEPENDS_packagename</filename>,
4517 <filename>DESCRIPTION_packagename</filename>, and so forth.
4518 Here is an example from the <filename>lighttpd</filename>
4519 recipe:
4520 <literallayout class='monospaced'>
4521 python populate_packages_prepend () {
4522 lighttpd_libdir = d.expand('${libdir}')
4523 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
4524 'lighttpd-module-%s', 'Lighttpd module for %s',
4525 extra_depends='')
4526 }
4527 </literallayout>
4528 The previous example specifies a number of things in the
4529 call to <filename>do_split_packages</filename>.
4530 <itemizedlist>
4531 <listitem><para>A directory within the files installed
4532 by your recipe through <filename>do_install</filename>
4533 in which to search.</para></listitem>
4534 <listitem><para>A regular expression used to match module
4535 files in that directory.
4536 In the example, note the parentheses () that mark
4537 the part of the expression from which the module
4538 name should be derived.</para></listitem>
4539 <listitem><para>A pattern to use for the package names.
4540 </para></listitem>
4541 <listitem><para>A description for each package.
4542 </para></listitem>
4543 <listitem><para>An empty string for
4544 <filename>extra_depends</filename>, which disables
4545 the default dependency on the main
4546 <filename>lighttpd</filename> package.
4547 Thus, if a file in <filename>${libdir}</filename>
4548 called <filename>mod_alias.so</filename> is found,
4549 a package called <filename>lighttpd-module-alias</filename>
4550 is created for it and the
4551 <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
4552 is set to "Lighttpd module for alias".</para></listitem>
4553 </itemizedlist>
4554 </para>
4555
4556 <para>
4557 Often, packaging modules is as simple as the previous
4558 example.
4559 However, more advanced options exist that you can use
4560 within <filename>do_split_packages</filename> to modify its
4561 behavior.
4562 And, if you need to, you can add more logic by specifying
4563 a hook function that is called for each package.
4564 It is also perfectly acceptable to call
4565 <filename>do_split_packages</filename> multiple times if
4566 you have more than one set of modules to package.
4567 </para>
4568
4569 <para>
4570 For more examples that show how to use
4571 <filename>do_split_packages</filename>, see the
4572 <filename>connman.inc</filename> file in the
4573 <filename>meta/recipes-connectivity/connman/</filename>
4574 directory of the <filename>poky</filename>
4575 <link linkend='yocto-project-repositories'>source repository</link>.
4576 You can also find examples in
4577 <filename>meta/classes/kernel.bbclass</filename>.
4578 </para>
4579
4580 <para>
4581 Following is a reference that shows
4582 <filename>do_split_packages</filename> mandatory and
4583 optional arguments:
4584 <literallayout class='monospaced'>
4585 Mandatory arguments
4586
4587 root
4588 The path in which to search
4589 file_regex
4590 Regular expression to match searched files.
4591 Use parentheses () to mark the part of this
4592 expression that should be used to derive the
4593 module name (to be substituted where %s is
4594 used in other function arguments as noted below)
4595 output_pattern
4596 Pattern to use for the package names. Must
4597 include %s.
4598 description
4599 Description to set for each package. Must
4600 include %s.
4601
4602 Optional arguments
4603
4604 postinst
4605 Postinstall script to use for all packages
4606 (as a string)
4607 recursive
4608 True to perform a recursive search - default
4609 False
4610 hook
4611 A hook function to be called for every match.
4612 The function will be called with the following
4613 arguments (in the order listed):
4614
4615 f
4616 Full path to the file/directory match
4617 pkg
4618 The package name
4619 file_regex
4620 As above
4621 output_pattern
4622 As above
4623 modulename
4624 The module name derived using file_regex
4625
4626 extra_depends
4627 Extra runtime dependencies (RDEPENDS) to be
4628 set for all packages. The default value of None
4629 causes a dependency on the main package
4630 (${PN}) - if you do not want this, pass empty
4631 string '' for this parameter.
4632 aux_files_pattern
4633 Extra item(s) to be added to FILES for each
4634 package. Can be a single string item or a list
4635 of strings for multiple items. Must include %s.
4636 postrm
4637 postrm script to use for all packages (as a
4638 string)
4639 allow_dirs
4640 True to allow directories to be matched -
4641 default False
4642 prepend
4643 If True, prepend created packages to PACKAGES
4644 instead of the default False which appends them
4645 match_path
4646 match file_regex on the whole relative path to
4647 the root rather than just the file name
4648 aux_files_pattern_verbatim
4649 Extra item(s) to be added to FILES for each
4650 package, using the actual derived module name
4651 rather than converting it to something legal
4652 for a package name. Can be a single string item
4653 or a list of strings for multiple items. Must
4654 include %s.
4655 allow_links
4656 True to allow symlinks to be matched - default
4657 False
4658 summary
4659 Summary to set for each package. Must include %s;
4660 defaults to description if not set.
4661 </literallayout>
4662 </para>
4663 </section>
4664
4665 <section id='satisfying-dependencies'>
4666 <title>Satisfying Dependencies</title>
4667
4668 <para>
4669 The second part for handling optional module packaging
4670 is to ensure that any dependencies on optional modules
4671 from other recipes are satisfied by your recipe.
4672 You can be sure these dependencies are satisfied by
4673 using the
4674 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
4675 Here is an example that continues with the
4676 <filename>lighttpd</filename> recipe shown earlier:
4677 <literallayout class='monospaced'>
4678 PACKAGES_DYNAMIC = "lighttpd-module-.*"
4679 </literallayout>
4680 The name specified in the regular expression can of
4681 course be anything.
4682 In this example, it is <filename>lighttpd-module-</filename>
4683 and is specified as the prefix to ensure that any
4684 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
4685 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
4686 on a package name starting with the prefix are satisfied
4687 during build time.
4688 If you are using <filename>do_split_packages</filename>
4689 as described in the previous section, the value you put in
4690 <filename>PACKAGES_DYNAMIC</filename> should correspond to
4691 the name pattern specified in the call to
4692 <filename>do_split_packages</filename>.
4693 </para>
4694 </section>
4695 </section>
4696
4697 <section id='using-runtime-package-management'>
4698 <title>Using Runtime Package Management</title>
4699
4700 <para>
4701 During a build, BitBake always transforms a recipe into one or
4702 more packages.
4703 For example, BitBake takes the <filename>bash</filename> recipe
4704 and currently produces the <filename>bash-dbg</filename>,
4705 <filename>bash-staticdev</filename>,
4706 <filename>bash-dev</filename>, <filename>bash-doc</filename>,
4707 <filename>bash-locale</filename>, and
4708 <filename>bash</filename> packages.
4709 Not all generated packages are included in an image.
4710 </para>
4711
4712 <para>
4713 In several situations, you might need to update, add, remove,
4714 or query the packages on a target device at runtime
4715 (i.e. without having to generate a new image).
4716 Examples of such situations include:
4717 <itemizedlist>
4718 <listitem><para>
4719 You want to provide in-the-field updates to deployed
4720 devices (e.g. security updates).
4721 </para></listitem>
4722 <listitem><para>
4723 You want to have a fast turn-around development cycle
4724 for one or more applications that run on your device.
4725 </para></listitem>
4726 <listitem><para>
4727 You want to temporarily install the "debug" packages
4728 of various applications on your device so that
4729 debugging can be greatly improved by allowing
4730 access to symbols and source debugging.
4731 </para></listitem>
4732 <listitem><para>
4733 You want to deploy a more minimal package selection of
4734 your device but allow in-the-field updates to add a
4735 larger selection for customization.
4736 </para></listitem>
4737 </itemizedlist>
4738 </para>
4739
4740 <para>
4741 In all these situations, you have something similar to a more
4742 traditional Linux distribution in that in-field devices
4743 are able to receive pre-compiled packages from a server for
4744 installation or update.
4745 Being able to install these packages on a running,
4746 in-field device is what is termed "runtime package
4747 management".
4748 </para>
4749
4750 <para>
4751 In order to use runtime package management, you
4752 need a host/server machine that serves up the pre-compiled
4753 packages plus the required metadata.
4754 You also need package manipulation tools on the target.
4755 The build machine is a likely candidate to act as the server.
4756 However, that machine does not necessarily have to be the
4757 package server.
4758 The build machine could push its artifacts to another machine
4759 that acts as the server (e.g. Internet-facing).
4760 </para>
4761
4762 <para>
4763 A simple build that targets just one device produces
4764 more than one package database.
4765 In other words, the packages produced by a build are separated
4766 out into a couple of different package groupings based on
4767 criteria such as the target's CPU architecture, the target
4768 board, or the C library used on the target.
4769 For example, a build targeting the <filename>qemuarm</filename>
4770 device produces the following three package databases:
4771 <filename>all</filename>, <filename>armv5te</filename>, and
4772 <filename>qemuarm</filename>.
4773 If you wanted your <filename>qemuarm</filename> device to be
4774 aware of all the packages that were available to it,
4775 you would need to point it to each of these databases
4776 individually.
4777 In a similar way, a traditional Linux distribution usually is
4778 configured to be aware of a number of software repositories
4779 from which it retrieves packages.
4780 </para>
4781
4782 <para>
4783 Using runtime package management is completely optional and
4784 not required for a successful build or deployment in any
4785 way.
4786 But if you want to make use of runtime package management,
4787 you need to do a couple things above and beyond the basics.
4788 The remainder of this section describes what you need to do.
4789 </para>
4790
4791 <section id='runtime-package-management-build'>
4792 <title>Build Considerations</title>
4793
4794 <para>
4795 This section describes build considerations that you need
4796 to be aware of in order to provide support for runtime
4797 package management.
4798 </para>
4799
4800 <para>
4801 When BitBake generates packages it needs to know
4802 what format or formats to use.
4803 In your configuration, you use the
4804 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
4805 variable to specify the format.
4806 <note>
4807 You can choose to have more than one format but you must
4808 provide at least one.
4809 </note>
4810 </para>
4811
4812 <para>
4813 If you would like your image to start off with a basic
4814 package database of the packages in your current build
4815 as well as have the relevant tools available on the
4816 target for runtime package management, you can include
4817 "package-management" in the
4818 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
4819 variable.
4820 Including "package-management" in this
4821 configuration variable ensures that when the image
4822 is assembled for your target, the image includes
4823 the currently-known package databases as well as
4824 the target-specific tools required for runtime
4825 package management to be performed on the target.
4826 However, this is not strictly necessary.
4827 You could start your image off without any databases
4828 but only include the required on-target package
4829 tool(s).
4830 As an example, you could include "opkg" in your
4831 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
4832 variable if you are using the IPK package format.
4833 You can then initialize your target's package database(s)
4834 later once your image is up and running.
4835 </para>
4836
4837 <para>
4838 Whenever you perform any sort of build step that can
4839 potentially generate a package or modify an existing
4840 package, it is always a good idea to re-generate the
4841 package index with:
4842 <literallayout class='monospaced'>
4843 $ bitbake package-index
4844 </literallayout>
4845 Realize that it is not sufficient to simply do the
4846 following:
4847 <literallayout class='monospaced'>
4848 $ bitbake &lt;some-package&gt; package-index
4849 </literallayout>
4850 This is because BitBake does not properly schedule the
4851 <filename>package-index</filename> target fully after any
4852 other target has completed.
4853 Thus, be sure to run the package update step separately.
4854 </para>
4855
4856 <para>
4857 As described below in the
4858 "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
4859 section, if you are using IPK as your package format, you
4860 can make use of the
4861 <filename>distro-feed-configs</filename> recipe provided
4862 by <filename>meta-oe</filename> in order to configure your
4863 target to use your IPK databases.
4864 </para>
4865
4866 <para>
4867 When your build is complete, your packages reside in the
4868 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
4869 directory.
4870 For example, if <filename>${TMPDIR}</filename>
4871 is <filename>tmp</filename> and your selected package type
4872 is IPK, then your IPK packages are available in
4873 <filename>tmp/deploy/ipk</filename>.
4874 </para>
4875 </section>
4876
4877 <section id='runtime-package-management-server'>
4878 <title>Host or Server Machine Setup</title>
4879
4880 <para>
4881 Typically, packages are served from a server using
4882 HTTP.
4883 However, other protocols are possible.
4884 If you want to use HTTP, then setup and configure a
4885 web server, such as Apache 2 or lighttpd, on the machine
4886 serving the packages.
4887 </para>
4888
4889 <para>
4890 As previously mentioned, the build machine can act as the
4891 package server.
4892 In the following sections that describe server machine
4893 setups, the build machine is assumed to also be the server.
4894 </para>
4895
4896 <section id='package-server-apache'>
4897 <title>Serving Packages via Apache 2</title>
4898
4899 <para>
4900 This example assumes you are using the Apache 2
4901 server:
4902 <orderedlist>
4903 <listitem><para>
4904 Add the directory to your Apache
4905 configuration, which you can find at
4906 <filename>/etc/httpd/conf/httpd.conf</filename>.
4907 Use commands similar to these on the
4908 development system.
4909 These example commands assume a top-level
4910 <link linkend='source-directory'>Source Directory</link>
4911 named <filename>poky</filename> in your home
4912 directory.
4913 The example also assumes an RPM package type.
4914 If you are using a different package type, such
4915 as IPK, use "ipk" in the pathnames:
4916 <literallayout class='monospaced'>
4917 &lt;VirtualHost *:80&gt;
4918 ....
4919 Alias /rpm ~/poky/build/tmp/deploy/rpm
4920 &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
4921 Options +Indexes
4922 &lt;/Directory&gt;
4923 &lt;/VirtualHost&gt;
4924 </literallayout></para></listitem>
4925 <listitem><para>
4926 Reload the Apache configuration as described
4927 in this step.
4928 For all commands, be sure you have root
4929 privileges.
4930 </para>
4931
4932 <para>
4933 If your development system is using Fedora or
4934 CentOS, use the following:
4935 <literallayout class='monospaced'>
4936 # service httpd reload
4937 </literallayout>
4938 For Ubuntu and Debian, use the following:
4939 <literallayout class='monospaced'>
4940 # /etc/init.d/apache2 reload
4941 </literallayout>
4942 For OpenSUSE, use the following:
4943 <literallayout class='monospaced'>
4944 # /etc/init.d/apache2 reload
4945 </literallayout></para></listitem>
4946 <listitem><para>
4947 If you are using Security-Enhanced Linux
4948 (SELinux), you need to label the files as
4949 being accessible through Apache.
4950 Use the following command from the development
4951 host.
4952 This example assumes RPM package types:
4953 <literallayout class='monospaced'>
4954 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
4955 </literallayout></para></listitem>
4956 </orderedlist>
4957 </para>
4958 </section>
4959
4960 <section id='package-server-lighttpd'>
4961 <title>Serving Packages via lighttpd</title>
4962
4963 <para>
4964 If you are using lighttpd, all you need
4965 to do is to provide a link from your
4966 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
4967 directory to lighttpd's document-root.
4968 You can determine the specifics of your lighttpd
4969 installation by looking through its configuration file,
4970 which is usually found at:
4971 <filename>/etc/lighttpd/lighttpd.conf</filename>.
4972 </para>
4973
4974 <para>
4975 For example, if you are using IPK, lighttpd's
4976 document-root is set to
4977 <filename>/var/www/lighttpd</filename>, and you had
4978 packages for a target named "BOARD",
4979 then you might create a link from your build location
4980 to lighttpd's document-root as follows:
4981 <literallayout class='monospaced'>
4982 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
4983 </literallayout>
4984 </para>
4985
4986 <para>
4987 At this point, you need to start the lighttpd server.
4988 The method used to start the server varies by
4989 distribution.
4990 However, one basic method that starts it by hand is:
4991 <literallayout class='monospaced'>
4992 # lighttpd -f /etc/lighttpd/lighttpd.conf
4993 </literallayout>
4994 </para>
4995 </section>
4996 </section>
4997
4998 <section id='runtime-package-management-target'>
4999 <title>Target Setup</title>
5000
5001 <para>
5002 Setting up the target differs depending on the
5003 package management system.
5004 This section provides information for RPM and IPK.
5005 </para>
5006
5007 <section id='runtime-package-management-target-rpm'>
5008 <title>Using RPM</title>
5009
5010 <para>
5011 The application for performing runtime package
5012 management of RPM packages on the target is called
5013 <filename>smart</filename>.
5014 </para>
5015
5016 <para>
5017 On the target machine, you need to inform
5018 <filename>smart</filename> of every package database
5019 you want to use.
5020 As an example, suppose your target device can use the
5021 following three package databases from a server named
5022 <filename>server.name</filename>:
5023 <filename>all</filename>, <filename>i586</filename>,
5024 and <filename>qemux86</filename>.
5025 Given this example, issue the following commands on the
5026 target:
5027 <literallayout class='monospaced'>
5028 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
5029 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
5030 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
5031 </literallayout>
5032 Also from the target machine, fetch the repository
5033 information using this command:
5034 <literallayout class='monospaced'>
5035 # smart update
5036 </literallayout>
5037 You can now use the <filename>smart query</filename>
5038 and <filename>smart install</filename> commands to
5039 find and install packages from the repositories.
5040 </para>
5041 </section>
5042
5043 <section id='runtime-package-management-target-ipk'>
5044 <title>Using IPK</title>
5045
5046 <para>
5047 The application for performing runtime package
5048 management of IPK packages on the target is called
5049 <filename>opkg</filename>.
5050 </para>
5051
5052 <para>
5053 In order to inform <filename>opkg</filename> of the
5054 package databases you want to use, simply create one
5055 or more <filename>*.conf</filename> files in the
5056 <filename>/etc/opkg</filename> directory on the target.
5057 The <filename>opkg</filename> application uses them
5058 to find its available package databases.
5059 As an example, suppose you configured your HTTP server
5060 on your machine named
5061 <filename>www.mysite.com</filename> to serve files
5062 from a <filename>BOARD-dir</filename> directory under
5063 its document-root.
5064 In this case, you might create a configuration
5065 file on the target called
5066 <filename>/etc/opkg/base-feeds.conf</filename> that
5067 contains:
5068 <literallayout class='monospaced'>
5069 src/gz all http://www.mysite.com/BOARD-dir/all
5070 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
5071 src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
5072 </literallayout>
5073 </para>
5074
5075 <para>
5076 As a way of making it easier to generate and make
5077 these IPK configuration files available on your
5078 target, simply define
5079 <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
5080 to point to your server and the location within the
5081 document-root which contains the databases.
5082 For example: if you are serving your packages over
5083 HTTP, your server's IP address is 192.168.7.1, and
5084 your databases are located in a directory called
5085 <filename>BOARD-dir</filename> underneath your HTTP
5086 server's document-root, you need to set
5087 <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
5088 <filename>http://192.168.7.1/BOARD-dir</filename> and
5089 a set of configuration files will be generated for you
5090 in your target to work with this feed.
5091 </para>
5092
5093 <para>
5094 On the target machine, fetch (or refresh) the
5095 repository information using this command:
5096 <literallayout class='monospaced'>
5097 # opkg update
5098 </literallayout>
5099 You can now use the <filename>opkg list</filename> and
5100 <filename>opkg install</filename> commands to find and
5101 install packages from the repositories.
5102 </para>
5103 </section>
5104 </section>
5105 </section>
5106
5107 <section id='testing-packages-with-ptest'>
5108 <title>Testing Packages With ptest</title>
5109
5110 <para>
5111 A Package Test (ptest) runs tests against packages built
5112 by the OpenEmbedded build system on the target machine.
5113 A ptest contains at least two items: the actual test, and
5114 a shell script (<filename>run-ptest</filename>) that starts
5115 the test.
5116 The shell script that starts the test must not contain
5117 the actual test, the script only starts it.
5118 On the other hand, the test can be anything from a simple
5119 shell script that runs a binary and checks the output to
5120 an elaborate system of test binaries and data files.
5121 </para>
5122
5123 <para>
5124 The test generates output in the format used by
5125 Automake:
5126 <literallayout class='monospaced'>
5127 &lt;result&gt;: &lt;testname&gt;
5128 </literallayout>
5129 where the result can be <filename>PASS</filename>,
5130 <filename>FAIL</filename>, or <filename>SKIP</filename>,
5131 and the testname can be any identifying string.
5132 </para>
5133
5134 <note>
5135 A recipe is "ptest-enabled" if it inherits the
5136 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5137 class.
5138 </note>
5139
5140 <section id='adding-ptest-to-your-build'>
5141 <title>Adding ptest to Your Build</title>
5142
5143 <para>
5144 To add package testing to your build, add the
5145 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5146 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
5147 variables to your <filename>local.conf</filename> file,
5148 which is found in the
5149 <link linkend='build-directory'>Build Directory</link>:
5150 <literallayout class='monospaced'>
5151 DISTRO_FEATURES_append = " ptest"
5152 EXTRA_IMAGE_FEATURES += "ptest-pkgs"
5153 </literallayout>
5154 Once your build is complete, the ptest files are installed
5155 into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
5156 directory within the image, where
5157 <filename>&lt;package&gt;</filename> is the name of the
5158 package.
5159 </para>
5160 </section>
5161
5162 <section id='running-ptest'>
5163 <title>Running ptest</title>
5164
5165 <para>
5166 The <filename>ptest-runner</filename> package installs a
5167 shell script that loops through all installed ptest test
5168 suites and runs them in sequence.
5169 Consequently, you might want to add this package to
5170 your image.
5171 </para>
5172 </section>
5173
5174 <section id='getting-your-package-ready'>
5175 <title>Getting Your Package Ready</title>
5176
5177 <para>
5178 In order to enable a recipe to run installed ptests
5179 on target hardware,
5180 you need to prepare the recipes that build the packages
5181 you want to test.
5182 Here is what you have to do for each recipe:
5183 <itemizedlist>
5184 <listitem><para><emphasis>Be sure the recipe
5185 inherits the
5186 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink>
5187 class:</emphasis>
5188 Include the following line in each recipe:
5189 <literallayout class='monospaced'>
5190 inherit ptest
5191 </literallayout>
5192 </para></listitem>
5193 <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
5194 This script starts your test.
5195 Locate the script where you will refer to it
5196 using
5197 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
5198 Here is an example that starts a test for
5199 <filename>dbus</filename>:
5200 <literallayout class='monospaced'>
5201 #!/bin/sh
5202 cd test
5203 make -k runtest-TESTS
5204 </literallayout>
5205 </para></listitem>
5206 <listitem><para><emphasis>Ensure dependencies are
5207 met:</emphasis>
5208 If the test adds build or runtime dependencies
5209 that normally do not exist for the package
5210 (such as requiring "make" to run the test suite),
5211 use the
5212 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
5213 and
5214 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
5215 variables in your recipe in order for the package
5216 to meet the dependencies.
5217 Here is an example where the package has a runtime
5218 dependency on "make":
5219 <literallayout class='monospaced'>
5220 RDEPENDS_${PN}-ptest += "make"
5221 </literallayout>
5222 </para></listitem>
5223 <listitem><para><emphasis>Add a function to build the
5224 test suite:</emphasis>
5225 Not many packages support cross-compilation of
5226 their test suites.
5227 Consequently, you usually need to add a
5228 cross-compilation function to the package.
5229 </para>
5230 <para>Many packages based on Automake compile and
5231 run the test suite by using a single command
5232 such as <filename>make check</filename>.
5233 However, the native <filename>make check</filename>
5234 builds and runs on the same computer, while
5235 cross-compiling requires that the package is built
5236 on the host but executed on the target.
5237 The built version of Automake that ships with the
5238 Yocto Project includes a patch that separates
5239 building and execution.
5240 Consequently, packages that use the unaltered,
5241 patched version of <filename>make check</filename>
5242 automatically cross-compiles.</para>
5243 <para>However, you still must add a
5244 <filename>do_compile_ptest</filename> function to
5245 build the test suite.
5246 Add a function similar to the following to your
5247 recipe:
5248 <literallayout class='monospaced'>
5249 do_compile_ptest() {
5250 oe_runmake buildtest-TESTS
5251 }
5252 </literallayout>
5253 </para></listitem>
5254 <listitem><para><emphasis>Ensure special configurations
5255 are set:</emphasis>
5256 If the package requires special configurations
5257 prior to compiling the test code, you must
5258 insert a <filename>do_configure_ptest</filename>
5259 function into the recipe.
5260 </para></listitem>
5261 <listitem><para><emphasis>Install the test
5262 suite:</emphasis>
5263 The <filename>ptest</filename> class
5264 automatically copies the file
5265 <filename>run-ptest</filename> to the target and
5266 then runs make <filename>install-ptest</filename>
5267 to run the tests.
5268 If this is not enough, you need to create a
5269 <filename>do_install_ptest</filename> function and
5270 make sure it gets called after the
5271 "make install-ptest" completes.
5272 </para></listitem>
5273 </itemizedlist>
5274 </para>
5275 </section>
5276 </section>
5277 </section>
5278
5279 <section id="building-software-from-an-external-source">
5280 <title>Building Software from an External Source</title>
5281
5282 <para>
5283 By default, the OpenEmbedded build system uses the
5284 <link linkend='build-directory'>Build Directory</link> to
5285 build source code.
5286 The build process involves fetching the source files, unpacking
5287 them, and then patching them if necessary before the build takes
5288 place.
5289 </para>
5290
5291 <para>
5292 Situations exist where you might want to build software from source
5293 files that are external to and thus outside of the
5294 OpenEmbedded build system.
5295 For example, suppose you have a project that includes a new BSP with
5296 a heavily customized kernel.
5297 And, you want to minimize exposing the build system to the
5298 development team so that they can focus on their project and
5299 maintain everyone's workflow as much as possible.
5300 In this case, you want a kernel source directory on the development
5301 machine where the development occurs.
5302 You want the recipe's
5303 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
5304 variable to point to the external directory and use it as is, not
5305 copy it.
5306 </para>
5307
5308 <para>
5309 To build from software that comes from an external source, all you
5310 need to do is inherit the
5311 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
5312 class and then set the
5313 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
5314 variable to point to your external source code.
5315 Here are the statements to put in your
5316 <filename>local.conf</filename> file:
5317 <literallayout class='monospaced'>
5318 INHERIT += "externalsrc"
5319 EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
5320 </literallayout>
5321 </para>
5322
5323 <para>
5324 By default, <filename>externalsrc.bbclass</filename> builds
5325 the source code in a directory separate from the external source
5326 directory as specified by
5327 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
5328 If you need to have the source built in the same directory in
5329 which it resides, or some other nominated directory, you can set
5330 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
5331 to point to that directory:
5332 <literallayout class='monospaced'>
5333 EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
5334 </literallayout>
5335 </para>
5336 </section>
5337
5338 <section id="selecting-an-initialization-manager">
5339 <title>Selecting an Initialization Manager</title>
5340
5341 <para>
5342 By default, the Yocto Project uses SysVinit as the initialization
5343 manager.
5344 However, support also exists for systemd,
5345 which is a full replacement for init with
5346 parallel starting of services, reduced shell overhead and other
5347 features that are used by many distributions.
5348 </para>
5349
5350 <para>
5351 If you want to use SysVinit, you do
5352 not have to do anything.
5353 But, if you want to use systemd, you must
5354 take some steps as described in the following sections.
5355 </para>
5356
5357 <section id='using-systemd-exclusively'>
5358 <title>Using systemd Exclusively</title>
5359
5360 <para>
5361 Set the these variables in your distribution configuration
5362 file as follows:
5363 <literallayout class='monospaced'>
5364 DISTRO_FEATURES_append = " systemd"
5365 VIRTUAL-RUNTIME_init_manager = "systemd"
5366 </literallayout>
5367 You can also prevent the SysVinit
5368 distribution feature from
5369 being automatically enabled as follows:
5370 <literallayout class='monospaced'>
5371 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
5372 </literallayout>
5373 Doing so removes any redundant SysVinit scripts.
5374 </para>
5375
5376 <para>
5377 To remove initscripts from your image altogether,
5378 set this variable also:
5379 <literallayout class='monospaced'>
5380 VIRTUAL-RUNTIME_initscripts = ""
5381 </literallayout>
5382 </para>
5383
5384 <para>
5385 For information on the backfill variable, see
5386 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>.
5387 </para>
5388 </section>
5389
5390 <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
5391 <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
5392
5393 <para>
5394 Set the these variables in your distribution configuration
5395 file as follows:
5396 <literallayout class='monospaced'>
5397 DISTRO_FEATURES_append = " systemd"
5398 VIRTUAL-RUNTIME_init_manager = "systemd"
5399 </literallayout>
5400 Doing so causes your main image to use the
5401 <filename>packagegroup-core-boot.bb</filename> recipe and
5402 systemd.
5403 The rescue/minimal image cannot use this package group.
5404 However, it can install SysVinit
5405 and the appropriate packages will have support for both
5406 systemd and SysVinit.
5407 </para>
5408 </section>
5409 </section>
5410
5411 <section id="platdev-appdev-srcrev">
5412 <title>Using an External SCM</title>
5413
5414 <para>
5415 If you're working on a recipe that pulls from an external Source
5416 Code Manager (SCM), it is possible to have the OpenEmbedded build
5417 system notice new recipe changes added to the SCM and then build
5418 the resulting packages that depend on the new recipes by using
5419 the latest versions.
5420 This only works for SCMs from which it is possible to get a
5421 sensible revision number for changes.
5422 Currently, you can do this with Apache Subversion (SVN), Git, and
5423 Bazaar (BZR) repositories.
5424 </para>
5425
5426 <para>
5427 To enable this behavior, the
5428 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
5429 of the recipe needs to reference
5430 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
5431 Here is an example:
5432 <literallayout class='monospaced'>
5433 PV = "1.2.3+git${SRCPV}
5434 </literallayout>
5435 Then, you can add the following to your
5436 <filename>local.conf</filename>:
5437 <literallayout class='monospaced'>
5438 SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
5439 </literallayout>
5440 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
5441 is the name of the recipe for which you want to enable automatic source
5442 revision updating.
5443 </para>
5444
5445 <para>
5446 If you do not want to update your local configuration file, you can
5447 add the following directly to the recipe to finish enabling
5448 the feature:
5449 <literallayout class='monospaced'>
5450 SRCREV = "${AUTOREV}"
5451 </literallayout>
5452 </para>
5453
5454 <para>
5455 The Yocto Project provides a distribution named
5456 <filename>poky-bleeding</filename>, whose configuration
5457 file contains the line:
5458 <literallayout class='monospaced'>
5459 require conf/distro/include/poky-floating-revisions.inc
5460 </literallayout>
5461 This line pulls in the listed include file that contains
5462 numerous lines of exactly that form:
5463 <literallayout class='monospaced'>
5464 SRCREV_pn-gconf-dbus ?= "${AUTOREV}"
5465 SRCREV_pn-matchbox-common ?= "${AUTOREV}"
5466 SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}"
5467 SRCREV_pn-matchbox-desktop ?= "${AUTOREV}"
5468 SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}"
5469 SRCREV_pn-matchbox-panel ?= "${AUTOREV}"
5470 SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}"
5471 SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}"
5472 SRCREV_pn-matchbox-terminal ?= "${AUTOREV}"
5473 SRCREV_pn-matchbox-wm ?= "${AUTOREV}"
5474 SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}"
5475 SRCREV_pn-settings-daemon ?= "${AUTOREV}"
5476 SRCREV_pn-screenshot ?= "${AUTOREV}"
5477 SRCREV_pn-libfakekey ?= "${AUTOREV}"
5478 SRCREV_pn-oprofileui ?= "${AUTOREV}"
5479 .
5480 .
5481 .
5482 </literallayout>
5483 These lines allow you to experiment with building a
5484 distribution that tracks the latest development source
5485 for numerous packages.
5486 <note><title>Caution</title>
5487 The <filename>poky-bleeding</filename> distribution
5488 is not tested on a regular basis.
5489 Keep this in mind if you use it.
5490 </note>
5491 </para>
5492 </section>
5493
5494 <section id='creating-a-read-only-root-filesystem'>
5495 <title>Creating a Read-Only Root Filesystem</title>
5496
5497 <para>
5498 Suppose, for security reasons, you need to disable
5499 your target device's root filesystem's write permissions
5500 (i.e. you need a read-only root filesystem).
5501 Or, perhaps you are running the device's operating system
5502 from a read-only storage device.
5503 For either case, you can customize your image for
5504 that behavior.
5505 </para>
5506
5507 <note>
5508 Supporting a read-only root filesystem requires that the system and
5509 applications do not try to write to the root filesystem.
5510 You must configure all parts of the target system to write
5511 elsewhere, or to gracefully fail in the event of attempting to
5512 write to the root filesystem.
5513 </note>
5514
5515 <section id='creating-the-root-filesystem'>
5516 <title>Creating the Root Filesystem</title>
5517
5518 <para>
5519 To create the read-only root filesystem, simply add the
5520 "read-only-rootfs" feature to your image.
5521 Using either of the following statements in your
5522 image recipe or from within the
5523 <filename>local.conf</filename> file found in the
5524 <link linkend='build-directory'>Build Directory</link>
5525 causes the build system to create a read-only root filesystem:
5526 <literallayout class='monospaced'>
5527 IMAGE_FEATURES = "read-only-rootfs"
5528 </literallayout>
5529 or
5530 <literallayout class='monospaced'>
5531 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
5532 </literallayout>
5533 </para>
5534
5535 <para>
5536 For more information on how to use these variables, see the
5537 "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
5538 section.
5539 For information on the variables, see
5540 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5541 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
5542 </para>
5543 </section>
5544
5545 <section id='post-installation-scripts'>
5546 <title>Post-Installation Scripts</title>
5547
5548 <para>
5549 It is very important that you make sure all
5550 post-Installation (<filename>pkg_postinst</filename>) scripts
5551 for packages that are installed into the image can be run
5552 at the time when the root filesystem is created during the
5553 build on the host system.
5554 These scripts cannot attempt to run during first-boot on the
5555 target device.
5556 With the "read-only-rootfs" feature enabled,
5557 the build system checks during root filesystem creation to make
5558 sure all post-installation scripts succeed.
5559 If any of these scripts still need to be run after the root
5560 filesystem is created, the build immediately fails.
5561 These build-time checks ensure that the build fails
5562 rather than the target device fails later during its
5563 initial boot operation.
5564 </para>
5565
5566 <para>
5567 Most of the common post-installation scripts generated by the
5568 build system for the out-of-the-box Yocto Project are engineered
5569 so that they can run during root filesystem creation
5570 (e.g. post-installation scripts for caching fonts).
5571 However, if you create and add custom scripts, you need
5572 to be sure they can be run during this file system creation.
5573 </para>
5574
5575 <para>
5576 Here are some common problems that prevent
5577 post-installation scripts from running during root filesystem
5578 creation:
5579 <itemizedlist>
5580 <listitem><para>
5581 <emphasis>Not using $D in front of absolute
5582 paths:</emphasis>
5583 The build system defines
5584 <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
5585 when the root filesystem is created.
5586 Furthermore, <filename>$D</filename> is blank when the
5587 script is run on the target device.
5588 This implies two purposes for <filename>$D</filename>:
5589 ensuring paths are valid in both the host and target
5590 environments, and checking to determine which
5591 environment is being used as a method for taking
5592 appropriate actions.
5593 </para></listitem>
5594 <listitem><para>
5595 <emphasis>Attempting to run processes that are
5596 specific to or dependent on the target
5597 architecture:</emphasis>
5598 You can work around these attempts by using native
5599 tools to accomplish the same tasks, or
5600 by alternatively running the processes under QEMU,
5601 which has the <filename>qemu_run_binary</filename>
5602 function.
5603 For more information, see the
5604 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink>
5605 class.</para></listitem>
5606 </itemizedlist>
5607 </para>
5608 </section>
5609
5610 <section id='areas-with-write-access'>
5611 <title>Areas With Write Access</title>
5612
5613 <para>
5614 With the "read-only-rootfs" feature enabled,
5615 any attempt by the target to write to the root filesystem at
5616 runtime fails.
5617 Consequently, you must make sure that you configure processes
5618 and applications that attempt these types of writes do so
5619 to directories with write access (e.g.
5620 <filename>/tmp</filename> or <filename>/var/run</filename>).
5621 </para>
5622 </section>
5623 </section>
5624
5625 <section id="performing-automated-runtime-testing">
5626 <title>Performing Automated Runtime Testing</title>
5627
5628 <para>
5629 The OpenEmbedded build system makes available a series of automated
5630 tests for images to verify runtime functionality.
5631 You can run these tests on either QEMU or actual target hardware.
5632 Tests are written in Python making use of the
5633 <filename>unittest</filename> module, and the majority of them
5634 run commands on the target system over SSH.
5635 This section describes how you set up the environment to use these
5636 tests, run available tests, and write and add your own tests.
5637 </para>
5638
5639 <section id='enabling-tests'>
5640 <title>Enabling Tests</title>
5641
5642 <para>
5643 Depending on whether you are planning on running tests using
5644 QEMU or on running them on the hardware, you have to take
5645 different steps to enable the tests.
5646 See the following subsections for information on how to
5647 enable both types of tests.
5648 </para>
5649
5650 <section id='qemu-image-enabling-tests'>
5651 <title>Enabling Runtime Tests on QEMU</title>
5652
5653 <para>
5654 In order to run tests, you need to do the following:
5655 <itemizedlist>
5656 <listitem><para><emphasis>Set up to avoid interaction
5657 with <filename>sudo</filename> for networking:</emphasis>
5658 To accomplish this, you must do one of the
5659 following:
5660 <itemizedlist>
5661 <listitem><para>Add
5662 <filename>NOPASSWD</filename> for your user
5663 in <filename>/etc/sudoers</filename> either for
5664 ALL commands or just for
5665 <filename>runqemu-ifup</filename>.
5666 You must provide the full path as that can
5667 change if you are using multiple clones of the
5668 source repository.
5669 <note>
5670 On some distributions, you also need to
5671 comment out "Defaults requiretty" in
5672 <filename>/etc/sudoers</filename>.
5673 </note></para></listitem>
5674 <listitem><para>Manually configure a tap interface
5675 for your system.</para></listitem>
5676 <listitem><para>Run as root the script in
5677 <filename>scripts/runqemu-gen-tapdevs</filename>,
5678 which should generate a list of tap devices.
5679 This is the option typically chosen for
5680 Autobuilder-type environments.
5681 </para></listitem>
5682 </itemizedlist></para></listitem>
5683 <listitem><para><emphasis>Set the
5684 <filename>DISPLAY</filename> variable:</emphasis>
5685 You need to set this variable so that you have an X
5686 server available (e.g. start
5687 <filename>vncserver</filename> for a headless machine).
5688 </para></listitem>
5689 <listitem><para><emphasis>Be sure your host's firewall
5690 accepts incoming connections from
5691 192.168.7.0/24:</emphasis>
5692 Some of the tests (in particular smart tests) start an
5693 HTTP server on a random high number port, which is
5694 used to serve files to the target.
5695 The smart module serves
5696 <filename>${DEPLOY_DIR}/rpm</filename> so it can run
5697 smart channel commands. That means your host's firewall
5698 must accept incoming connections from 192.168.7.0/24,
5699 which is the default IP range used for tap devices
5700 by <filename>runqemu</filename>.</para></listitem>
5701 </itemizedlist>
5702 </para>
5703
5704 <para>
5705 Once you start running the tests, the following happens:
5706 <itemizedlist>
5707 <listitem><para>A copy of the root filesystem is written
5708 to <filename>${WORKDIR}/testimage</filename>.
5709 </para></listitem>
5710 <listitem><para>The image is booted under QEMU using the
5711 standard <filename>runqemu</filename> script.
5712 </para></listitem>
5713 <listitem><para>A default timeout of 500 seconds occurs
5714 to allow for the boot process to reach the login prompt.
5715 You can change the timeout period by setting
5716 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
5717 in the <filename>local.conf</filename> file.
5718 </para></listitem>
5719 <listitem><para>Once the boot process is reached and the
5720 login prompt appears, the tests run.
5721 The full boot log is written to
5722 <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
5723 </para></listitem>
5724 <listitem><para>Each test module loads in the order found
5725 in <filename>TEST_SUITES</filename>.
5726 You can find the full output of the commands run over
5727 SSH in
5728 <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
5729 </para></listitem>
5730 <listitem><para>If no failures occur, the task running the
5731 tests ends successfully.
5732 You can find the output from the
5733 <filename>unittest</filename> in the task log at
5734 <filename>${WORKDIR}/temp/log.do_testimage</filename>.
5735 </para></listitem>
5736 </itemizedlist>
5737 </para>
5738 </section>
5739
5740 <section id='hardware-image-enabling-tests'>
5741 <title>Enabling Runtime Tests on Hardware</title>
5742
5743 <para>
5744 The OpenEmbedded build system can run tests on real
5745 hardware, and for certain devices it can also deploy
5746 the image to be tested onto the device beforehand.
5747 </para>
5748
5749 <para>
5750 For automated deployment, a "master image" is installed
5751 onto the hardware once as part of setup.
5752 Then, each time tests are to be run, the following
5753 occurs:
5754 <orderedlist>
5755 <listitem><para>The master image is booted into and
5756 used to write the image to be tested to
5757 a second partition.
5758 </para></listitem>
5759 <listitem><para>The device is then rebooted using an
5760 external script that you need to provide.
5761 </para></listitem>
5762 <listitem><para>The device boots into the image to be
5763 tested.
5764 </para></listitem>
5765 </orderedlist>
5766 </para>
5767
5768 <para>
5769 When running tests (independent of whether the image
5770 has been deployed automatically or not), the device is
5771 expected to be connected to a network on a
5772 pre-determined IP address.
5773 You can either use static IP addresses written into
5774 the image, or set the image to use DHCP and have your
5775 DHCP server on the test network assign a known IP address
5776 based on the MAC address of the device.
5777 </para>
5778
5779 <para>
5780 In order to run tests on hardware, you need to set
5781 <filename>TEST_TARGET</filename> to an appropriate value.
5782 For QEMU, you do not have to change anything, the default
5783 value is "QemuTarget".
5784 For running tests on hardware, two options exist:
5785 "SimpleRemoteTarget" and "GummibootTarget".
5786 <itemizedlist>
5787 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
5788 Choose "SimpleRemoteTarget" if you are going to
5789 run tests on a target system that is already
5790 running the image to be tested and is available
5791 on the network.
5792 You can use "SimpleRemoteTarget" in conjunction
5793 with either real hardware or an image running
5794 within a separately started QEMU or any
5795 other virtual machine manager.
5796 </para></listitem>
5797 <listitem><para><emphasis>"GummibootTarget":</emphasis>
5798 Choose "GummibootTarget" if your hardware is
5799 an EFI-based machine with
5800 <filename>gummiboot</filename> as bootloader and
5801 <filename>core-image-testmaster</filename>
5802 (or something similar) is installed.
5803 Also, your hardware under test must be in a
5804 DHCP-enabled network that gives it the same IP
5805 address for each reboot.</para>
5806 <para>If you choose "GummibootTarget", there are
5807 additional requirements and considerations.
5808 See the
5809 "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
5810 section, which follows, for more information.
5811 </para></listitem>
5812 </itemizedlist>
5813 </para>
5814 </section>
5815
5816 <section id='selecting-gummiboottarget'>
5817 <title>Selecting GummibootTarget</title>
5818
5819 <para>
5820 If you did not set <filename>TEST_TARGET</filename> to
5821 "GummibootTarget", then you do not need any information
5822 in this section.
5823 You can skip down to the
5824 "<link linkend='qemu-image-running-tests'>Running Tests</link>"
5825 section.
5826 </para>
5827
5828 <para>
5829 If you did set <filename>TEST_TARGET</filename> to
5830 "GummibootTarget", you also need to perform a one-time
5831 setup of your master image by doing the following:
5832 <orderedlist>
5833 <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis>
5834 Be sure that <filename>EFI_PROVIDER</filename>
5835 is as follows:
5836 <literallayout class='monospaced'>
5837 EFI_PROVIDER = "gummiboot"
5838 </literallayout>
5839 </para></listitem>
5840 <listitem><para><emphasis>Build the master image:</emphasis>
5841 Build the <filename>core-image-testmaster</filename>
5842 image.
5843 The <filename>core-image-testmaster</filename>
5844 recipe is provided as an example for a
5845 "master" image and you can customize the image
5846 recipe as you would any other recipe.
5847 </para>
5848 <para>Here are the image recipe requirements:
5849 <itemizedlist>
5850 <listitem><para>Inherits
5851 <filename>core-image</filename>
5852 so that kernel modules are installed.
5853 </para></listitem>
5854 <listitem><para>Installs normal linux utilities
5855 not busybox ones (e.g.
5856 <filename>bash</filename>,
5857 <filename>coreutils</filename>,
5858 <filename>tar</filename>,
5859 <filename>gzip</filename>, and
5860 <filename>kmod</filename>).
5861 </para></listitem>
5862 <listitem><para>Uses a custom
5863 initramfs image with a custom installer.
5864 A normal image that you can install usually
5865 creates a single rootfs partition.
5866 This image uses another installer that
5867 creates a specific partition layout.
5868 Not all Board Support Packages (BSPs)
5869 can use an installer.
5870 For such cases, you need to manually create
5871 the following partition layout on the
5872 target:
5873 <itemizedlist>
5874 <listitem><para>First partition mounted
5875 under <filename>/boot</filename>,
5876 labeled "boot".
5877 </para></listitem>
5878 <listitem><para>The main rootfs
5879 partition where this image gets
5880 installed, which is mounted under
5881 <filename>/</filename>.
5882 </para></listitem>
5883 <listitem><para>Another partition
5884 labeled "testrootfs" where test
5885 images get deployed.
5886 </para></listitem>
5887 </itemizedlist>
5888 </para></listitem>
5889 </itemizedlist>
5890 </para></listitem>
5891 <listitem><para><emphasis>Install image:</emphasis>
5892 Install the image that you just built on the target
5893 system.
5894 </para></listitem>
5895 </orderedlist>
5896 </para>
5897
5898 <para>
5899 The final thing you need to do when setting
5900 <filename>TEST_TARGET</filename> to "GummibootTarget" is
5901 to set up the test image:
5902 <orderedlist>
5903 <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis>
5904 Make sure you have the following statements in
5905 your <filename>local.conf</filename> file:
5906 <literallayout class='monospaced'>
5907 IMAGE_FSTYPES += "tar.gz"
5908 INHERIT += "testimage"
5909 TEST_TARGET = "GummibootTarget"
5910 TEST_TARGET_IP = "192.168.2.3"
5911 </literallayout>
5912 </para></listitem>
5913 <listitem><para><emphasis>Build your test image:</emphasis>
5914 Use BitBake to build the image:
5915 <literallayout class='monospaced'>
5916 $ bitbake core-image-sato
5917 </literallayout>
5918 </para></listitem>
5919 </orderedlist>
5920 </para>
5921
5922 <para>
5923 Here is some additional information regarding running
5924 "GummibootTarget" as your test target:
5925 <itemizedlist>
5926 <listitem><para>
5927 You can use
5928 <filename>TEST_POWERCONTROL_CMD</filename>
5929 together with
5930 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
5931 as a command that runs on the host and does power
5932 cycling.
5933 The test code passes one argument to that command:
5934 off, on or cycle (off then on).
5935 Here is an example that could appear in your
5936 <filename>local.conf</filename> file:
5937 <literallayout class='monospaced'>
5938 TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
5939 </literallayout>
5940 In this example, the expect script does the
5941 following:
5942 <literallayout class='monospaced'>
5943 ssh test@10.11.12.1 "pyctl nuc1 &lt;arg&gt;"
5944 </literallayout>
5945 It then runs a Python script that controls power
5946 for a label called <filename>nuc1</filename>.
5947 <note>
5948 You need to customize
5949 <filename>TEST_POWERCONTROL_CMD</filename>
5950 and
5951 <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
5952 for your own setup.
5953 The one requirement is that it accepts
5954 "on", "off", and "cycle" as the last argument.
5955 </note>
5956 </para></listitem>
5957 <listitem><para>
5958 When no command is defined, it connects to the
5959 device over SSH and uses the classic reboot command
5960 to reboot the device.
5961 Classic reboot is fine as long as the machine
5962 actually reboots (i.e. the SSH test has not
5963 failed).
5964 It is useful for scenarios where you have a simple
5965 setup, typically with a single board, and where
5966 some manual interaction is okay from time to time.
5967 </para></listitem>
5968 </itemizedlist>
5969 </para>
5970 </section>
5971 </section>
5972
5973 <section id="qemu-image-running-tests">
5974 <title>Running Tests</title>
5975
5976 <para>
5977 You can start the tests automatically or manually:
5978 <itemizedlist>
5979 <listitem><para><emphasis>Automatically running tests:</emphasis>
5980 To run the tests automatically after the
5981 OpenEmbedded build system successfully creates an image,
5982 first set the
5983 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
5984 variable to "1" in your <filename>local.conf</filename>
5985 file in the
5986 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
5987 <literallayout class='monospaced'>
5988 TEST_IMAGE = "1"
5989 </literallayout>
5990 Next, build your image.
5991 If the image successfully builds, the tests will be
5992 run:
5993 <literallayout class='monospaced'>
5994 bitbake core-image-sato
5995 </literallayout></para></listitem>
5996 <listitem><para><emphasis>Manually running tests:</emphasis>
5997 To manually run the tests, first globally inherit the
5998 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink>
5999 class by editing your <filename>local.conf</filename>
6000 file:
6001 <literallayout class='monospaced'>
6002 INHERIT += "testimage"
6003 </literallayout>
6004 Next, use BitBake to run the tests:
6005 <literallayout class='monospaced'>
6006 bitbake -c testimage &lt;image&gt;
6007 </literallayout></para></listitem>
6008 </itemizedlist>
6009 </para>
6010
6011 <para>
6012 All test files reside in
6013 <filename>meta/lib/oeqa/runtime</filename> in the
6014 <link linkend='source-directory'>Source Directory</link>.
6015 A test name maps directly to a Python module.
6016 Each test module may contain a number of individual tests.
6017 Tests are usually grouped together by the area
6018 tested (e.g tests for systemd reside in
6019 <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
6020 </para>
6021
6022 <para>
6023 You can add tests to any layer provided you place them in the
6024 proper area and you extend
6025 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6026 in the <filename>local.conf</filename> file as normal.
6027 Be sure that tests reside in
6028 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
6029 <note>
6030 Be sure that module names do not collide with module names
6031 used in the default set of test modules in
6032 <filename>meta/lib/oeqa/runtime</filename>.
6033 </note>
6034 </para>
6035
6036 <para>
6037 You can change the set of tests run by appending or overriding
6038 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
6039 variable in <filename>local.conf</filename>.
6040 Each name in <filename>TEST_SUITES</filename> represents a
6041 required test for the image.
6042 Test modules named within <filename>TEST_SUITES</filename>
6043 cannot be skipped even if a test is not suitable for an image
6044 (e.g. running the RPM tests on an image without
6045 <filename>rpm</filename>).
6046 Appending "auto" to <filename>TEST_SUITES</filename> causes the
6047 build system to try to run all tests that are suitable for the
6048 image (i.e. each test module may elect to skip itself).
6049 </para>
6050
6051 <para>
6052 The order you list tests in <filename>TEST_SUITES</filename>
6053 is important and influences test dependencies.
6054 Consequently, tests that depend on other tests should be added
6055 after the test on which they depend.
6056 For example, since the <filename>ssh</filename> test
6057 depends on the
6058 <filename>ping</filename> test, "ssh" needs to come after
6059 "ping" in the list.
6060 The test class provides no re-ordering or dependency handling.
6061 <note>
6062 Each module can have multiple classes with multiple test
6063 methods.
6064 And, Python <filename>unittest</filename> rules apply.
6065 </note>
6066 </para>
6067
6068 <para>
6069 Here are some things to keep in mind when running tests:
6070 <itemizedlist>
6071 <listitem><para>The default tests for the image are defined
6072 as:
6073 <literallayout class='monospaced'>
6074 DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
6075 </literallayout></para></listitem>
6076 <listitem><para>Add your own test to the list of the
6077 by using the following:
6078 <literallayout class='monospaced'>
6079 TEST_SUITES_append = " mytest"
6080 </literallayout></para></listitem>
6081 <listitem><para>Run a specific list of tests as follows:
6082 <literallayout class='monospaced'>
6083 TEST_SUITES = "test1 test2 test3"
6084 </literallayout>
6085 Remember, order is important.
6086 Be sure to place a test that is dependent on another test
6087 later in the order.</para></listitem>
6088 </itemizedlist>
6089 </para>
6090 </section>
6091
6092 <section id="exporting-tests">
6093 <title>Exporting Tests</title>
6094
6095 <para>
6096 You can export tests so that they can run independently of
6097 the build system.
6098 Exporting tests is required if you want to be able to hand
6099 the test execution off to a scheduler.
6100 You can only export tests that are defined in
6101 <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>.
6102 </para>
6103
6104 <para>
6105 If you image is already built, make sure the following are set
6106 in your <filename>local.conf</filename> file.
6107 Be sure to provide the IP address you need:
6108 <literallayout class='monospaced'>
6109 TEST_EXPORT_ONLY = "1"
6110 TEST_TARGET = "simpleremote"
6111 TEST_TARGET_IP = "192.168.7.2"
6112 TEST_SERVER_IP = "192.168.7.1"
6113 </literallayout>
6114 You can then export the tests with the following:
6115 <literallayout class='monospaced'>
6116 $ bitbake core-image-sato -c testimage
6117 </literallayout>
6118 Exporting the tests places them in the
6119 <link linkend='build-directory'>Build Directory</link> in
6120 <filename>tmp/testimage/core-image-sato</filename>, which
6121 is controlled by the
6122 <filename>TEST_EXPORT_DIR</filename> variable.
6123 </para>
6124
6125 <para>
6126 The exported data (i.e. <filename>testdata.json</filename>)
6127 contains paths to the Build Directory.
6128 Thus, the contents of the directory can be moved
6129 to another machine as long as you update some paths in the
6130 JSON.
6131 Usually you only care about the
6132 ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests
6133 are enabled).
6134 Consequently, running the tests on other machine
6135 means that you have to move the contents and call
6136 <filename>runexported</filename> with "--deploy-dir PATH:
6137 ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json
6138 runexported.py accepts other arguments as well, see --help.
6139 </para>
6140
6141 <para>
6142 You can now run the tests outside of the build environment:
6143 <literallayout class='monospaced'>
6144 $ cd tmp/testimage/core-image-sato
6145 $ ./runexported.py testdata.json
6146 </literallayout>
6147 <note>
6148 This "export" feature does not deploy or boot the target
6149 image.
6150 Your target (be it a Qemu or hardware one)
6151 has to already be up and running when you call
6152 <filename>runexported.py</filename>
6153 </note>
6154 </para>
6155 </section>
6156
6157 <section id="qemu-image-writing-new-tests">
6158 <title>Writing New Tests</title>
6159
6160 <para>
6161 As mentioned previously, all new test files need to be in the
6162 proper place for the build system to find them.
6163 New tests for additional functionality outside of the core
6164 should be added to the layer that adds the functionality, in
6165 <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
6166 long as
6167 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
6168 is extended in the layer's
6169 <filename>layer.conf</filename> file as normal).
6170 Just remember that filenames need to map directly to test
6171 (module) names and that you do not use module names that
6172 collide with existing core tests.
6173 </para>
6174
6175 <para>
6176 To create a new test, start by copying an existing module
6177 (e.g. <filename>syslog.py</filename> or
6178 <filename>gcc.py</filename> are good ones to use).
6179 Test modules can use code from
6180 <filename>meta/lib/oeqa/utils</filename>, which are helper
6181 classes.
6182 </para>
6183
6184 <note>
6185 Structure shell commands such that you rely on them and they
6186 return a single code for success.
6187 Be aware that sometimes you will need to parse the output.
6188 See the <filename>df.py</filename> and
6189 <filename>date.py</filename> modules for examples.
6190 </note>
6191
6192 <para>
6193 You will notice that all test classes inherit
6194 <filename>oeRuntimeTest</filename>, which is found in
6195 <filename>meta/lib/oetest.py</filename>.
6196 This base class offers some helper attributes, which are
6197 described in the following sections:
6198 </para>
6199
6200 <section id='qemu-image-writing-tests-class-methods'>
6201 <title>Class Methods</title>
6202
6203 <para>
6204 Class methods are as follows:
6205 <itemizedlist>
6206 <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
6207 Returns "True" if <filename>pkg</filename> is in the
6208 installed package list of the image, which is based
6209 on the manifest file that is generated during the
6210 <filename>do.rootfs</filename> task.
6211 </para></listitem>
6212 <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
6213 Returns "True" if the feature is in
6214 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
6215 or
6216 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
6217 </para></listitem>
6218 </itemizedlist>
6219 </para>
6220 </section>
6221
6222 <section id='qemu-image-writing-tests-class-attributes'>
6223 <title>Class Attributes</title>
6224
6225 <para>
6226 Class attributes are as follows:
6227 <itemizedlist>
6228 <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
6229 Equals "ps -ef" if <filename>procps</filename> is
6230 installed in the image.
6231 Otherwise, <filename>pscmd</filename> equals
6232 "ps" (busybox).
6233 </para></listitem>
6234 <listitem><para><emphasis><filename>tc</filename>:</emphasis>
6235 The called text context, which gives access to the
6236 following attributes:
6237 <itemizedlist>
6238 <listitem><para><emphasis><filename>d</filename>:</emphasis>
6239 The BitBake datastore, which allows you to
6240 use stuff such as
6241 <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
6242 </para></listitem>
6243 <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
6244 Used internally.
6245 The tests do not need these.
6246 </para></listitem>
6247 <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
6248 The absolute path to
6249 <filename>meta/lib/oeqa/runtime/files</filename>,
6250 which contains helper files for tests meant
6251 for copying on the target such as small
6252 files written in C for compilation.
6253 </para></listitem>
6254 <listitem><para><emphasis><filename>target</filename>:</emphasis>
6255 The target controller object used to deploy
6256 and start an image on a particular target
6257 (e.g. QemuTarget, SimpleRemote, and
6258 GummibootTarget).
6259 Tests usually use the following:
6260 <itemizedlist>
6261 <listitem><para><emphasis><filename>ip</filename>:</emphasis>
6262 The target's IP address.
6263 </para></listitem>
6264 <listitem><para><emphasis><filename>server_ip</filename>:</emphasis>
6265 The host's IP address, which is
6266 usually used by the "smart" test
6267 suite.
6268 </para></listitem>
6269 <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
6270 The single, most used method.
6271 This command is a wrapper for:
6272 <filename>ssh root@host "cmd"</filename>.
6273 The command returns a tuple:
6274 (status, output), which are what
6275 their names imply - the return code
6276 of 'cmd' and whatever output
6277 it produces.
6278 The optional timeout argument
6279 represents the number of seconds the
6280 test should wait for 'cmd' to
6281 return.
6282 If the argument is "None", the
6283 test uses the default instance's
6284 timeout period, which is 300
6285 seconds.
6286 If the argument is "0", the test
6287 runs until the command returns.
6288 </para></listitem>
6289 <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
6290 <filename>scp localpath root@ip:remotepath</filename>.
6291 </para></listitem>
6292 <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
6293 <filename>scp root@host:remotepath localpath</filename>.
6294 </para></listitem>
6295 </itemizedlist></para></listitem>
6296 </itemizedlist></para></listitem>
6297 </itemizedlist>
6298 </para>
6299 </section>
6300
6301 <section id='qemu-image-writing-tests-instance-attributes'>
6302 <title>Instance Attributes</title>
6303
6304 <para>
6305 A single instance attribute exists, which is
6306 <filename>target</filename>.
6307 The <filename>target</filename> instance attribute is
6308 identical to the class attribute of the same name, which
6309 is described in the previous section.
6310 This attribute exists as both an instance and class
6311 attribute so tests can use
6312 <filename>self.target.run(cmd)</filename> in instance
6313 methods instead of
6314 <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
6315 </para>
6316 </section>
6317 </section>
6318 </section>
6319
6320 <section id="platdev-gdb-remotedebug">
6321 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
6322
6323 <para>
6324 GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
6325 It also allows you to perform post-mortem style analysis of program crashes.
6326 GDB is available as a package within the Yocto Project and is
6327 installed in SDK images by default.
6328 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
6329 in the Yocto Project Reference Manual for a description of these images.
6330 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
6331 </para>
6332
6333 <tip>
6334 For best results, install DBG (<filename>-dbg</filename>) packages
6335 for the applications you are going to debug.
6336 Doing so makes extra debug symbols available that give you more
6337 meaningful output.
6338 </tip>
6339
6340 <para>
6341 Sometimes, due to memory or disk space constraints, it is not possible
6342 to use GDB directly on the remote target to debug applications.
6343 These constraints arise because GDB needs to load the debugging information and the
6344 binaries of the process being debugged.
6345 Additionally, GDB needs to perform many computations to locate information such as function
6346 names, variable names and values, stack traces and so forth - even before starting the
6347 debugging process.
6348 These extra computations place more load on the target system and can alter the
6349 characteristics of the program being debugged.
6350 </para>
6351
6352 <para>
6353 To help get past the previously mentioned constraints, you can use Gdbserver.
6354 Gdbserver runs on the remote target and does not load any debugging information
6355 from the debugged process.
6356 Instead, a GDB instance processes the debugging information that is run on a
6357 remote computer - the host GDB.
6358 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
6359 program, as well as read or write memory regions of that debugged program.
6360 All the debugging information loaded and processed as well
6361 as all the heavy debugging is done by the host GDB.
6362 Offloading these processes gives the Gdbserver running on the target a chance to remain
6363 small and fast.
6364 </para>
6365
6366 <para>
6367 Because the host GDB is responsible for loading the debugging information and
6368 for doing the necessary processing to make actual debugging happen, the
6369 user has to make sure the host can access the unstripped binaries complete
6370 with their debugging information and also be sure the target is compiled with no optimizations.
6371 The host GDB must also have local access to all the libraries used by the
6372 debugged program.
6373 Because Gdbserver does not need any local debugging information, the binaries on
6374 the remote target can remain stripped.
6375 However, the binaries must also be compiled without optimization
6376 so they match the host's binaries.
6377 </para>
6378
6379 <para>
6380 To remain consistent with GDB documentation and terminology, the binary being debugged
6381 on the remote target machine is referred to as the "inferior" binary.
6382 For documentation on GDB see the
6383 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
6384 </para>
6385
6386 <para>
6387 The remainder of this section describes the steps you need to take
6388 to debug using the GNU project debugger.
6389 </para>
6390
6391 <section id='platdev-gdb-remotedebug-setup'>
6392 <title>Set Up the Cross-Development Debugging Environment</title>
6393
6394 <para>
6395 Before you can initiate a remote debugging session, you need
6396 to be sure you have set up the cross-development environment,
6397 toolchain, and sysroot.
6398 The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
6399 chapter of the Yocto Project Application Developer's Guide
6400 describes this process.
6401 Be sure you have read that chapter and have set up
6402 your environment.
6403 </para>
6404 </section>
6405
6406 <section id="platdev-gdb-remotedebug-launch-gdbserver">
6407 <title>Launch Gdbserver on the Target</title>
6408
6409 <para>
6410 Make sure Gdbserver is installed on the target.
6411 If it is not, install the package
6412 <filename>gdbserver</filename>, which needs the
6413 <filename>libthread-db1</filename> package.
6414 </para>
6415
6416 <para>
6417 Here is an example that when entered from the host
6418 connects to the target and launches Gdbserver in order to
6419 "debug" a binary named <filename>helloworld</filename>:
6420 <literallayout class='monospaced'>
6421 $ gdbserver localhost:2345 /usr/bin/helloworld
6422 </literallayout>
6423 Gdbserver should now be listening on port 2345 for debugging
6424 commands coming from a remote GDB process that is running on
6425 the host computer.
6426 Communication between Gdbserver and the host GDB are done
6427 using TCP.
6428 To use other communication protocols, please refer to the
6429 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
6430 </para>
6431 </section>
6432
6433 <section id="platdev-gdb-remotedebug-launch-gdb">
6434 <title>Launch GDB on the Host Computer</title>
6435
6436 <para>
6437 Running GDB on the host computer takes a number of stages, which
6438 this section describes.
6439 </para>
6440
6441 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
6442 <title>Build the Cross-GDB Package</title>
6443 <para>
6444 A suitable GDB cross-binary is required that runs on your
6445 host computer but also knows about the the ABI of the
6446 remote target.
6447 You can get this binary from the
6448 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
6449 Here is an example where the toolchain has been installed
6450 in the default directory
6451 <filename>/opt/poky/&DISTRO;</filename>:
6452 <literallayout class='monospaced'>
6453 /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
6454 </literallayout>
6455 where <filename>arm</filename> is the target architecture
6456 and <filename>linux-gnueabi</filename> is the target ABI.
6457 </para>
6458
6459 <para>
6460 Alternatively, you can use BitBake to build the
6461 <filename>gdb-cross</filename> binary.
6462 Here is an example:
6463 <literallayout class='monospaced'>
6464 $ bitbake gdb-cross
6465 </literallayout>
6466 Once the binary is built, you can find it here:
6467 <literallayout class='monospaced'>
6468 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
6469 </literallayout>
6470 </para>
6471 </section>
6472
6473 <section id='create-the-gdb-initialization-file'>
6474 <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
6475
6476 <para>
6477 Aside from the GDB cross-binary, you also need a GDB
6478 initialization file in the same top directory in which
6479 your binary resides.
6480 When you start GDB on your host development system, GDB
6481 finds this initialization file and executes all the
6482 commands within.
6483 For information on the <filename>.gdbinit</filename>, see
6484 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
6485 which is maintained by
6486 <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
6487 </para>
6488
6489 <para>
6490 You need to add a statement in the
6491 <filename>.gdbinit</filename> file that points to your
6492 root filesystem.
6493 Here is an example that points to the root filesystem for
6494 an ARM-based target device:
6495 <literallayout class='monospaced'>
6496 set sysroot /home/jzhang/sysroot_arm
6497 </literallayout>
6498 </para>
6499 </section>
6500
6501 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
6502 <title>Launch the Host GDB</title>
6503
6504 <para>
6505 Before launching the host GDB, you need to be sure
6506 you have sourced the cross-debugging environment script,
6507 which if you installed the root filesystem in the default
6508 location is at <filename>/opt/poky/&DISTRO;</filename>
6509 and begins with the string "environment-setup".
6510 For more information, see the
6511 "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
6512 section in the Yocto Project Application Developer's
6513 Guide.
6514 </para>
6515
6516 <para>
6517 Finally, switch to the directory where the binary resides
6518 and run the <filename>cross-gdb</filename> binary.
6519 Provide the binary file you are going to debug.
6520 For example, the following command continues with the
6521 example used in the previous section by loading
6522 the <filename>helloworld</filename> binary as well as the
6523 debugging information:
6524 <literallayout class='monospaced'>
6525 $ arm-poky-linux-gnuabi-gdb helloworld
6526 </literallayout>
6527 The commands in your <filename>.gdbinit</filename> execute
6528 and the GDB prompt appears.
6529 </para>
6530 </section>
6531 </section>
6532
6533 <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
6534 <title>Connect to the Remote GDB Server</title>
6535
6536 <para>
6537 From the target, you need to connect to the remote GDB
6538 server that is running on the host.
6539 You need to specify the remote host and port.
6540 Here is the command continuing with the example:
6541 <literallayout class='monospaced'>
6542 target remote 192.168.7.2:2345
6543 </literallayout>
6544 </para>
6545 </section>
6546
6547 <section id="platdev-gdb-remotedebug-launch-gdb-using">
6548 <title>Use the Debugger</title>
6549
6550 <para>
6551 You can now proceed with debugging as normal - as if you were debugging
6552 on the local machine.
6553 For example, to instruct GDB to break in the "main" function and then
6554 continue with execution of the inferior binary use the following commands
6555 from within GDB:
6556 <literallayout class='monospaced'>
6557 (gdb) break main
6558 (gdb) continue
6559 </literallayout>
6560 </para>
6561
6562 <para>
6563 For more information about using GDB, see the project's online documentation at
6564 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
6565 </para>
6566 </section>
6567 </section>
6568
6569 <section id="examining-builds-using-toaster">
6570 <title>Examining Builds Using the Toaster API</title>
6571
6572 <para>
6573 Toaster is an Application Programming Interface (API) and
6574 web-based interface to the OpenEmbedded build system, which uses
6575 BitBake.
6576 Both interfaces are based on a Representational State Transfer
6577 (REST) API that queries for and returns build information using
6578 <filename>GET</filename> and <filename>JSON</filename>.
6579 These types of search operations retrieve sets of objects from
6580 a datastore used to collect build information.
6581 The results contain all the data for the objects being returned.
6582 You can order the results of the search by key and the search
6583 parameters are consistent for all object types.
6584 </para>
6585
6586 <para>
6587 Using the interfaces you can do the following:
6588 <itemizedlist>
6589 <listitem><para>See information about the tasks executed
6590 and reused during the build.</para></listitem>
6591 <listitem><para>See what is built (recipes and
6592 packages) and what packages were installed into the final
6593 image.</para></listitem>
6594 <listitem><para>See performance-related information such
6595 as build time, CPU usage, and disk I/O.</para></listitem>
6596 <listitem><para>Examine error, warning and trace messages
6597 to aid in debugging.</para></listitem>
6598 </itemizedlist>
6599 </para>
6600
6601 <note>
6602 <para>This release of Toaster provides you with information
6603 about a BitBake run.
6604 The tool does not allow you to configure and launch a build.
6605 However, future development includes plans to integrate the
6606 configuration and build launching capabilities of
6607 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
6608 </para>
6609 <para>For more information on using Hob to build an image,
6610 see the
6611 "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
6612 section.</para>
6613 </note>
6614
6615 <para>
6616 The remainder of this section describes what you need to have in
6617 place to use Toaster, how to start it, use it, and stop it.
6618 For additional information on installing and running Toaster, see the
6619 "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
6620 section of the "Toaster" wiki page.
6621 For complete information on the API and its search operation
6622 URI, parameters, and responses, see the
6623 <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
6624 Wiki page.
6625 </para>
6626
6627 <section id='starting-toaster'>
6628 <title>Starting Toaster</title>
6629
6630 <para>
6631 Getting set up to use and start Toaster is simple.
6632 First, be sure you have met the following requirements:
6633 <itemizedlist>
6634 <listitem><para>You have set up your
6635 <link linkend='source-directory'>Source Directory</link>
6636 by cloning the upstream <filename>poky</filename>
6637 repository.
6638 See the
6639 <link linkend='local-yp-release'>Yocto Project Release</link>
6640 item for information on how to set up the Source
6641 Directory.</para></listitem>
6642 <listitem><para>Be sure your build machine has
6643 <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
6644 version 1.5 installed.</para></listitem>
6645 <listitem><para>Make sure that port 8000 and 8200 are
6646 free (i.e. they have no servers on them).
6647 </para></listitem>
6648 </itemizedlist>
6649 </para>
6650
6651 <para>
6652 Once you have met the requirements, follow these steps to
6653 start Toaster running in the background of your shell:
6654 <orderedlist>
6655 <listitem><para><emphasis>Set up your build environment:</emphasis>
6656 Source a build environment script (i.e.
6657 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
6658 or
6659 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
6660 </para></listitem>
6661 <listitem><para><emphasis>Start Toaster:</emphasis>
6662 Start the Toaster service using this
6663 command from within your
6664 <link linkend='build-directory'>Build Directory</link>:
6665 <literallayout class='monospaced'>
6666 $ source toaster start
6667 </literallayout></para></listitem>
6668 <note>
6669 The Toaster must be started and running in order
6670 for it to collect data.
6671 </note>
6672 </orderedlist>
6673 </para>
6674
6675 <para>
6676 When Toaster starts, it creates some additional files in your
6677 Build Directory.
6678 Deleting these files will cause you to lose data or interrupt
6679 Toaster:
6680 <itemizedlist>
6681 <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
6682 Toaster's database file.</para></listitem>
6683 <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
6684 The log file of the web server.</para></listitem>
6685 <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
6686 The log file of the user interface component.
6687 </para></listitem>
6688 <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
6689 The PID of the web server.</para></listitem>
6690 <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
6691 The PID of the DSI data bridge.</para></listitem>
6692 <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
6693 The BitBake server's log file.</para></listitem>
6694 </itemizedlist>
6695 </para>
6696 </section>
6697
6698 <section id='using-toaster'>
6699 <title>Using Toaster</title>
6700
6701 <para>
6702 Once Toaster is running, it logs information for any BitBake
6703 run from your Build Directory.
6704 This logging is automatic.
6705 All you need to do is access and use the information.
6706 </para>
6707
6708 <para>
6709 You access the information one of two ways:
6710 <itemizedlist>
6711 <listitem><para>Open a Browser and enter
6712 <filename>http://localhost:8000</filename>
6713 for the URL.
6714 </para></listitem>
6715 <listitem><para>Use the <filename>xdg-open</filename>
6716 tool from the shell and pass it the same URL.
6717 </para></listitem>
6718 </itemizedlist>
6719 Either method opens the home page for the Toaster interface.
6720 </para>
6721
6722 <note><title>Notes</title>
6723 <para>
6724 For information on how to delete information from the Toaster
6725 database, see the
6726 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink>
6727 wiki page.
6728 </para>
6729
6730 <para>
6731 For information on how to set up an instance of Toaster on
6732 a remote host, see the
6733 <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink>
6734 wiki page.
6735 </para>
6736 </note>
6737 </section>
6738
6739 <section id='examining-toaster-data'>
6740 <title>Examining Toaster Data</title>
6741
6742 <para>
6743 The Toaster database is persistent regardless of whether you
6744 start or stop the service.
6745 </para>
6746
6747 <para>
6748 Toaster's interface shows you a list of builds
6749 (successful and unsuccessful) for which it has data.
6750 You can click on any build to see related information.
6751 This information includes configuration details, information
6752 about tasks, all recipes and packages built and their
6753 dependencies, packages and their directory structure as
6754 installed in your final image,
6755 execution time, CPU usage and disk I/O per task.
6756 </para>
6757
6758 <para>
6759 For details on the interface, see the
6760 <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>.
6761 </para>
6762 </section>
6763
6764 <section id='stopping-toaster'>
6765 <title>Stopping Toaster</title>
6766
6767 <para>
6768 Stop the Toaster service with the following command
6769 from with the
6770 <link linkend='build-directory'>Build Directory</link>:
6771 <literallayout class='monospaced'>
6772 $ source toaster stop
6773 </literallayout>
6774 The service stops but the Toaster database remains persistent.
6775 </para>
6776 </section>
6777 </section>
6778
6779 <section id="platdev-oprofile">
6780 <title>Profiling with OProfile</title>
6781
6782 <para>
6783 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
6784 statistical profiler well suited for finding performance
6785 bottlenecks in both user-space software and in the kernel.
6786 This profiler provides answers to questions like "Which functions does my application spend
6787 the most time in when doing X?"
6788 Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
6789 applications on target hardware straight forward.
6790 <note>
6791 For more information on how to set up and run OProfile, see the
6792 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
6793 section in the Yocto Project Profiling and Tracing Manual.
6794 </note>
6795 </para>
6796
6797 <para>
6798 To use OProfile, you need an image that has OProfile installed.
6799 The easiest way to do this is with "tools-profile" in the
6800 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
6801 You also need debugging symbols to be available on the system where the analysis
6802 takes place.
6803 You can gain access to the symbols by using "dbg-pkgs" in the
6804 <filename>IMAGE_FEATURES</filename> variable or by
6805 installing the appropriate DBG (<filename>-dbg</filename>) packages.
6806 </para>
6807
6808 <para>
6809 For successful call graph analysis, the binaries must preserve the frame
6810 pointer register and should also be compiled with the
6811 <filename>-fno-omit-framepointer</filename> flag.
6812 You can achieve this by setting the
6813 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
6814 variable with the following options:
6815 <literallayout class='monospaced'>
6816 -fexpensive-optimizations
6817 -fno-omit-framepointer
6818 -frename-registers
6819 -O2
6820 </literallayout>
6821 You can also achieve it by setting the
6822 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
6823 variable to "1" in the <filename>local.conf</filename> configuration file.
6824 If you use the <filename>DEBUG_BUILD</filename> variable,
6825 you also add extra debugging information that can make the debug
6826 packages large.
6827 </para>
6828
6829 <section id="platdev-oprofile-target">
6830 <title>Profiling on the Target</title>
6831
6832 <para>
6833 Using OProfile, you can perform all the profiling work on the target device.
6834 A simple OProfile session might look like the following:
6835 </para>
6836
6837 <para>
6838 <literallayout class='monospaced'>
6839 # opcontrol --reset
6840 # opcontrol --start --separate=lib --no-vmlinux -c 5
6841 .
6842 .
6843 [do whatever is being profiled]
6844 .
6845 .
6846 # opcontrol --stop
6847 $ opreport -cl
6848 </literallayout>
6849 </para>
6850
6851 <para>
6852 In this example, the <filename>reset</filename> command clears any previously profiled data.
6853 The next command starts OProfile.
6854 The options used when starting the profiler separate dynamic library data
6855 within applications, disable kernel profiling, and enable callgraphing up to
6856 five levels deep.
6857 <note>
6858 To profile the kernel, you would specify the
6859 <filename>--vmlinux=/path/to/vmlinux</filename> option.
6860 The <filename>vmlinux</filename> file is usually in the source directory in the
6861 <filename>/boot/</filename> directory and must match the running kernel.
6862 </note>
6863 </para>
6864
6865 <para>
6866 After you perform your profiling tasks, the next command stops the profiler.
6867 After that, you can view results with the <filename>opreport</filename> command with options
6868 to see the separate library symbols and callgraph information.
6869 </para>
6870
6871 <para>
6872 Callgraphing logs information about time spent in functions and about a function's
6873 calling function (parent) and called functions (children).
6874 The higher the callgraphing depth, the more accurate the results.
6875 However, higher depths also increase the logging overhead.
6876 Consequently, you should take care when setting the callgraphing depth.
6877 <note>
6878 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
6879 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
6880 with <filename>gcc</filename>.
6881 </note>
6882 </para>
6883
6884 <para>
6885 For more information on using OProfile, see the OProfile
6886 online documentation at
6887 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
6888 </para>
6889 </section>
6890
6891 <section id="platdev-oprofile-oprofileui">
6892 <title>Using OProfileUI</title>
6893
6894 <para>
6895 A graphical user interface for OProfile is also available.
6896 You can download and build this interface from the Yocto Project at
6897 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
6898 If the "tools-profile" image feature is selected, all necessary binaries
6899 are installed onto the target device for OProfileUI interaction.
6900 For a list of image features that ship with the Yocto Project,
6901 see the
6902 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
6903 section in the Yocto Project Reference Manual.
6904 </para>
6905
6906 <para>
6907 Even though the source directory usually includes all needed patches on the target device, you
6908 might find you need other OProfile patches for recent OProfileUI features.
6909 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
6910 OProfileUI README</ulink> for the most recent information.
6911 </para>
6912
6913 <section id="platdev-oprofile-oprofileui-online">
6914 <title>Online Mode</title>
6915
6916 <para>
6917 Using OProfile in online mode assumes a working network connection with the target
6918 hardware.
6919 With this connection, you just need to run "oprofile-server" on the device.
6920 By default, OProfile listens on port 4224.
6921 <note>
6922 You can change the port using the <filename>--port</filename> command-line
6923 option.
6924 </note>
6925 </para>
6926
6927 <para>
6928 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
6929 straight forward.
6930 You access key functionality through the buttons on the toolbar, which
6931 are duplicated in the menus.
6932 Here are the buttons:
6933 <itemizedlist>
6934 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
6935 You can also supply the IP address or hostname.</para></listitem>
6936 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
6937 </para></listitem>
6938 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
6939 </para></listitem>
6940 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
6941 downloads the data to the local host.
6942 Stopping the profiler generates the profile and displays it in the viewer.
6943 </para></listitem>
6944 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
6945 target and generates the profile, which appears in the viewer.</para></listitem>
6946 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
6947 Resetting the data removes sample information collected from previous
6948 sampling runs.
6949 Be sure you reset the data if you do not want to include old sample information.
6950 </para></listitem>
6951 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
6952 target to another directory for later examination.</para></listitem>
6953 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
6954 </para></listitem>
6955 </itemizedlist>
6956 </para>
6957
6958 <para>
6959 The client downloads the complete profile archive from
6960 the target to the host for processing.
6961 This archive is a directory that contains the sample data, the object files,
6962 and the debug information for the object files.
6963 The archive is then converted using the <filename>oparchconv</filename> script, which is
6964 included in this distribution.
6965 The script uses <filename>opimport</filename> to convert the archive from
6966 the target to something that can be processed on the host.
6967 </para>
6968
6969 <para>
6970 Downloaded archives reside in the
6971 <link linkend='build-directory'>Build Directory</link> in
6972 <filename>tmp</filename> and are cleared up when they are no longer in use.
6973 </para>
6974
6975 <para>
6976 If you wish to perform kernel profiling, you need to be sure
6977 a <filename>vmlinux</filename> file that matches the running kernel is available.
6978 In the source directory, that file is usually located in
6979 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
6980 <filename>KERNEL-version</filename> is the version of the kernel.
6981 The OpenEmbedded build system generates separate <filename>vmlinux</filename>
6982 packages for each kernel it builds.
6983 Thus, it should just be a question of making sure a matching package is
6984 installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
6985 The files are automatically installed into development and profiling images
6986 alongside OProfile.
6987 A configuration option exists within the OProfileUI settings page that you can use to
6988 enter the location of the <filename>vmlinux</filename> file.
6989 </para>
6990
6991 <para>
6992 Waiting for debug symbols to transfer from the device can be slow, and it
6993 is not always necessary to actually have them on the device for OProfile use.
6994 All that is needed is a copy of the filesystem with the debug symbols present
6995 on the viewer system.
6996 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
6997 section covers how to create such a directory within
6998 the source directory and how to use the OProfileUI Settings
6999 Dialog to specify the location.
7000 If you specify the directory, it will be used when the file checksums
7001 match those on the system you are profiling.
7002 </para>
7003 </section>
7004
7005 <section id="platdev-oprofile-oprofileui-offline">
7006 <title>Offline Mode</title>
7007
7008 <para>
7009 If network access to the target is unavailable, you can generate
7010 an archive for processing in <filename>oprofile-viewer</filename> as follows:
7011 <literallayout class='monospaced'>
7012 # opcontrol --reset
7013 # opcontrol --start --separate=lib --no-vmlinux -c 5
7014 .
7015 .
7016 [do whatever is being profiled]
7017 .
7018 .
7019 # opcontrol --stop
7020 # oparchive -o my_archive
7021 </literallayout>
7022 </para>
7023
7024 <para>
7025 In the above example, <filename>my_archive</filename> is the name of the
7026 archive directory where you would like the profile archive to be kept.
7027 After the directory is created, you can copy it to another host and load it
7028 using <filename>oprofile-viewer</filename> open functionality.
7029 If necessary, the archive is converted.
7030 </para>
7031 </section>
7032 </section>
7033 </section>
7034
7035 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
7036 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
7037
7038 <para>
7039 One of the concerns for a development organization using open source
7040 software is how to maintain compliance with various open source
7041 licensing during the lifecycle of the product.
7042 While this section does not provide legal advice or
7043 comprehensively cover all scenarios, it does
7044 present methods that you can use to
7045 assist you in meeting the compliance requirements during a software
7046 release.
7047 </para>
7048
7049 <para>
7050 With hundreds of different open source licenses that the Yocto
7051 Project tracks, it is difficult to know the requirements of each
7052 and every license.
7053 However, the requirements of the major FLOSS licenses can begin
7054 to be covered by
7055 assuming that three main areas of concern exist:
7056 <itemizedlist>
7057 <listitem><para>Source code must be provided.</para></listitem>
7058 <listitem><para>License text for the software must be
7059 provided.</para></listitem>
7060 <listitem><para>Compilation scripts and modifications to the
7061 source code must be provided.
7062 </para></listitem>
7063 </itemizedlist>
7064 There are other requirements beyond the scope of these
7065 three and the methods described in this section
7066 (e.g. the mechanism through which source code is distributed).
7067 </para>
7068
7069 <para>
7070 As different organizations have different methods of complying with
7071 open source licensing, this section is not meant to imply that
7072 there is only one single way to meet your compliance obligations,
7073 but rather to describe one method of achieving compliance.
7074 The remainder of this section describes methods supported to meet the
7075 previously mentioned three requirements.
7076 Once you take steps to meet these requirements,
7077 and prior to releasing images, sources, and the build system,
7078 you should audit all artifacts to ensure completeness.
7079 <note>
7080 The Yocto Project generates a license manifest during
7081 image creation that is located
7082 in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
7083 to assist with any audits.
7084 </note>
7085 </para>
7086
7087 <section id='providing-the-source-code'>
7088 <title>Providing the Source Code</title>
7089
7090 <para>
7091 Compliance activities should begin before you generate the
7092 final image.
7093 The first thing you should look at is the requirement that
7094 tops the list for most compliance groups - providing
7095 the source.
7096 The Yocto Project has a few ways of meeting this
7097 requirement.
7098 </para>
7099
7100 <para>
7101 One of the easiest ways to meet this requirement is
7102 to provide the entire
7103 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
7104 used by the build.
7105 This method, however, has a few issues.
7106 The most obvious is the size of the directory since it includes
7107 all sources used in the build and not just the source used in
7108 the released image.
7109 It will include toolchain source, and other artifacts, which
7110 you would not generally release.
7111 However, the more serious issue for most companies is accidental
7112 release of proprietary software.
7113 The Yocto Project provides an
7114 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
7115 class to help avoid some of these concerns.
7116 </para>
7117
7118 <para>
7119 Before you employ <filename>DL_DIR</filename> or the
7120 archiver class, you need to decide how you choose to
7121 provide source.
7122 The source archiver class can generate tarballs and SRPMs
7123 and can create them with various levels of compliance in mind.
7124 </para>
7125
7126 <para>
7127 One way of doing this (but certainly not the only way) is to
7128 release just the source as a tarball.
7129 You can do this by adding the following to the
7130 <filename>local.conf</filename> file found in the
7131 <link linkend='build-directory'>Build Directory</link>:
7132 <literallayout class='monospaced'>
7133 INHERIT += "archiver"
7134 ARCHIVER_MODE[src] = "original"
7135 </literallayout>
7136 During the creation of your image, the source from all
7137 recipes that deploy packages to the image is placed within
7138 subdirectories of
7139 <filename>DEPLOY_DIR/sources</filename> based on the
7140 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
7141 for each recipe.
7142 Releasing the entire directory enables you to comply with
7143 requirements concerning providing the unmodified source.
7144 It is important to note that the size of the directory can
7145 get large.
7146 </para>
7147
7148 <para>
7149 A way to help mitigate the size issue is to only release
7150 tarballs for licenses that require the release of
7151 source.
7152 Let us assume you are only concerned with GPL code as
7153 identified with the following:
7154 <literallayout class='monospaced'>
7155 $ cd poky/build/tmp/deploy/sources
7156 $ mkdir ~/gpl_source_release
7157 $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
7158 </literallayout>
7159 At this point, you could create a tarball from the
7160 <filename>gpl_source_release</filename> directory and
7161 provide that to the end user.
7162 This method would be a step toward achieving compliance
7163 with section 3a of GPLv2 and with section 6 of GPLv3.
7164 </para>
7165 </section>
7166
7167 <section id='providing-license-text'>
7168 <title>Providing License Text</title>
7169
7170 <para>
7171 One requirement that is often overlooked is inclusion
7172 of license text.
7173 This requirement also needs to be dealt with prior to
7174 generating the final image.
7175 Some licenses require the license text to accompany
7176 the binary.
7177 You can achieve this by adding the following to your
7178 <filename>local.conf</filename> file:
7179 <literallayout class='monospaced'>
7180 COPY_LIC_MANIFEST = "1"
7181 COPY_LIC_DIRS = "1"
7182 </literallayout>
7183 Adding these statements to the configuration file ensures
7184 that the licenses collected during package generation
7185 are included on your image.
7186 As the source archiver has already archived the original
7187 unmodified source that contains the license files,
7188 you would have already met the requirements for inclusion
7189 of the license information with source as defined by the GPL
7190 and other open source licenses.
7191 </para>
7192 </section>
7193
7194 <section id='providing-compilation-scripts-and-source-code-modifications'>
7195 <title>Providing Compilation Scripts and Source Code Modifications</title>
7196
7197 <para>
7198 At this point, we have addressed all we need to address
7199 prior to generating the image.
7200 The next two requirements are addressed during the final
7201 packaging of the release.
7202 </para>
7203
7204 <para>
7205 By releasing the version of the OpenEmbedded build system
7206 and the layers used during the build, you will be providing both
7207 compilation scripts and the source code modifications in one
7208 step.
7209 </para>
7210
7211 <para>
7212 If the deployment team has a
7213 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
7214 and a distro layer, and those those layers are used to patch,
7215 compile, package, or modify (in any way) any open source
7216 software included in your released images, you
7217 might be required to to release those layers under section 3 of
7218 GPLv2 or section 1 of GPLv3.
7219 One way of doing that is with a clean
7220 checkout of the version of the Yocto Project and layers used
7221 during your build.
7222 Here is an example:
7223 <literallayout class='monospaced'>
7224 # We built using the &DISTRO_NAME; branch of the poky repo
7225 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
7226 $ cd poky
7227 # We built using the release_branch for our layers
7228 $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
7229 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
7230 # clean up the .git repos
7231 $ find . -name ".git" -type d -exec rm -rf {} \;
7232 </literallayout>
7233 One thing a development organization might want to consider
7234 for end-user convenience is to modify
7235 <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
7236 ensure that when the end user utilizes the released build
7237 system to build an image, the development organization's
7238 layers are included in the <filename>bblayers.conf</filename>
7239 file automatically:
7240 <literallayout class='monospaced'>
7241 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
7242 # changes incompatibly
7243 LCONF_VERSION = "6"
7244
7245 BBPATH = "${TOPDIR}"
7246 BBFILES ?= ""
7247
7248 BBLAYERS ?= " \
7249 ##OEROOT##/meta \
7250 ##OEROOT##/meta-yocto \
7251 ##OEROOT##/meta-yocto-bsp \
7252 ##OEROOT##/meta-mylayer \
7253 "
7254
7255 BBLAYERS_NON_REMOVABLE ?= " \
7256 ##OEROOT##/meta \
7257 ##OEROOT##/meta-yocto \
7258 "
7259 </literallayout>
7260 Creating and providing an archive of the
7261 <link linkend='metadata'>Metadata</link> layers
7262 (recipes, configuration files, and so forth)
7263 enables you to meet your
7264 requirements to include the scripts to control compilation
7265 as well as any modifications to the original source.
7266 </para>
7267 </section>
7268 </section>
7269
7270 <section id='using-the-error-reporting-tool'>
7271 <title>Using the Error Reporting Tool</title>
7272
7273 <para>
7274 The error reporting tool allows you to
7275 submit errors encountered during builds to a central database.
7276 Outside of the build environment, you can use a web interface to
7277 browse errors, view statistics, and query for errors.
7278 The tool works using a client-server system where the client
7279 portion is integrated with the installed Yocto Project
7280 <link linkend='source-directory'>Source Directory</link>
7281 (e.g. <filename>poky</filename>).
7282 The server receives the information collected and saves it in a
7283 database.
7284 </para>
7285
7286 <para>
7287 A live instance of the error reporting server exists at
7288 <ulink url='http://errors.yoctoproject.org'></ulink>.
7289 This server exists so that when you want to get help with
7290 build failures, you can submit all of the information on the
7291 failure easily and then point to the URL in your bug report
7292 or send an email to the mailing list.
7293 <note>
7294 If you send error reports to this server, the reports become
7295 publicly visible.
7296 </note>
7297 </para>
7298
7299 <section id='enabling-and-using-the-tool'>
7300 <title>Enabling and Using the Tool</title>
7301
7302 <para>
7303 By default, the error reporting tool is disabled.
7304 You can enable it by inheriting the
7305 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink>
7306 class by adding the following statement to the end of
7307 your <filename>local.conf</filename> file in your
7308 <link linkend='build-directory'>Build Directory</link>.
7309 <literallayout class='monospaced'>
7310 INHERIT += "report-error"
7311 </literallayout>
7312 </para>
7313
7314 <para>
7315 By default, the error reporting feature stores information in
7316 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>.
7317 However, you can specify a directory to use by adding the following
7318 to your <filename>local.conf</filename> file:
7319 <literallayout class='monospaced'>
7320 ERR_REPORT_DIR = "path"
7321 </literallayout>
7322 Enabling error reporting causes the build process to collect
7323 the errors and store them in a file as previously described.
7324 When the build system encounters an error, it includes a command
7325 as part of the console output.
7326 You can run the command to send the error file to the server.
7327 For example, the following command sends the errors to an upstream
7328 server:
7329 <literallayout class='monospaced'>
7330 send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server]
7331 </literallayout>
7332 In the above example, the <filename>server</filename> parameter is
7333 optional.
7334 By default, the errors are sent to a database used by the entire
7335 community.
7336 If you specify a particular server, you can send them to a different
7337 database.
7338 </para>
7339
7340 <para>
7341 When sending the error file, you receive a link that corresponds
7342 to your entry in the database.
7343 For example, here is a typical link:
7344 <literallayout class='monospaced'>
7345 http://localhost:8000/Errors/Search/1/158
7346 </literallayout>
7347 Following the link takes you to a web interface where you can
7348 browse, query the errors, and view statistics.
7349 </para>
7350 </section>
7351
7352 <section id='disabling-the-tool'>
7353 <title>Disabling the Tool</title>
7354
7355 <para>
7356 To disable the error reporting feature, simply remove or comment
7357 out the following statement from the end of your
7358 <filename>local.conf</filename> file in your
7359 <link linkend='build-directory'>Build Directory</link>.
7360 <literallayout class='monospaced'>
7361 INHERIT += "report-error"
7362 </literallayout>
7363 </para>
7364 </section>
7365
7366 <section id='setting-up-your-own-error-reporting-server'>
7367 <title>Setting Up Your Own Error Reporting Server</title>
7368
7369 <para>
7370 If you want to set up your own error reporting server, you
7371 can obtain the code from the Git repository at
7372 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>.
7373 Instructions on how to set it up are in the README document.
7374 </para>
7375 </section>
7376 </section>
7377</chapter>
7378
7379<!--
7380vim: expandtab tw=80 ts=4
7381-->
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..f3cf489f5b
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -0,0 +1,207 @@
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 </para></listitem>
157 <listitem><para><emphasis>
158 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
159 The bug tracking application the Yocto Project uses.
160 If you find problems with the Yocto Project, you should report them using this
161 application.</para></listitem>
162 <listitem><para><emphasis>
163 Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
164 lists, click on the following URLs and follow the instructions:
165 <itemizedlist>
166 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
167 Yocto Project Discussions mailing list.</para></listitem>
168 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
169 Yocto Project Discussions mailing list about the
170 OpenEmbedded build system (Poky).
171 </para></listitem>
172 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
173 for a mailing list to receive official Yocto Project announcements
174 as well as Yocto Project milestones.</para></listitem>
175 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a
176 listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>.
177 </para></listitem>
178 </itemizedlist></para></listitem>
179 <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
180 Two IRC channels on freenode are available
181 for Yocto Project and Poky discussions: <filename>#yocto</filename> and
182 <filename>#poky</filename>, respectively.</para></listitem>
183 <listitem><para><emphasis>
184 <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
185 The build system used by the Yocto Project.
186 This project is the upstream, generic, embedded distribution
187 from which the Yocto Project derives its build system (Poky)
188 and to which it contributes.</para></listitem>
189 <listitem><para><emphasis>
190 <ulink url='http://developer.berlios.de/projects/bitbake/'>
191 BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
192 to process project metadata.</para></listitem>
193 <listitem><para><emphasis>
194 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual:</ulink></emphasis>
195 A comprehensive guide to the BitBake tool.
196 If you want information on BitBake, see this manual.
197 </para></listitem>
198 <listitem><para><emphasis>
199 <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
200 </emphasis> An open-source machine emulator and virtualizer.</para></listitem>
201 </itemizedlist>
202 </para>
203 </section>
204</chapter>
205<!--
206vim: expandtab tw=80 ts=4
207-->
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
new file mode 100644
index 0000000000..4fd4c4e1e3
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -0,0 +1,2069 @@
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>Five BSPs exist that are part of the
159 Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>,
160 <filename>beaglebone</filename>,
161 <filename>mpc8315e</filename>, and <filename>edgerouter</filename>.
162 The recipes and configurations for these five BSPs are located and dispersed
163 within the <link linkend='source-directory'>Source Directory</link>.
164 On the other hand, BSP layers for Crown Bay,
165 Crystal Forest, Emenlow, Fish River Island 2, Haswell,
166 Jasper Forest, NUC DC3217IYE,
167 Romley, Sugar Bay, and tlk exist in their own separate layers
168 within the larger <filename>meta-intel</filename> layer.</note>
169 <para>When you set up a layer for a new BSP, you should follow a standard layout.
170 This layout is described in the
171 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
172 section of the Board Support Package (BSP) Development Guide.
173 In the standard layout, you will notice a suggested structure for recipes and
174 configuration information.
175 You can see the standard layout for a BSP by examining
176 any supported BSP found in the <filename>meta-intel</filename> layer inside
177 the Source Directory.</para></listitem>
178 <listitem><para><emphasis>Make configuration changes to your new BSP
179 layer</emphasis>: The standard BSP layer structure organizes the files you need
180 to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
181 directories within the BSP layer.
182 Configuration changes identify where your new layer is on the local system
183 and identify which kernel you are going to use.
184 When you run the <filename>yocto-bsp</filename> script, you are able to interactively
185 configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
186 </para></listitem>
187 <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe
188 changes include altering recipes (<filename>.bb</filename> files), removing
189 recipes you do not use, and adding new recipes or append files
190 (<filename>.bbappend</filename>) that you need to support your hardware.
191 </para></listitem>
192 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
193 changes to your BSP layer, there remains a few things
194 you need to do for the OpenEmbedded build system in order for it to create your image.
195 You need to get the build environment ready by sourcing an environment setup script
196 (i.e. <filename>oe-init-build-env</filename> or
197 <filename>oe-init-build-env-memres</filename>)
198 and you need to be sure two key configuration files are configured appropriately:
199 the <filename>conf/local.conf</filename> and the
200 <filename>conf/bblayers.conf</filename> file.
201 You must make the OpenEmbedded build system aware of your new layer.
202 See the
203 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
204 for information on how to let the build system know about your new layer.</para>
205 <para>The entire process for building an image is overviewed in the section
206 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
207 of the Yocto Project Quick Start.
208 You might want to reference this information.</para></listitem>
209 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
210 uses the BitBake tool to build images based on the type of image you want to create.
211 You can find more information about BitBake in the
212 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
213 </para>
214 <para>The build process supports several types of images to satisfy different needs.
215 See the
216 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
217 in the Yocto Project Reference Manual for information on
218 supported images.</para></listitem>
219 </orderedlist>
220 </para>
221
222 <para>
223 You can view a video presentation on "Building Custom Embedded Images with Yocto"
224 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
225 After going to the page, just search for "Embedded".
226 You can also find supplemental information in the
227 <ulink url='&YOCTO_DOCS_BSP_URL;'>
228 Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
229 Finally, there is a wiki page write up of the example also located
230 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
231 here</ulink> that you might find helpful.
232 </para>
233 </section>
234
235 <section id='modifying-the-kernel'>
236 <title><anchor id='kernel-spot' />Modifying the Kernel</title>
237
238 <para>
239 Kernel modification involves changing the Yocto Project kernel, which could involve changing
240 configuration options as well as adding new kernel recipes.
241 Configuration changes can be added in the form of configuration fragments, while recipe
242 modification comes through the kernel's <filename>recipes-kernel</filename> area
243 in a kernel layer you create.
244 </para>
245
246 <para>
247 The remainder of this section presents a high-level overview of the Yocto Project
248 kernel architecture and the steps to modify the kernel.
249 You can reference the
250 "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
251 for an example that changes the source code of the kernel.
252 For information on how to configure the kernel, see the
253 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
254 For more information on the kernel and on modifying the kernel, see the
255 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
256 </para>
257
258 <section id='kernel-overview'>
259 <title>Kernel Overview</title>
260
261 <para>
262 Traditionally, when one thinks of a patched kernel, they think of a base kernel
263 source tree and a fixed structure that contains kernel patches.
264 The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
265 generator.
266 By the end of this section, this analogy will become clearer.
267 </para>
268
269 <para>
270 You can find a web interface to the Yocto Project kernel source repositories at
271 <ulink url='&YOCTO_GIT_URL;'></ulink>.
272 If you look at the interface, you will see to the left a grouping of
273 Git repositories titled "Yocto Linux Kernel."
274 Within this group, you will find several kernels supported by
275 the Yocto Project:
276 <itemizedlist>
277 <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The
278 stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel
279 is based on the Linux 3.4 released kernel.</para></listitem>
280 <listitem><para><emphasis><filename>linux-yocto-3.8</filename></emphasis> - The
281 stable Yocto Project kernel to use with the Yocto Project Release 1.4. This kernel
282 is based on the Linux 3.8 released kernel.</para></listitem>
283 <listitem><para><emphasis><filename>linux-yocto-3.10</filename></emphasis> - The
284 stable Yocto Project kernel to use with the Yocto Project Release 1.5. This kernel
285 is based on the Linux 3.10 released kernel.</para></listitem>
286 <listitem><para><emphasis><filename>linux-yocto-3.14</filename></emphasis> - The
287 stable Yocto Project kernel to use with the Yocto Project Release 1.6. This kernel
288 is based on the Linux 3.14 released kernel.</para></listitem>
289 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
290 kernel based on the latest upstream release candidate available.</para></listitem>
291 </itemizedlist>
292 </para>
293
294 <para>
295 The kernels are maintained using the Git revision control system
296 that structures them using the familiar "tree", "branch", and "leaf" scheme.
297 Branches represent diversions from general code to more specific code, while leaves
298 represent the end-points for a complete and unique kernel whose source files,
299 when gathered from the root of the tree to the leaf, accumulate to create the files
300 necessary for a specific piece of hardware and its features.
301 The following figure displays this concept:
302 <para>
303 <imagedata fileref="figures/kernel-overview-1.png"
304 width="6in" depth="6in" align="center" scale="100" />
305 </para>
306
307 <para>
308 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
309 where a supported base kernel is modified from the Linux kernel.
310 For example, this could be the branch point for the <filename>linux-yocto-3.4</filename>
311 kernel.
312 Thus, everything further to the right in the structure is based on the
313 <filename>linux-yocto-3.4</filename> kernel.
314 Branch points to right in the figure represent where the
315 <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware
316 or types of kernels, such as real-time kernels.
317 Each leaf thus represents the end-point for a kernel designed to run on a specific
318 targeted device.
319 </para>
320
321 <para>
322 The overall result is a Git-maintained repository from which all the supported
323 kernel types can be derived for all the supported devices.
324 A big advantage to this scheme is the sharing of common features by keeping them in
325 "larger" branches within the tree.
326 This practice eliminates redundant storage of similar features shared among kernels.
327 </para>
328
329 <note>
330 Keep in mind the figure does not take into account all the supported Yocto
331 Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
332 Also keep in mind that this structure represents the Yocto Project source repositories
333 that are either pulled from during the build or established on the host development system
334 prior to the build by either cloning a particular kernel's Git repository or by
335 downloading and unpacking a tarball.
336 </note>
337
338 <para>
339 Upstream storage of all the available kernel source code is one thing, while
340 representing and using the code on your host development system is another.
341 Conceptually, you can think of the kernel source repositories as all the
342 source files necessary for all the supported kernels.
343 As a developer, you are just interested in the source files for the kernel on
344 which you are working.
345 And, furthermore, you need them available on your host system.
346 </para>
347
348 <para>
349 Kernel source code is available on your host system a couple of different
350 ways.
351 If you are working in the kernel all the time, you probably would want
352 to set up your own local Git repository of the kernel tree.
353 If you just need to make some patches to the kernel, you can access
354 temporary kernel source files that were extracted and used
355 during a build.
356 We will just talk about working with the temporary source code.
357 For more information on how to get kernel source code onto your
358 host system, see the
359 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
360 bulleted item earlier in the manual.
361 </para>
362
363 <para>
364 What happens during the build?
365 When you build the kernel on your development system, all files needed for the build
366 are taken from the source repositories pointed to by the
367 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
368 and gathered in a temporary work area
369 where they are subsequently used to create the unique kernel.
370 Thus, in a sense, the process constructs a local source tree specific to your
371 kernel to generate the new kernel image - a source generator if you will.
372 </para>
373 The following figure shows the temporary file structure
374 created on your host system when the build occurs.
375 This
376 <link linkend='build-directory'>Build Directory</link> contains all the
377 source files used during the build.
378 </para>
379
380 <para>
381 <imagedata fileref="figures/kernel-overview-2-generic.png"
382 width="6in" depth="5in" align="center" scale="100" />
383 </para>
384
385 <para>
386 Again, for additional information on the Yocto Project kernel's
387 architecture and its branching strategy, see the
388 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
389 You can also reference the
390 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
391 section for a detailed example that modifies the kernel.
392 </para>
393 </section>
394
395 <section id='kernel-modification-workflow'>
396 <title>Kernel Modification Workflow</title>
397
398 <para>
399 This illustration and the following list summarizes the kernel modification general workflow.
400 </para>
401
402 <para>
403 <imagedata fileref="figures/kernel-dev-flow.png"
404 width="6in" depth="5in" align="center" scalefit="1" />
405 </para>
406
407 <para>
408 <orderedlist>
409 <listitem><para><emphasis>Set up your host development system to support
410 development using the Yocto Project</emphasis>: See
411 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
412 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
413 in the Yocto Project Quick Start for requirements.</para></listitem>
414 <listitem><para><emphasis>Establish a local copy of project files on your
415 system</emphasis>: Having the <link linkend='source-directory'>Source
416 Directory</link> on your system gives you access to the build process and tools
417 you need.
418 For information on how to get these files, see the bulleted item
419 "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
420 </para></listitem>
421 <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
422 Temporary kernel source files are kept in the
423 <link linkend='build-directory'>Build Directory</link>
424 created by the
425 OpenEmbedded build system when you run BitBake.
426 If you have never built the kernel in which you are
427 interested, you need to run an initial build to
428 establish local kernel source files.</para>
429 <para>If you are building an image for the first time, you need to get the build
430 environment ready by sourcing an environment setup script
431 (i.e. <filename>oe-init-build-env</filename> or
432 <filename>oe-init-build-env-memres</filename>).
433 You also need to be sure two key configuration files
434 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
435 are configured appropriately.</para>
436 <para>The entire process for building an image is overviewed in the
437 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
438 section of the Yocto Project Quick Start.
439 You might want to reference this information.
440 You can find more information on BitBake in the
441 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
442 </para>
443 <para>The build process supports several types of images to satisfy different needs.
444 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
445 the Yocto Project Reference Manual for information on supported images.
446 </para></listitem>
447 <listitem><para><emphasis>Make changes to the kernel source code if
448 applicable</emphasis>: Modifying the kernel does not always mean directly
449 changing source files.
450 However, if you have to do this, you make the changes to the files in the
451 Build Directory.</para></listitem>
452 <listitem><para><emphasis>Make kernel configuration changes
453 if applicable</emphasis>:
454 If your situation calls for changing the kernel's configuration, you can
455 use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
456 to enable and disable kernel configurations.
457 Using the script lets you interactively set up kernel configurations.
458 Using <filename>menuconfig</filename> allows you to interactively develop and test the
459 configuration changes you are making to the kernel.
460 When saved, changes using <filename>menuconfig</filename> update the kernel's
461 <filename>.config</filename> file.
462 Try to resist the temptation of directly editing the <filename>.config</filename>
463 file found in the Build Directory at
464 <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
465 Doing so, can produce unexpected results when the OpenEmbedded build system
466 regenerates the configuration file.</para>
467 <para>Once you are satisfied with the configuration changes made using
468 <filename>menuconfig</filename>, you can directly compare the
469 <filename>.config</filename> file against a saved original and gather those
470 changes into a config fragment to be referenced from within the kernel's
471 <filename>.bbappend</filename> file.</para></listitem>
472 <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
473 Rebuilding the kernel image applies your changes.</para></listitem>
474 </orderedlist>
475 </para>
476 </section>
477 </section>
478</section>
479
480<section id='application-development-workflow'>
481 <title>Application Development Workflow</title>
482
483 <para>
484 Application development involves creating an application that you want
485 to run on your target hardware, which is running a kernel image created using the
486 OpenEmbedded build system.
487 The Yocto Project provides an
488 <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink>
489 and stand-alone
490 <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink>
491 that facilitate quick development and integration of your application into its runtime environment.
492 Using the ADT and toolchains, you can compile and link your application.
493 You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
494 If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE,
495 you can use an Eclipse Yocto Plug-in to
496 allow you to develop, deploy, and test your application all from within Eclipse.
497 </para>
498
499 <para>
500 While we strongly suggest using the ADT to develop your application, this option might not
501 be best for you.
502 If this is the case, you can still use pieces of the Yocto Project for your development process.
503 However, because the process can vary greatly, this manual does not provide detail on the process.
504 </para>
505
506 <section id='workflow-using-the-adt-and-eclipse'>
507 <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
508
509 <para>
510 To help you understand how application development works using the ADT, this section
511 provides an overview of the general development process and a detailed example of the process
512 as it is used from within the Eclipse IDE.
513 </para>
514
515 <para>
516 The following illustration and list summarize the application development general workflow.
517 </para>
518
519 <para>
520 <imagedata fileref="figures/app-dev-flow.png"
521 width="7in" depth="8in" align="center" scale="100" />
522 </para>
523
524 <para>
525 <orderedlist>
526 <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
527 See
528 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
529 and
530 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both
531 in the Yocto Project Reference Manual for requirements.
532 In particular, be sure your host system has the
533 <filename>xterm</filename> package installed.
534 </para></listitem>
535 <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
536 You must have a target kernel image that has been built using the OpenEmbedded
537 build system.</para>
538 <para>Depending on whether the Yocto Project has a pre-built image that matches your target
539 architecture and where you are going to run the image while you develop your application
540 (QEMU or real hardware), the area from which you get the image differs.
541 <itemizedlist>
542 <listitem><para>Download the image from
543 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
544 if your target architecture is supported and you are going to develop
545 and test your application on actual hardware.</para></listitem>
546 <listitem><para>Download the image from
547 <ulink url='&YOCTO_QEMU_DL_URL;'>
548 <filename>machines/qemu</filename></ulink> if your target architecture is supported
549 and you are going to develop and test your application using the QEMU
550 emulator.</para></listitem>
551 <listitem><para>Build your image if you cannot find a pre-built image that matches
552 your target architecture.
553 If your target architecture is similar to a supported architecture, you can
554 modify the kernel image before you build it.
555 See the
556 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
557 section for an example.</para></listitem>
558 </itemizedlist></para>
559 <para>For information on pre-built kernel image naming schemes for images
560 that can run on the QEMU emulator, see the
561 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
562 section in the Yocto Project Quick Start.</para></listitem>
563 <listitem><para><emphasis>Install the ADT</emphasis>:
564 The ADT provides a target-specific cross-development toolchain, the root filesystem,
565 the QEMU emulator, and other tools that can help you develop your application.
566 While it is possible to get these pieces separately, the ADT Installer provides an
567 easy, inclusive method.
568 You can get these pieces by running an ADT installer script, which is configurable.
569 For information on how to install the ADT, see the
570 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
571 section
572 in the Yocto Project Application Developer's Guide.</para></listitem>
573 <listitem><para><emphasis>If applicable, secure the target root filesystem
574 and the Cross-development toolchain</emphasis>:
575 If you choose not to install the ADT using the ADT Installer,
576 you need to find and download the appropriate root filesystem and
577 the cross-development toolchain.</para>
578 <para>You can find the tarballs for the root filesystem in the same area used
579 for the kernel image.
580 Depending on the type of image you are running, the root filesystem you need differs.
581 For example, if you are developing an application that runs on an image that
582 supports Sato, you need to get a root filesystem that supports Sato.</para>
583 <para>You can find the cross-development toolchains at
584 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
585 Be sure to get the correct toolchain for your development host and your
586 target architecture.
587 See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
588 section in the Yocto Project Application Developer's Guide for information
589 and the
590 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
591 in the Yocto Project Quick Start for information on finding and installing
592 the correct toolchain based on your host development system and your target
593 architecture.
594 </para></listitem>
595 <listitem><para><emphasis>Create and build your application</emphasis>:
596 At this point, you need to have source files for your application.
597 Once you have the files, you can use the Eclipse IDE to import them and build the
598 project.
599 If you are not using Eclipse, you need to use the cross-development tools you have
600 installed to create the image.</para></listitem>
601 <listitem><para><emphasis>Deploy the image with the application</emphasis>:
602 If you are using the Eclipse IDE, you can deploy your image to the hardware or to
603 QEMU through the project's preferences.
604 If you are not using the Eclipse IDE, then you need to deploy the application
605 to the hardware using other methods.
606 Or, if you are using QEMU, you need to use that tool and load your image in for testing.
607 </para></listitem>
608 <listitem><para><emphasis>Test and debug the application</emphasis>:
609 Once your application is deployed, you need to test it.
610 Within the Eclipse IDE, you can use the debugging environment along with the
611 set of user-space tools installed along with the ADT to debug your application.
612 Of course, the same user-space tools are available separately if you choose
613 not to use the Eclipse IDE.</para></listitem>
614 </orderedlist>
615 </para>
616 </section>
617
618 <section id='adt-eclipse'>
619 <title>Working Within Eclipse</title>
620
621 <para>
622 The Eclipse IDE is a popular development environment and it fully
623 supports development using the Yocto Project.
624 <note>
625 This release of the Yocto Project supports both the Kepler
626 and Juno versions of the Eclipse IDE.
627 Thus, the following information provides setup information for
628 both versions.
629 </note>
630 </para>
631
632 <para>
633 When you install and configure the Eclipse Yocto Project Plug-in
634 into the Eclipse IDE, you maximize your Yocto Project experience.
635 Installing and configuring the Plug-in results in an environment
636 that has extensions specifically designed to let you more easily
637 develop software.
638 These extensions allow for cross-compilation, deployment, and
639 execution of your output into a QEMU emulation session as well as
640 actual target hardware.
641 You can also perform cross-debugging and profiling.
642 The environment also supports a suite of tools that allows you
643 to perform remote profiling, tracing, collection of power data,
644 collection of latency data, and collection of performance data.
645 </para>
646
647 <para>
648 This section describes how to install and configure the Eclipse IDE
649 Yocto Plug-in and how to use it to develop your application.
650 </para>
651
652 <section id='setting-up-the-eclipse-ide'>
653 <title>Setting Up the Eclipse IDE</title>
654
655 <para>
656 To develop within the Eclipse IDE, you need to do the following:
657 <orderedlist>
658 <listitem><para>Install the optimal version of the Eclipse
659 IDE.</para></listitem>
660 <listitem><para>Configure the Eclipse IDE.
661 </para></listitem>
662 <listitem><para>Install the Eclipse Yocto Plug-in.
663 </para></listitem>
664 <listitem><para>Configure the Eclipse Yocto Plug-in.
665 </para></listitem>
666 </orderedlist>
667 <note>
668 Do not install Eclipse from your distribution's package
669 repository.
670 Be sure to install Eclipse from the official Eclipse
671 download site as directed in the next section.
672 </note>
673 </para>
674
675 <section id='installing-eclipse-ide'>
676 <title>Installing the Eclipse IDE</title>
677
678 <para>
679 It is recommended that you have the Kepler 4.3.2 version of
680 the Eclipse IDE installed on your development system.
681 However, if you currently have the Juno 4.2 version
682 installed and you do not want to upgrade the IDE, you can
683 configure Juno to work with the Yocto Project.
684 </para>
685
686 <para>
687 If you do not have the Kepler 4.3.2 Eclipse IDE installed,
688 you can find the tarball at
689 <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
690 From that site, choose the Eclipse Standard 4.3.2 version
691 particular to your development host.
692 This version contains the Eclipse Platform, the Java
693 Development Tools (JDT), and the Plug-in Development
694 Environment.
695 </para>
696
697 <para>
698 Once you have downloaded the tarball, extract it into a
699 clean directory.
700 For example, the following commands unpack and install the
701 downloaded Eclipse IDE tarball into a clean directory
702 using the default name <filename>eclipse</filename>:
703 <literallayout class='monospaced'>
704 $ cd ~
705 $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz
706 </literallayout>
707 </para>
708 </section>
709
710 <section id='configuring-the-eclipse-ide'>
711 <title>Configuring the Eclipse IDE</title>
712
713 <para>
714 This section presents the steps needed to configure the
715 Eclipse IDE.
716 </para>
717
718 <para>
719 Before installing and configuring the Eclipse Yocto Plug-in,
720 you need to configure the Eclipse IDE.
721 Follow these general steps:
722 <orderedlist>
723 <listitem><para>Start the Eclipse IDE.</para></listitem>
724 <listitem><para>Make sure you are in your Workbench and
725 select "Install New Software" from the "Help"
726 pull-down menu.</para></listitem>
727 <listitem><para>Select
728 <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
729 from the "Work with:" pull-down menu.
730 <note>
731 For Juno, select
732 <filename>Juno - &ECLIPSE_JUNO_URL;</filename>
733 </note>
734 </para></listitem>
735 <listitem><para>Expand the box next to "Linux Tools"
736 and select the
737 <filename>LTTng - Linux Tracing Toolkit</filename>
738 boxes.</para></listitem>
739 <listitem><para>Expand the box next to "Mobile and
740 Device Development" and select the following boxes:
741 <itemizedlist>
742 <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem>
743 <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
744 <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
745 <listitem><para><filename>Target Management Terminal</filename></para></listitem>
746 <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
747 <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
748 </itemizedlist></para></listitem>
749 <listitem><para>Expand the box next to "Programming
750 Languages" and select the
751 <filename>C/C++ Autotools Support</filename>
752 and <filename>C/C++ Development Tools</filename>
753 boxes.</para></listitem>
754 <listitem><para>Complete the installation and restart
755 the Eclipse IDE.</para></listitem>
756 </orderedlist>
757 </para>
758 </section>
759
760 <section id='installing-the-eclipse-yocto-plug-in'>
761 <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
762
763 <para>
764 You can install the Eclipse Yocto Plug-in into the Eclipse
765 IDE one of two ways: use the Yocto Project's Eclipse
766 Update site to install the pre-built plug-in or build and
767 install the plug-in from the latest source code.
768 </para>
769
770 <section id='new-software'>
771 <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
772
773 <para>
774 To install the Eclipse Yocto Plug-in from the update
775 site, follow these steps:
776 <orderedlist>
777 <listitem><para>Start up the Eclipse IDE.
778 </para></listitem>
779 <listitem><para>In Eclipse, select "Install New
780 Software" from the "Help" menu.
781 </para></listitem>
782 <listitem><para>Click "Add..." in the "Work with:"
783 area.</para></listitem>
784 <listitem><para>Enter
785 <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
786 in the URL field and provide a meaningful name
787 in the "Name" field.
788 <note>
789 If you are using Juno, use
790 <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename>
791 in the URL field.
792 </note></para></listitem>
793 <listitem><para>Click "OK" to have the entry added
794 to the "Work with:" drop-down list.
795 </para></listitem>
796 <listitem><para>Select the entry for the plug-in
797 from the "Work with:" drop-down list.
798 </para></listitem>
799 <listitem><para>Check the boxes next to
800 <filename>Yocto Project ADT Plug-in</filename>,
801 <filename>Yocto Project Bitbake Commander Plug-in</filename>,
802 and
803 <filename>Yocto Project Documentation plug-in</filename>.
804 </para></listitem>
805 <listitem><para>Complete the remaining software
806 installation steps and then restart the Eclipse
807 IDE to finish the installation of the plug-in.
808 </para></listitem>
809 </orderedlist>
810 </para>
811 </section>
812
813 <section id='zip-file-method'>
814 <title>Installing the Plug-in Using the Latest Source Code</title>
815
816 <para>
817 To install the Eclipse Yocto Plug-in from the latest
818 source code, follow these steps:
819 <orderedlist>
820 <listitem><para>Be sure your development system
821 is not using OpenJDK to build the plug-in
822 by doing the following:
823 <orderedlist>
824 <listitem><para>Use the Oracle JDK.
825 If you don't have that, go to
826 <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
827 and download the appropriate tarball
828 for your development system and
829 extract it into your home directory.
830 </para></listitem>
831 <listitem><para>In the shell you are going
832 to do your work, export the location of
833 the Oracle Java as follows:
834 <literallayout class='monospaced'>
835 export PATH=~/jdk1.7.0_40/bin:$PATH
836 </literallayout></para></listitem>
837 </orderedlist></para></listitem>
838 <listitem><para>In the same shell, create a Git
839 repository with:
840 <literallayout class='monospaced'>
841 $ cd ~
842 $ git clone git://git.yoctoproject.org/eclipse-poky-kepler
843 </literallayout>
844 <note>
845 If you are using Juno, the repository is
846 located at
847 <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>.
848 </note>
849 For this example, the repository is named
850 <filename>~/eclipse-poky-kepler</filename>.
851 </para></listitem>
852 <listitem><para>Change to the directory where you
853 set up the Git repository:
854 <literallayout class='monospaced'>
855 $ cd ~/eclipse-poky-kepler
856 </literallayout></para></listitem>
857 <listitem><para>Be sure you are in the right branch
858 for your Git repository.
859 For this release set the branch to
860 <filename>&DISTRO_NAME;</filename>:
861 <literallayout class='monospaced'>
862 $ git checkout &DISTRO_NAME;
863 </literallayout></para></listitem>
864 <listitem><para>Change to the
865 <filename>scripts</filename>
866 directory within the Git repository:
867 <literallayout class='monospaced'>
868 $ cd scripts
869 </literallayout></para></listitem>
870 <listitem><para>Set up the local build environment
871 by running the setup script:
872 <literallayout class='monospaced'>
873 $ ./setup.sh
874 </literallayout></para></listitem>
875 <listitem><para>When the script finishes execution,
876 it prompts you with instructions on how to run
877 the <filename>build.sh</filename> script, which
878 is also in the <filename>scripts</filename>
879 directory of
880 the Git repository created earlier.
881 </para></listitem>
882 <listitem><para>Run the <filename>build.sh</filename> script
883 as directed.
884 Be sure to provide the name of the Git branch
885 along with the Yocto Project release you are
886 using.
887 Here is an example that uses the
888 <filename>&DISTRO_NAME;</filename> branch:
889 <literallayout class='monospaced'>
890 $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
891 </literallayout>
892 After running the script, the file
893 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
894 is in the current directory.</para></listitem>
895 <listitem><para>If necessary, start the Eclipse IDE
896 and be sure you are in the Workbench.
897 </para></listitem>
898 <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
899 </para></listitem>
900 <listitem><para>Click "Add".</para></listitem>
901 <listitem><para>Provide anything you want in the
902 "Name" field.</para></listitem>
903 <listitem><para>Click "Archive" and browse to the
904 ZIP file you built in step eight.
905 This ZIP file should not be "unzipped", and must
906 be the <filename>*archive.zip</filename> file
907 created by running the
908 <filename>build.sh</filename> script.
909 </para></listitem>
910 <listitem><para>Click through the "Okay" buttons.
911 </para></listitem>
912 <listitem><para>Check the boxes
913 in the installation window and complete
914 the installation.</para></listitem>
915 <listitem><para>Restart the Eclipse IDE if
916 necessary.</para></listitem>
917 </orderedlist>
918 </para>
919
920 <para>
921 At this point you should be able to configure the
922 Eclipse Yocto Plug-in as described in the
923 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
924 section.</para>
925 </section>
926 </section>
927
928 <section id='configuring-the-eclipse-yocto-plug-in'>
929 <title>Configuring the Eclipse Yocto Plug-in</title>
930
931 <para>
932 Configuring the Eclipse Yocto Plug-in involves setting the
933 Cross Compiler options and the Target options.
934 The configurations you choose become the default settings
935 for all projects.
936 You do have opportunities to change them later when
937 you configure the project (see the following section).
938 </para>
939
940 <para>
941 To start, you need to do the following from within the
942 Eclipse IDE:
943 <itemizedlist>
944 <listitem><para>Choose "Preferences" from the
945 "Windows" menu to display the Preferences Dialog.
946 </para></listitem>
947 <listitem><para>Click "Yocto Project ADT".
948 </para></listitem>
949 </itemizedlist>
950 </para>
951
952 <section id='configuring-the-cross-compiler-options'>
953 <title>Configuring the Cross-Compiler Options</title>
954
955 <para>
956 To configure the Cross Compiler Options, you must select
957 the type of toolchain, point to the toolchain, specify
958 the sysroot location, and select the target
959 architecture.
960 <itemizedlist>
961 <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
962 Choose between
963 <filename>Standalone pre-built toolchain</filename>
964 and
965 <filename>Build system derived toolchain</filename>
966 for Cross Compiler Options.
967 <itemizedlist>
968 <listitem><para><emphasis>
969 <filename>Standalone Pre-built Toolchain:</filename></emphasis>
970 Select this mode when you are using
971 a stand-alone cross-toolchain.
972 For example, suppose you are an
973 application developer and do not
974 need to build a target image.
975 Instead, you just want to use an
976 architecture-specific toolchain on
977 an existing kernel and target root
978 filesystem.</para></listitem>
979 <listitem><para><emphasis>
980 <filename>Build System Derived Toolchain:</filename></emphasis>
981 Select this mode if the
982 cross-toolchain has been installed
983 and built as part of the
984 <link linkend='build-directory'>Build Directory</link>.
985 When you select
986 <filename>Build system derived toolchain</filename>,
987 you are using the toolchain bundled
988 inside the Build Directory.
989 </para></listitem>
990 </itemizedlist>
991 </para></listitem>
992 <listitem><para><emphasis>Point to the Toolchain:</emphasis>
993 If you are using a stand-alone pre-built
994 toolchain, you should be pointing to where it is
995 installed.
996 If you used the ADT Installer script and
997 accepted the default installation directory, the
998 toolchain will be installed in the
999 <filename>&YOCTO_ADTPATH_DIR;</filename>
1000 directory.
1001 Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>"
1002 and
1003 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1004 in the Yocto Project Application Developer's
1005 Guide describe how to install a stand-alone
1006 cross-toolchain.</para>
1007 <para>If you are using a system-derived
1008 toolchain, the path you provide for the
1009 <filename>Toolchain Root Location</filename>
1010 field is the
1011 <link linkend='build-directory'>Build Directory</link>.
1012 See the
1013 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>"
1014 section in the Yocto Project Application
1015 Developer's Guide for information on how to
1016 install the toolchain into the Build
1017 Directory.</para></listitem>
1018 <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
1019 This location is where the root filesystem for
1020 the target hardware resides.
1021 If you used the ADT Installer script and
1022 accepted the default installation directory,
1023 then the location is
1024 <filename>/opt/poky/&DISTRO;</filename>.
1025 Additionally, when you use the ADT Installer
1026 script, the same location is used for the QEMU
1027 user-space tools and the NFS boot process.
1028 </para>
1029 <para>If you used either of the other two
1030 methods to install the toolchain or did not
1031 accept the ADT Installer script's default
1032 installation directory, then the location of
1033 the sysroot filesystem depends on where you
1034 separately extracted and installed the
1035 filesystem.</para>
1036 <para>For information on how to install the
1037 toolchain and on how to extract and install the
1038 sysroot filesystem, see the
1039 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1040 section in the Yocto Project Application
1041 Developer's Guide.
1042 </para></listitem>
1043 <listitem><para><emphasis>Select the Target Architecture:</emphasis>
1044 The target architecture is the type of hardware
1045 you are going to use or emulate.
1046 Use the pull-down
1047 <filename>Target Architecture</filename> menu
1048 to make your selection.
1049 The pull-down menu should have the supported
1050 architectures.
1051 If the architecture you need is not listed in
1052 the menu, you will need to build the image.
1053 See the
1054 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1055 section of the Yocto Project Quick Start for
1056 more information.</para></listitem>
1057 </itemizedlist>
1058 </para>
1059 </section>
1060
1061 <section id='configuring-the-target-options'>
1062 <title>Configuring the Target Options</title>
1063
1064 <para>
1065 You can choose to emulate hardware using the QEMU
1066 emulator, or you can choose to run your image on actual
1067 hardware.
1068 <itemizedlist>
1069 <listitem><para><emphasis>QEMU:</emphasis>
1070 Select this option if you will be using the
1071 QEMU emulator.
1072 If you are using the emulator, you also need to
1073 locate the kernel and specify any custom
1074 options.</para>
1075 <para>If you selected
1076 <filename>Build system derived toolchain</filename>,
1077 the target kernel you built will be located in
1078 the Build Directory in
1079 <filename>tmp/deploy/images/&lt;machine&gt;</filename>
1080 directory.
1081 If you selected
1082 <filename>Standalone pre-built toolchain</filename>,
1083 the pre-built image you downloaded is located
1084 in the directory you specified when you
1085 downloaded the image.</para>
1086 <para>Most custom options are for advanced QEMU
1087 users to further customize their QEMU instance.
1088 These options are specified between paired
1089 angled brackets.
1090 Some options must be specified outside the
1091 brackets.
1092 In particular, the options
1093 <filename>serial</filename>,
1094 <filename>nographic</filename>, and
1095 <filename>kvm</filename> must all be outside the
1096 brackets.
1097 Use the <filename>man qemu</filename> command
1098 to get help on all the options and their use.
1099 The following is an example:
1100 <literallayout class='monospaced'>
1101 serial ‘&lt;-m 256 -full-screen&gt;’
1102 </literallayout></para>
1103 <para>
1104 Regardless of the mode, Sysroot is already
1105 defined as part of the Cross-Compiler Options
1106 configuration in the
1107 <filename>Sysroot Location:</filename> field.
1108 </para></listitem>
1109 <listitem><para><emphasis>External HW:</emphasis>
1110 Select this option if you will be using actual
1111 hardware.</para></listitem>
1112 </itemizedlist>
1113 </para>
1114
1115 <para>
1116 Click the "OK" to save your plug-in configurations.
1117 </para>
1118 </section>
1119 </section>
1120 </section>
1121
1122 <section id='creating-the-project'>
1123 <title>Creating the Project</title>
1124
1125 <para>
1126 You can create two types of projects: Autotools-based, or
1127 Makefile-based.
1128 This section describes how to create Autotools-based projects
1129 from within the Eclipse IDE.
1130 For information on creating Makefile-based projects in a
1131 terminal window, see the section
1132 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
1133 in the Yocto Project Application Developer's Guide.
1134 <note>
1135 Do not use special characters in project names
1136 (e.g. spaces, underscores, etc.). Doing so can
1137 cause configuration to fail.
1138 </note>
1139 </para>
1140
1141 <para>
1142 To create a project based on a Yocto template and then display
1143 the source code, follow these steps:
1144 <orderedlist>
1145 <listitem><para>Select "Project" from the "File -> New" menu.
1146 </para></listitem>
1147 <listitem><para>Double click <filename>CC++</filename>.
1148 </para></listitem>
1149 <listitem><para>Double click <filename>C Project</filename>
1150 to create the project.</para></listitem>
1151 <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.
1152 </para></listitem>
1153 <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
1154 This is an Autotools-based project based on a Yocto
1155 template.</para></listitem>
1156 <listitem><para>Put a name in the <filename>Project name:</filename>
1157 field.
1158 Do not use hyphens as part of the name.
1159 </para></listitem>
1160 <listitem><para>Click "Next".</para></listitem>
1161 <listitem><para>Add information in the
1162 <filename>Author</filename> and
1163 <filename>Copyright notice</filename> fields.
1164 </para></listitem>
1165 <listitem><para>Be sure the <filename>License</filename>
1166 field is correct.</para></listitem>
1167 <listitem><para>Click "Finish".</para></listitem>
1168 <listitem><para>If the "open perspective" prompt appears,
1169 click "Yes" so that you in the C/C++ perspective.
1170 </para></listitem>
1171 <listitem><para>The left-hand navigation pane shows your
1172 project.
1173 You can display your source by double clicking the
1174 project's source file.</para></listitem>
1175 </orderedlist>
1176 </para>
1177 </section>
1178
1179 <section id='configuring-the-cross-toolchains'>
1180 <title>Configuring the Cross-Toolchains</title>
1181
1182 <para>
1183 The earlier section,
1184 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
1185 sets up the default project configurations.
1186 You can override these settings for a given project by following
1187 these steps:
1188 <orderedlist>
1189 <listitem><para>Select "Change Yocto Project Settings" from
1190 the "Project" menu.
1191 This selection brings up the Yocto Project Settings
1192 Dialog and allows you to make changes specific to an
1193 individual project.</para>
1194 <para>By default, the Cross Compiler Options and Target
1195 Options for a project are inherited from settings you
1196 provided using the Preferences Dialog as described
1197 earlier in the
1198 "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
1199 The Yocto Project Settings Dialog allows you to override
1200 those default settings for a given project.
1201 </para></listitem>
1202 <listitem><para>Make your configurations for the project
1203 and click "OK".
1204 If you are running the Juno version of Eclipse, you can
1205 skip down to the next section where you build the
1206 project.
1207 If you are not working with Juno, you need to reconfigure the
1208 project as described in the next step.
1209 </para></listitem>
1210 <listitem><para>Select "Reconfigure Project" from the
1211 "Project" menu.
1212 This selection reconfigures the project by running
1213 <filename>autogen.sh</filename> in the workspace for
1214 your project.
1215 The script also runs <filename>libtoolize</filename>,
1216 <filename>aclocal</filename>,
1217 <filename>autoconf</filename>,
1218 <filename>autoheader</filename>,
1219 <filename>automake --a</filename>, and
1220 <filename>./configure</filename>.
1221 Click on the "Console" tab beneath your source code to
1222 see the results of reconfiguring your project.
1223 </para></listitem>
1224 </orderedlist>
1225 </para>
1226 </section>
1227
1228 <section id='building-the-project'>
1229 <title>Building the Project</title>
1230
1231 <para>
1232 To build the project in Juno, right click on the project in
1233 the navigator pane and select "Build Project".
1234 If you are not running Juno, select "Build Project" from the
1235 "Project" menu.
1236 The console should update and you can note the cross-compiler
1237 you are using.
1238 </para>
1239 </section>
1240
1241 <section id='starting-qemu-in-user-space-nfs-mode'>
1242 <title>Starting QEMU in User-Space NFS Mode</title>
1243
1244 <para>
1245 To start the QEMU emulator from within Eclipse, follow these
1246 steps:
1247 <orderedlist>
1248 <listitem><para>Expose and select "External Tools" from
1249 the "Run" menu.
1250 Your image should appear as a selectable menu item.
1251 </para></listitem>
1252 <listitem><para>Select your image from the menu to launch
1253 the emulator in a new window.</para></listitem>
1254 <listitem><para>If needed, enter your host root password in
1255 the shell window at the prompt.
1256 This sets up a <filename>Tap 0</filename> connection
1257 needed for running in user-space NFS mode.
1258 </para></listitem>
1259 <listitem><para>Wait for QEMU to launch.</para></listitem>
1260 <listitem><para>Once QEMU launches, you can begin operating
1261 within that environment.
1262 For example, you could determine the IP Address
1263 for the user-space NFS by using the
1264 <filename>ifconfig</filename> command.</para></listitem>
1265 </orderedlist>
1266 </para>
1267 </section>
1268
1269 <section id='deploying-and-debugging-the-application'>
1270 <title>Deploying and Debugging the Application</title>
1271
1272 <para>
1273 Once the QEMU emulator is running the image, you can deploy
1274 your application using the Eclipse IDE and then use
1275 the emulator to perform debugging.
1276 Follow these steps to deploy the application.
1277 <orderedlist>
1278 <listitem><para>Select "Debug Configurations..." from the
1279 "Run" menu.</para></listitem>
1280 <listitem><para>In the left area, expand
1281 <filename>C/C++Remote Application</filename>.
1282 </para></listitem>
1283 <listitem><para>Locate your project and select it to bring
1284 up a new tabbed view in the Debug Configurations Dialog.
1285 </para></listitem>
1286 <listitem><para>Enter the absolute path into which you want
1287 to deploy the application.
1288 Use the "Remote Absolute File Path for
1289 C/C++Application:" field.
1290 For example, enter
1291 <filename>/usr/bin/&lt;programname&gt;</filename>.
1292 </para></listitem>
1293 <listitem><para>Click on the "Debugger" tab to see the
1294 cross-tool debugger you are using.</para></listitem>
1295 <listitem><para>Click on the "Main" tab.</para></listitem>
1296 <listitem><para>Create a new connection to the QEMU instance
1297 by clicking on "new".</para></listitem>
1298 <listitem><para>Select <filename>TCF</filename>, which means
1299 Target Communication Framework.</para></listitem>
1300 <listitem><para>Click "Next".</para></listitem>
1301 <listitem><para>Clear out the "host name" field and enter
1302 the IP Address determined earlier.</para></listitem>
1303 <listitem><para>Click "Finish" to close the
1304 New Connections Dialog.</para></listitem>
1305 <listitem><para>Use the drop-down menu now in the
1306 "Connection" field and pick the IP Address you entered.
1307 </para></listitem>
1308 <listitem><para>Click "Run" to bring up a login screen
1309 and login.</para></listitem>
1310 <listitem><para>Accept the debug perspective.
1311 </para></listitem>
1312 </orderedlist>
1313 </para>
1314 </section>
1315
1316 <section id='running-user-space-tools'>
1317 <title>Running User-Space Tools</title>
1318
1319 <para>
1320 As mentioned earlier in the manual, several tools exist that
1321 enhance your development experience.
1322 These tools are aids in developing and debugging applications
1323 and images.
1324 You can run these user-space tools from within the Eclipse
1325 IDE through the "YoctoTools" menu.
1326 </para>
1327
1328 <para>
1329 Once you pick a tool, you need to configure it for the remote
1330 target.
1331 Every tool needs to have the connection configured.
1332 You must select an existing TCF-based RSE connection to the
1333 remote target.
1334 If one does not exist, click "New" to create one.
1335 </para>
1336
1337 <para>
1338 Here are some specifics about the remote tools:
1339 <itemizedlist>
1340 <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
1341 Selecting this tool causes the
1342 <filename>oprofile-server</filename> on the remote
1343 target to launch on the local host machine.
1344 The <filename>oprofile-viewer</filename> must be
1345 installed on the local host machine and the
1346 <filename>oprofile-server</filename> must be installed
1347 on the remote target, respectively, in order to use.
1348 You must compile and install the
1349 <filename>oprofile-viewer</filename> from the source
1350 code on your local host machine.
1351 Furthermore, in order to convert the target's sample
1352 format data into a form that the host can use, you must
1353 have OProfile version 0.9.4 or greater installed on the
1354 host.</para>
1355 <para>You can locate both the viewer and server from
1356 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1357 You can also find more information on setting up and
1358 using this tool in the
1359 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>"
1360 section of the Yocto Project Profiling and Tracing
1361 Manual.
1362 <note>The <filename>oprofile-server</filename> is
1363 installed by default on the
1364 <filename>core-image-sato-sdk</filename> image.</note>
1365 </para></listitem>
1366 <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
1367 Selecting this tool transfers the remote target's
1368 <filename>Lttng</filename> tracing data back to the
1369 local host machine and uses the Lttng Eclipse plug-in
1370 to graphically display the output.
1371 For information on how to use Lttng to trace an
1372 application,
1373 see <ulink url='http://lttng.org/documentation'></ulink>
1374 and the
1375 "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
1376 section, which is in the Yocto Project Profiling and
1377 Tracing Manual.
1378 <note>Do not use
1379 <filename>Lttng-user space (legacy)</filename> tool.
1380 This tool no longer has any upstream support.</note>
1381 </para>
1382 <para>Before you use the
1383 <filename>Lttng2.0 ust trace import</filename> tool,
1384 you need to setup the Lttng Eclipse plug-in and create a
1385 Tracing project.
1386 Do the following:
1387 <orderedlist>
1388 <listitem><para>Select "Open Perspective" from the
1389 "Window" menu and then select "Tracing".
1390 </para></listitem>
1391 <listitem><para>Click "OK" to change the Eclipse
1392 perspective into the Tracing perspective.
1393 </para></listitem>
1394 <listitem><para>Create a new Tracing project by
1395 selecting "Project" from the "File -> New" menu.
1396 </para></listitem>
1397 <listitem><para>Choose "Tracing Project" from the
1398 "Tracing" menu.
1399 </para></listitem>
1400 <listitem><para>Generate your tracing data on the
1401 remote target.</para></listitem>
1402 <listitem><para>Select "Lttng2.0 ust trace import"
1403 from the "Yocto Project Tools" menu to
1404 start the data import process.</para></listitem>
1405 <listitem><para>Specify your remote connection name.
1406 </para></listitem>
1407 <listitem><para>For the Ust directory path, specify
1408 the location of your remote tracing data.
1409 Make sure the location ends with
1410 <filename>ust</filename> (e.g.
1411 <filename>/usr/mysession/ust</filename>).
1412 </para></listitem>
1413 <listitem><para>Click "OK" to complete the import
1414 process.
1415 The data is now in the local tracing project
1416 you created.</para></listitem>
1417 <listitem><para>Right click on the data and then use
1418 the menu to Select "Generic CTF Trace" from the
1419 "Trace Type... -> Common Trace Format" menu to
1420 map the tracing type.</para></listitem>
1421 <listitem><para>Right click the mouse and select
1422 "Open" to bring up the Eclipse Lttng Trace
1423 Viewer so you view the tracing data.
1424 </para></listitem>
1425 </orderedlist></para></listitem>
1426 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
1427 Selecting this tool runs PowerTOP on the remote target
1428 machine and displays the results in a new view called
1429 PowerTOP.</para>
1430 <para>The "Time to gather data(sec):" field is the time
1431 passed in seconds before data is gathered from the
1432 remote target for analysis.</para>
1433 <para>The "show pids in wakeups list:" field corresponds
1434 to the <filename>-p</filename> argument passed to
1435 <filename>PowerTOP</filename>.</para></listitem>
1436 <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
1437 LatencyTOP identifies system latency, while
1438 Perf monitors the system's performance counter
1439 registers.
1440 Selecting either of these tools causes an RSE terminal
1441 view to appear from which you can run the tools.
1442 Both tools refresh the entire screen to display results
1443 while they run.
1444 For more information on setting up and using
1445 <filename>perf</filename>, see the
1446 "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
1447 section in the Yocto Project Profiling and Tracing
1448 Manual.
1449 </para></listitem>
1450 </itemizedlist>
1451 </para>
1452 </section>
1453
1454 <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
1455 <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
1456
1457 <para>
1458 Within the Eclipse IDE, you can create a Yocto BitBake Commander
1459 project, edit the <link linkend='metadata'>Metadata</link>, and
1460 then use
1461 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE.
1462 </para>
1463
1464 <section id='creating-the-yocto-bitbake-commander-project'>
1465 <title>Creating the Yocto BitBake Commander Project</title>
1466
1467 <para>
1468 To create a Yocto BitBake Commander project, follow these
1469 steps:
1470 <orderedlist>
1471 <listitem><para>Select "Other" from the
1472 "Window -> Open Perspective" menu
1473 and then choose "Bitbake Commander".
1474 </para></listitem>
1475 <listitem><para>Click "OK" to change the perspective to
1476 Bitbake Commander.</para></listitem>
1477 <listitem><para>Select "Project" from the "File -> New"
1478 menu to create a new Yocto
1479 Bitbake Commander project.</para></listitem>
1480 <listitem><para>Choose "New Yocto Project" from the
1481 "Yocto Project Bitbake Commander" menu and click
1482 "Next".</para></listitem>
1483 <listitem><para>Enter the Project Name and choose the
1484 Project Location.
1485 The Yocto project's Metadata files will be put under
1486 the directory
1487 <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
1488 If that directory does not exist, you need to check
1489 the "Clone from Yocto Git Repository" box, which
1490 would execute a <filename>git clone</filename>
1491 command to get the project's Metadata files.
1492 <note>
1493 Do not specify your BitBake Commander project
1494 location as your Eclipse workspace.
1495 Doing so causes an error indicating that the
1496 current project overlaps the location of
1497 another project.
1498 This error occurs even if no such project exits.
1499 </note></para></listitem>
1500 <listitem><para>Select <filename>Finish</filename> to
1501 create the project.</para></listitem>
1502 </orderedlist>
1503 </para>
1504 </section>
1505
1506 <section id='editing-the-metadata'>
1507 <title>Editing the Metadata</title>
1508
1509 <para>
1510 After you create the Yocto Bitbake Commander project, you
1511 can modify the <link linkend='metadata'>Metadata</link>
1512 files by opening them in the project.
1513 When editing recipe files (<filename>.bb</filename> files),
1514 you can view BitBake variable values and information by
1515 hovering the mouse pointer over the variable name and
1516 waiting a few seconds.
1517 </para>
1518
1519 <para>
1520 To edit the Metadata, follow these steps:
1521 <orderedlist>
1522 <listitem><para>Select your Yocto Bitbake Commander
1523 project.</para></listitem>
1524 <listitem><para>Select "BitBake Recipe" from the
1525 "File -> New -> Yocto BitBake Commander" menu
1526 to open a new recipe wizard.</para></listitem>
1527 <listitem><para>Point to your source by filling in the
1528 "SRC_URL" field.
1529 For example, you can add a recipe to your
1530 <link linkend='source-directory'>Source Directory</link>
1531 by defining "SRC_URL" as follows:
1532 <literallayout class='monospaced'>
1533 ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
1534 </literallayout></para></listitem>
1535 <listitem><para>Click "Populate" to calculate the
1536 archive md5, sha256, license checksum values and to
1537 auto-generate the recipe filename.</para></listitem>
1538 <listitem><para>Fill in the "Description" field.
1539 </para></listitem>
1540 <listitem><para>Be sure values for all required
1541 fields exist.</para></listitem>
1542 <listitem><para>Click "Finish".</para></listitem>
1543 </orderedlist>
1544 </para>
1545 </section>
1546
1547 <section id='biding-and-customizing-the-image-using-hob'>
1548 <title>Building and Customizing the Image Using Hob</title>
1549
1550 <para>
1551 To build and customize the image using Hob from within the
1552 Eclipse IDE, follow these steps:
1553 <orderedlist>
1554 <listitem><para>Select your Yocto Bitbake Commander
1555 project.</para></listitem>
1556 <listitem><para>Select "Launch Hob" from the "Project"
1557 menu.</para></listitem>
1558 <listitem><para>Enter the
1559 <link linkend='build-directory'>Build Directory</link>
1560 where you want to put your final images.
1561 </para></listitem>
1562 <listitem><para>Click "OK" to launch Hob.
1563 </para></listitem>
1564 <listitem><para>Use Hob to customize and build your own
1565 images.
1566 For information on Hob, see the
1567 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink>
1568 on the Yocto Project website.</para></listitem>
1569 </orderedlist>
1570 </para>
1571 </section>
1572 </section>
1573 </section>
1574
1575 <section id='workflow-using-stand-alone-cross-development-toolchains'>
1576 <title>Workflow Using Stand-Alone Cross-Development Toolchains</title>
1577
1578 <para>
1579 If you want to develop an application without prior installation
1580 of the ADT, you still can employ the
1581 <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>,
1582 the QEMU emulator, and a number of supported target image files.
1583 You just need to follow these general steps:
1584 <orderedlist>
1585 <listitem><para><emphasis>Install the cross-development
1586 toolchain for your target hardware:</emphasis>
1587 For information on how to install the toolchain, see the
1588 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
1589 section in the Yocto Project Application Developer's
1590 Guide.</para></listitem>
1591 <listitem><para><emphasis>Download the Target Image:</emphasis>
1592 The Yocto Project supports several target architectures
1593 and has many pre-built kernel images and root filesystem
1594 images.</para>
1595 <para>If you are going to develop your application on
1596 hardware, go to the
1597 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
1598 download area and choose a target machine area
1599 from which to download the kernel image and root filesystem.
1600 This download area could have several files in it that
1601 support development using actual hardware.
1602 For example, the area might contain
1603 <filename>.hddimg</filename> files that combine the
1604 kernel image with the filesystem, boot loaders, and
1605 so forth.
1606 Be sure to get the files you need for your particular
1607 development process.</para>
1608 <para>If you are going to develop your application and
1609 then run and test it using the QEMU emulator, go to the
1610 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
1611 download area.
1612 From this area, go down into the directory for your
1613 target architecture (e.g. <filename>qemux86_64</filename>
1614 for an <trademark class='registered'>Intel</trademark>-based
1615 64-bit architecture).
1616 Download kernel, root filesystem, and any other files you
1617 need for your process.
1618 <note>In order to use the root filesystem in QEMU, you
1619 need to extract it.
1620 See the
1621 "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
1622 section for information on how to extract the root
1623 filesystem.</note></para></listitem>
1624 <listitem><para><emphasis>Develop and Test your
1625 Application:</emphasis> At this point, you have the tools
1626 to develop your application.
1627 If you need to separately install and use the QEMU
1628 emulator, you can go to
1629 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
1630 to download and learn about the emulator.</para></listitem>
1631 </orderedlist>
1632 </para>
1633 </section>
1634</section>
1635
1636<section id="modifying-temporary-source-code">
1637 <title>Modifying Temporary Source Code</title>
1638
1639 <para>
1640 You might
1641 find it helpful during development to modify the temporary source code used by recipes
1642 to build packages.
1643 For example, suppose you are developing a patch and you need to experiment a bit
1644 to figure out your solution.
1645 After you have initially built the package, you can iteratively tweak the
1646 source code, which is located in the
1647 <link linkend='build-directory'>Build Directory</link>, and then
1648 you can force a re-compile and quickly test your altered code.
1649 Once you settle on a solution, you can then preserve your changes in the form of
1650 patches.
1651 You can accomplish these steps all within either a
1652 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1653 <link linkend='git'>Git</link> workflow.
1654 </para>
1655
1656 <section id='finding-the-temporary-source-code'>
1657 <title>Finding the Temporary Source Code</title>
1658
1659 <para>
1660 During a build, the unpacked temporary source code used by recipes
1661 to build packages is available in the Build Directory as
1662 defined by the
1663 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
1664 Below is the default value for the <filename>S</filename> variable as defined in the
1665 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1666 <link linkend='source-directory'>Source Directory</link>:
1667 <literallayout class='monospaced'>
1668 S = "${WORKDIR}/${BP}"
1669 </literallayout>
1670 You should be aware that many recipes override the <filename>S</filename> variable.
1671 For example, recipes that fetch their source from Git usually set
1672 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1673 <note>
1674 The
1675 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
1676 represents the base recipe name, which consists of the name and version:
1677 <literallayout class='monospaced'>
1678 BP = "${BPN}-${PV}"
1679 </literallayout>
1680 </note>
1681 </para>
1682
1683 <para>
1684 The path to the work directory for the recipe
1685 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
1686 is defined as follows:
1687 <literallayout class='monospaced'>
1688 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1689 </literallayout>
1690 The actual directory depends on several things:
1691 <itemizedlist>
1692 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1693 The top-level build output directory</listitem>
1694 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1695 The target system identifier</listitem>
1696 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1697 The recipe name</listitem>
1698 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1699 The epoch - (if
1700 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1701 is not specified, which is usually the case for most
1702 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1703 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1704 The recipe version</listitem>
1705 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1706 The recipe revision</listitem>
1707 </itemizedlist>
1708 </para>
1709
1710 <para>
1711 As an example, assume a Source Directory top-level folder
1712 name <filename>poky</filename>, a default Build Directory at
1713 <filename>poky/build</filename>, and a
1714 <filename>qemux86-poky-linux</filename> machine target
1715 system.
1716 Furthermore, suppose your recipe is named
1717 <filename>foo_1.3.0-r0.bb</filename>.
1718 In this case, the work directory the build system uses to
1719 build the package would be as follows:
1720 <literallayout class='monospaced'>
1721 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1722 </literallayout>
1723 </para>
1724
1725 <para>
1726 Now that you know where to locate the directory that has the temporary source code,
1727 you can use a Quilt or Git workflow to make your edits, test the changes,
1728 and preserve the changes in the form of patches.
1729 </para>
1730 </section>
1731
1732 <section id="using-a-quilt-workflow">
1733 <title>Using a Quilt Workflow</title>
1734
1735 <para>
1736 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
1737 is a powerful tool that allows you to capture source code changes without having
1738 a clean source tree.
1739 This section outlines the typical workflow you can use to modify temporary source code,
1740 test changes, and then preserve the changes in the form of a patch all using Quilt.
1741 </para>
1742
1743 <para>
1744 Follow these general steps:
1745 <orderedlist>
1746 <listitem><para><emphasis>Find the Source Code:</emphasis>
1747 The temporary source code used by the OpenEmbedded build system is kept in the
1748 Build Directory.
1749 See the
1750 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1751 section to learn how to locate the directory that has the temporary source code for a
1752 particular package.</para></listitem>
1753 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1754 You need to be in the directory that has the temporary source code.
1755 That directory is defined by the
1756 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1757 variable.</para></listitem>
1758 <listitem><para><emphasis>Create a New Patch:</emphasis>
1759 Before modifying source code, you need to create a new patch.
1760 To create a new patch file, use <filename>quilt new</filename> as below:
1761 <literallayout class='monospaced'>
1762 $ quilt new my_changes.patch
1763 </literallayout></para></listitem>
1764 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1765 After creating the patch, you need to notify Quilt about the files
1766 you plan to edit.
1767 You notify Quilt by adding the files to the patch you just created:
1768 <literallayout class='monospaced'>
1769 $ quilt add file1.c file2.c file3.c
1770 </literallayout>
1771 </para></listitem>
1772 <listitem><para><emphasis>Edit the Files:</emphasis>
1773 Make your changes in the temporary source code to the files you added
1774 to the patch.</para></listitem>
1775 <listitem><para><emphasis>Test Your Changes:</emphasis>
1776 Once you have modified the source code, the easiest way to test your changes
1777 is by calling the <filename>compile</filename> task as shown in the following example:
1778 <literallayout class='monospaced'>
1779 $ bitbake -c compile -f &lt;name_of_package&gt;
1780 </literallayout>
1781 The <filename>-f</filename> or <filename>--force</filename>
1782 option forces the specified task to execute.
1783 If you find problems with your code, you can just keep editing and
1784 re-testing iteratively until things work as expected.
1785 <note>All the modifications you make to the temporary source code
1786 disappear once you <filename>-c clean</filename> or
1787 <filename>-c cleanall</filename> with BitBake for the package.
1788 Modifications will also disappear if you use the <filename>rm_work</filename>
1789 feature as described in the
1790 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1791 section of the Yocto Project Quick Start.
1792 </note></para></listitem>
1793 <listitem><para><emphasis>Generate the Patch:</emphasis>
1794 Once your changes work as expected, you need to use Quilt to generate the final patch that
1795 contains all your modifications.
1796 <literallayout class='monospaced'>
1797 $ quilt refresh
1798 </literallayout>
1799 At this point, the <filename>my_changes.patch</filename> file has all your edits made
1800 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1801 <filename>file3.c</filename> files.</para>
1802 <para>You can find the resulting patch file in the <filename>patches/</filename>
1803 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1804 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1805 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1806 which you can create in the same directory that holds the recipe
1807 (<filename>.bb</filename>) file or the
1808 append (<filename>.bbappend</filename>) file.
1809 Placing the patch here guarantees that the OpenEmbedded build system will find
1810 the patch.
1811 Next, add the patch into the
1812 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1813 of the recipe.
1814 Here is an example:
1815 <literallayout class='monospaced'>
1816 SRC_URI += "file://my_changes.patch"
1817 </literallayout></para></listitem>
1818 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1819 Finally, don't forget to 'bump' the
1820 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1821 value in the recipe since the resulting packages have changed.</para></listitem>
1822 </orderedlist>
1823 </para> </section>
1824
1825 <section id='using-a-git-workflow'>
1826 <title>Using a Git Workflow</title>
1827 <para>
1828 Git is an even more powerful tool that allows you to capture source code changes without having
1829 a clean source tree.
1830 This section outlines the typical workflow you can use to modify temporary source code,
1831 test changes, and then preserve the changes in the form of a patch all using Git.
1832 For general information on Git as it is used in the Yocto Project, see the
1833 "<link linkend='git'>Git</link>" section.
1834 </para>
1835
1836 <note>
1837 This workflow uses Git only for its ability to manage local changes to the source code
1838 and produce patches independent of any version control system used with the Yocto Project.
1839 </note>
1840
1841 <para>
1842 Follow these general steps:
1843 <orderedlist>
1844 <listitem><para><emphasis>Find the Source Code:</emphasis>
1845 The temporary source code used by the OpenEmbedded build system is kept in the
1846 Build Directory.
1847 See the
1848 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1849 section to learn how to locate the directory that has the temporary source code for a
1850 particular package.</para></listitem>
1851 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1852 You need to be in the directory that has the temporary source code.
1853 That directory is defined by the
1854 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1855 variable.</para></listitem>
1856 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
1857 If the recipe you are working with does not use a Git fetcher,
1858 you need to set up a Git repository as follows:
1859 <literallayout class='monospaced'>
1860 $ git init
1861 $ git add *
1862 $ git commit -m "initial revision"
1863 </literallayout>
1864 The above Git commands initialize a Git repository that is based on the
1865 files in your current working directory, stage all the files, and commit
1866 the files.
1867 At this point, your Git repository is aware of all the source code files.
1868 Any edits you now make to files can be committed later and will be tracked by
1869 Git.</para></listitem>
1870 <listitem><para><emphasis>Edit the Files:</emphasis>
1871 Make your changes to the temporary source code.</para></listitem>
1872 <listitem><para><emphasis>Test Your Changes:</emphasis>
1873 Once you have modified the source code, the easiest way to test your changes
1874 is by calling the <filename>compile</filename> task as shown in the following example:
1875 <literallayout class='monospaced'>
1876 $ bitbake -c compile -f &lt;name_of_package&gt;
1877 </literallayout>
1878 The <filename>-f</filename> or <filename>--force</filename>
1879 option forces the specified task to execute.
1880 If you find problems with your code, you can just keep editing and
1881 re-testing iteratively until things work as expected.
1882 <note>All the modifications you make to the temporary source code
1883 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
1884 or <filename>-c cleanall</filename> with BitBake for the package.
1885 Modifications will also disappear if you use the <filename>rm_work</filename>
1886 feature as described in the
1887 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1888 section of the Yocto Project Quick Start.
1889 </note></para></listitem>
1890 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1891 Use the <filename>git status</filename> command to see what files you have actually edited.
1892 The ability to have Git track the files you have changed is an advantage that this
1893 workflow has over the Quilt workflow.
1894 Here is the Git command to list your changed files:
1895 <literallayout class='monospaced'>
1896 $ git status
1897 </literallayout></para></listitem>
1898 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1899 Use the <filename>git add</filename> command to stage the changed files so they
1900 can be committed as follows:
1901 <literallayout class='monospaced'>
1902 $ git add file1.c file2.c file3.c
1903 </literallayout></para></listitem>
1904 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1905 Use the <filename>git commit</filename> command to commit the changes to the
1906 local repository.
1907 Once you have committed the files, you can use the <filename>git log</filename>
1908 command to see your changes:
1909 <literallayout class='monospaced'>
1910 $ git commit -m "&lt;commit-summary-message&gt;"
1911 $ git log
1912 </literallayout>
1913 <note>The name of the patch file created in the next step is based on your
1914 <filename>commit-summary-message</filename>.</note></para></listitem>
1915 <listitem><para><emphasis>Generate the Patch:</emphasis>
1916 Once the changes are committed, use the <filename>git format-patch</filename>
1917 command to generate a patch file:
1918 <literallayout class='monospaced'>
1919 $ git format-patch -1
1920 </literallayout>
1921 Specifying "-1" causes Git to generate the
1922 patch file for the most recent commit.</para>
1923 <para>At this point, the patch file has all your edits made
1924 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1925 <filename>file3.c</filename> files.
1926 You can find the resulting patch file in the current directory and it
1927 is named according to the <filename>git commit</filename> summary line.
1928 The patch file ends with <filename>.patch</filename>.</para></listitem>
1929 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1930 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1931 which you can create in the same directory that holds the recipe
1932 (<filename>.bb</filename>) file or the
1933 append (<filename>.bbappend</filename>) file.
1934 Placing the patch here guarantees that the OpenEmbedded build system will find
1935 the patch.
1936 Next, add the patch into the
1937 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1938 of the recipe.
1939 Here is an example:
1940 <literallayout class='monospaced'>
1941 SRC_URI += "file://0001-&lt;commit-summary-message&gt;.patch"
1942 </literallayout></para></listitem>
1943 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1944 Finally, don't forget to 'bump' the
1945 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1946 value in the recipe since the resulting packages have changed.</para></listitem>
1947 </orderedlist>
1948 </para>
1949 </section>
1950</section>
1951
1952<section id='image-development-using-hob'>
1953 <title>Image Development Using Hob</title>
1954
1955 <para>
1956 The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the
1957 OpenEmbedded build system, which is based on BitBake.
1958 You can use the Hob to build custom operating system images within the Yocto Project build environment.
1959 Hob simply provides a friendly interface over the build system used during development.
1960 In other words, building images with the Hob lets you take care of common build tasks more easily.
1961 </para>
1962
1963 <para>
1964 For a better understanding of Hob, see the project page at
1965 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink>
1966 on the Yocto Project website.
1967 If you follow the "Documentation" link from the Hob page, you will
1968 find a short introductory training video on Hob.
1969 The following lists some features of Hob:
1970 <itemizedlist>
1971 <listitem><para>You can setup and run Hob using these commands:
1972 <literallayout class='monospaced'>
1973 $ source oe-init-build-env
1974 $ hob
1975 </literallayout></para></listitem>
1976 <listitem><para>You can set the
1977 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1978 for which you are building the image.</para></listitem>
1979 <listitem><para>You can modify various policy settings such as the
1980 package format with which to build,
1981 the parallelism BitBake uses, whether or not to build an
1982 external toolchain, and which host to build against.
1983 </para></listitem>
1984 <listitem><para>You can manage
1985 <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
1986 <listitem><para>You can select a base image and then add extra packages for your custom build.
1987 </para></listitem>
1988 <listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
1989 </itemizedlist>
1990 </para>
1991</section>
1992
1993<section id="platdev-appdev-devshell">
1994 <title>Using a Development Shell</title>
1995
1996 <para>
1997 When debugging certain commands or even when just editing packages,
1998 <filename>devshell</filename> can be a useful tool.
1999 When you invoke <filename>devshell</filename>, source files are
2000 extracted into your working directory and patches are applied.
2001 Then, a new terminal is opened and you are placed in the working directory.
2002 In the new terminal, all the OpenEmbedded build-related environment variables are
2003 still defined so you can use commands such as <filename>configure</filename> and
2004 <filename>make</filename>.
2005 The commands execute just as if the OpenEmbedded build system were executing them.
2006 Consequently, working this way can be helpful when debugging a build or preparing
2007 software to be used with the OpenEmbedded build system.
2008 </para>
2009
2010 <para>
2011 Following is an example that uses <filename>devshell</filename> on a target named
2012 <filename>matchbox-desktop</filename>:
2013 <literallayout class='monospaced'>
2014 $ bitbake matchbox-desktop -c devshell
2015 </literallayout>
2016 </para>
2017
2018 <para>
2019 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
2020 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
2021 variable controls what type of shell is opened.
2022 </para>
2023
2024 <para>
2025 For spawned terminals, the following occurs:
2026 <itemizedlist>
2027 <listitem><para>The <filename>PATH</filename> variable includes the
2028 cross-toolchain.</para></listitem>
2029 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
2030 <filename>.pc</filename> files.</para></listitem>
2031 <listitem><para>The <filename>configure</filename> command finds the
2032 Yocto Project site files as well as any other necessary files.</para></listitem>
2033 </itemizedlist>
2034 </para>
2035
2036 <para>
2037 Within this environment, you can run configure or compile
2038 commands as if they were being run by
2039 the OpenEmbedded build system itself.
2040 As noted earlier, the working directory also automatically changes to the
2041 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
2042 </para>
2043
2044 <para>
2045 When you are finished, you just exit the shell or close the terminal window.
2046 </para>
2047
2048 <note>
2049 <para>
2050 It is worth remembering that when using <filename>devshell</filename>
2051 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
2052 instead of just using <filename>gcc</filename>.
2053 The same applies to other applications such as <filename>binutils</filename>,
2054 <filename>libtool</filename> and so forth.
2055 BitBake sets up environment variables such as <filename>CC</filename>
2056 to assist applications, such as <filename>make</filename> to find the correct tools.
2057 </para>
2058
2059 <para>
2060 It is also worth noting that <filename>devshell</filename> still works over
2061 X11 forwarding and similar situations.
2062 </para>
2063 </note>
2064</section>
2065
2066</chapter>
2067<!--
2068vim: expandtab tw=80 ts=4
2069-->
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
new file mode 100644
index 0000000000..37fa5afdd5
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -0,0 +1,1687 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='dev-manual-newbie'>
6
7<title>The Yocto Project Open Source Development Environment</title>
8
9<para>
10 This chapter helps you understand the Yocto Project as an open source development project.
11 In general, working in an open source environment is very different from working in a
12 closed, proprietary environment.
13 Additionally, the Yocto Project uses specific tools and constructs as part of its development
14 environment.
15 This chapter specifically addresses open source philosophy, using the
16 Yocto Project in a team environment, source repositories, Yocto Project
17 terms, licensing, the open source distributed version control system Git,
18 workflows, bug tracking, and how to submit changes.
19</para>
20
21<section id='open-source-philosophy'>
22 <title>Open Source Philosophy</title>
23
24 <para>
25 Open source philosophy is characterized by software development directed by peer production
26 and collaboration through an active community of developers.
27 Contrast this to the more standard centralized development models used by commercial software
28 companies where a finite set of developers produces a product for sale using a defined set
29 of procedures that ultimately result in an end product whose architecture and source material
30 are closed to the public.
31 </para>
32
33 <para>
34 Open source projects conceptually have differing concurrent agendas, approaches, and production.
35 These facets of the development process can come from anyone in the public (community) that has a
36 stake in the software project.
37 The open source environment contains new copyright, licensing, domain, and consumer issues
38 that differ from the more traditional development environment.
39 In an open source environment, the end product, source material, and documentation are
40 all available to the public at no cost.
41 </para>
42
43 <para>
44 A benchmark example of an open source project is the Linux Kernel, which was initially conceived
45 and created by Finnish computer science student Linus Torvalds in 1991.
46 Conversely, a good example of a non-open source project is the
47 <trademark class='registered'>Windows</trademark> family of operating
48 systems developed by <trademark class='registered'>Microsoft</trademark> Corporation.
49 </para>
50
51 <para>
52 Wikipedia has a good historical description of the Open Source Philosophy
53 <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
54 You can also find helpful information on how to participate in the Linux Community
55 <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
56 </para>
57</section>
58
59<section id="usingpoky-changes-collaborate">
60 <title>Using the Yocto Project in a Team Environment</title>
61
62 <para>
63 It might not be immediately clear how you can use the Yocto
64 Project in a team environment, or scale it for a large team of
65 developers.
66 One of the strengths of the Yocto Project is that it is extremely
67 flexible.
68 Thus, you can adapt it to many different use cases and scenarios.
69 However, these characteristics can cause a struggle if you are trying
70 to create a working setup that scales across a large team.
71 </para>
72
73 <para>
74 To help with these types of situations, this section presents
75 some of the project's most successful experiences,
76 practices, solutions, and available technologies that work well.
77 Keep in mind, the information here is a starting point.
78 You can build off it and customize it to fit any
79 particular working environment and set of practices.
80 </para>
81
82 <section id='best-practices-system-configurations'>
83 <title>System Configurations</title>
84
85 <para>
86 Systems across a large team should meet the needs of
87 two types of developers: those working on the contents of the
88 operating system image itself and those developing applications.
89 Regardless of the type of developer, their workstations must
90 be both reasonably powerful and run Linux.
91 </para>
92
93 <section id='best-practices-application-development'>
94 <title>Application Development</title>
95
96 <para>
97 For developers who mainly do application level work
98 on top of an existing software stack,
99 here are some practices that work best:
100 <itemizedlist>
101 <listitem><para>Use a pre-built toolchain that
102 contains the software stack itself.
103 Then, develop the application code on top of the
104 stack.
105 This method works well for small numbers of relatively
106 isolated applications.</para></listitem>
107 <listitem><para>When possible, use the Yocto Project
108 plug-in for the <trademark class='trade'>Eclipse</trademark> IDE
109 and other pieces of Application Development
110 Technology (ADT).
111 For more information, see the
112 "<link linkend='application-development-workflow'>Application
113 Development Workflow</link>" section as well as the
114 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
115 </para></listitem>
116 <listitem><para>Keep your cross-development toolchains
117 updated.
118 You can do this through provisioning either as new
119 toolchain downloads or as updates through a package
120 update mechanism using <filename>opkg</filename>
121 to provide updates to an existing toolchain.
122 The exact mechanics of how and when to do this are a
123 question for local policy.</para></listitem>
124 <listitem><para>Use multiple toolchains installed locally
125 into different locations to allow development across
126 versions.</para></listitem>
127 </itemizedlist>
128 </para>
129 </section>
130
131 <section id='best-practices-core-system-development'>
132 <title>Core System Development</title>
133
134 <para>
135 For core system development, it is often best to have the
136 build system itself available on the developer workstations
137 so developers can run their own builds and directly
138 rebuild the software stack.
139 You should keep the core system unchanged as much as
140 possible and do your work in layers on top of the core system.
141 Doing so gives you a greater level of portability when
142 upgrading to new versions of the core system or Board
143 Support Packages (BSPs).
144 You can share layers amongst the developers of a particular
145 project and contain the policy configuration that defines
146 the project.
147 </para>
148
149 <para>
150 Aside from the previous best practices, there exists a number
151 of tips and tricks that can help speed up core development
152 projects:
153 <itemizedlist>
154 <listitem><para>Use a
155 <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>
156 (sstate) among groups of developers who are on a
157 fast network.
158 The best way to share sstate is through a
159 Network File System (NFS) share.
160 The first user to build a given component for the
161 first time contributes that object to the sstate,
162 while subsequent builds from other developers then
163 reuse the object rather than rebuild it themselves.
164 </para>
165 <para>Although it is possible to use other protocols for the
166 sstate such as HTTP and FTP, you should avoid these.
167 Using HTTP limits the sstate to read-only and
168 FTP provides poor performance.
169 </para></listitem>
170 <listitem><para>Have autobuilders contribute to the sstate
171 pool similarly to how the developer workstations
172 contribute.
173 For information, see the
174 "<link linkend='best-practices-autobuilders'>Autobuilders</link>"
175 section.</para></listitem>
176 <listitem><para>Build stand-alone tarballs that contain
177 "missing" system requirements if for some reason
178 developer workstations do not meet minimum system
179 requirements such as latest Python versions,
180 <filename>chrpath</filename>, or other tools.
181 You can install and relocate the tarball exactly as you
182 would the usual cross-development toolchain so that
183 all developers can meet minimum version requirements
184 on most distributions.</para></listitem>
185 <listitem><para>Use a small number of shared,
186 high performance systems for testing purposes
187 (e.g. dual, six-core Xeons with 24 Gbytes of RAM
188 and plenty of disk space).
189 Developers can use these systems for wider, more
190 extensive testing while they continue to develop
191 locally using their primary development system.
192 </para></listitem>
193 <listitem><para>Enable the PR Service when package feeds
194 need to be incremental with continually increasing
195 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink>
196 values.
197 Typically, this situation occurs when you use or
198 publish package feeds and use a shared state.
199 You should enable the PR Service for all users who
200 use the shared state pool.
201 For more information on the PR Service, see the
202 "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
203 </para></listitem>
204 </itemizedlist>
205 </para>
206 </section>
207 </section>
208
209 <section id='best-practices-source-control-management'>
210 <title>Source Control Management (SCM)</title>
211
212 <para>
213 Keeping your
214 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
215 and any software you are developing under the
216 control of an SCM system that is compatible
217 with the OpenEmbedded build system is advisable.
218 Of the SCMs BitBake supports, the
219 Yocto Project team strongly recommends using
220 <link linkend='git'>Git</link>.
221 Git is a distributed system that is easy to backup,
222 allows you to work remotely, and then connects back to the
223 infrastructure.
224 <note>
225 For information about BitBake, see the
226 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
227 </note>
228 </para>
229
230 <para>
231 It is relatively easy to set up Git services and create
232 infrastructure like
233 <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
234 which is based on server software called
235 <filename>gitolite</filename> with <filename>cgit</filename>
236 being used to generate the web interface that lets you view the
237 repositories.
238 The <filename>gitolite</filename> software identifies users
239 using SSH keys and allows branch-based
240 access controls to repositories that you can control as little
241 or as much as necessary.
242 </para>
243
244 <note>
245 The setup of these services is beyond the scope of this manual.
246 However, sites such as these exist that describe how to perform
247 setup:
248 <itemizedlist>
249 <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
250 Describes how to install <filename>gitolite</filename>
251 on the server.</para></listitem>
252 <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
253 All topics for <filename>gitolite</filename>.
254 </para></listitem>
255 <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
256 Documentation on how to create interfaces and frontends
257 for Git.</para></listitem>
258 </itemizedlist>
259 </note>
260 </section>
261
262 <section id='best-practices-autobuilders'>
263 <title>Autobuilders</title>
264
265 <para>
266 Autobuilders are often the core of a development project.
267 It is here that changes from individual developers are brought
268 together and centrally tested and subsequent decisions about
269 releases can be made.
270 Autobuilders also allow for "continuous integration" style
271 testing of software components and regression identification
272 and tracking.
273 </para>
274
275 <para>
276 See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
277 for more information and links to buildbot.
278 The Yocto Project team has found this implementation
279 works well in this role.
280 A public example of this is the Yocto Project
281 Autobuilders, which we use to test the overall health of the
282 project.
283 </para>
284
285 <para>
286 The features of this system are:
287 <itemizedlist>
288 <listitem><para>Highlights when commits break the build.
289 </para></listitem>
290 <listitem><para>Populates an sstate cache from which
291 developers can pull rather than requiring local
292 builds.</para></listitem>
293 <listitem><para>Allows commit hook triggers,
294 which trigger builds when commits are made.
295 </para></listitem>
296 <listitem><para>Allows triggering of automated image booting
297 and testing under the QuickEMUlator (QEMU).
298 </para></listitem>
299 <listitem><para>Supports incremental build testing and
300 from-scratch builds.</para></listitem>
301 <listitem><para>Shares output that allows developer
302 testing and historical regression investigation.
303 </para></listitem>
304 <listitem><para>Creates output that can be used for releases.
305 </para></listitem>
306 <listitem><para>Allows scheduling of builds so that resources
307 can be used efficiently.</para></listitem>
308 </itemizedlist>
309 </para>
310 </section>
311
312 <section id='best-practices-policies-and-change-flow'>
313 <title>Policies and Change Flow</title>
314
315 <para>
316 The Yocto Project itself uses a hierarchical structure and a
317 pull model.
318 Scripts exist to create and send pull requests
319 (i.e. <filename>create-pull-request</filename> and
320 <filename>send-pull-request</filename>).
321 This model is in line with other open source projects where
322 maintainers are responsible for specific areas of the project
323 and a single maintainer handles the final "top-of-tree" merges.
324 </para>
325
326 <note>
327 You can also use a more collective push model.
328 The <filename>gitolite</filename> software supports both the
329 push and pull models quite easily.
330 </note>
331
332 <para>
333 As with any development environment, it is important
334 to document the policy used as well as any main project
335 guidelines so they are understood by everyone.
336 It is also a good idea to have well structured
337 commit messages, which are usually a part of a project's
338 guidelines.
339 Good commit messages are essential when looking back in time and
340 trying to understand why changes were made.
341 </para>
342
343 <para>
344 If you discover that changes are needed to the core layer of the
345 project, it is worth sharing those with the community as soon
346 as possible.
347 Chances are if you have discovered the need for changes, someone
348 else in the community needs them also.
349 </para>
350 </section>
351
352 <section id='best-practices-summary'>
353 <title>Summary</title>
354
355 <para>
356 This section summarizes the key recommendations described in the
357 previous sections:
358 <itemizedlist>
359 <listitem><para>Use <link linkend='git'>Git</link>
360 as the source control system.</para></listitem>
361 <listitem><para>Maintain your Metadata in layers that make sense
362 for your situation.
363 See the "<link linkend='understanding-and-creating-layers'>Understanding
364 and Creating Layers</link>" section for more information on
365 layers.</para></listitem>
366 <listitem><para>
367 Separate the project's Metadata and code by using
368 separate Git repositories.
369 See the
370 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
371 section for information on these repositories.
372 See the
373 "<link linkend='getting-setup'>Getting Set Up</link>"
374 section for information on how to set up local Git
375 repositories for related upstream Yocto Project
376 Git repositories.
377 </para></listitem>
378 <listitem><para>Set up the directory for the shared state cache
379 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
380 where it makes sense.
381 For example, set up the sstate cache on a system used
382 by developers in the same organization and share the
383 same source directories on their machines.
384 </para></listitem>
385 <listitem><para>Set up an Autobuilder and have it populate the
386 sstate cache and source directories.</para></listitem>
387 <listitem><para>The Yocto Project community encourages you
388 to send patches to the project to fix bugs or add features.
389 If you do submit patches, follow the project commit
390 guidelines for writing good commit messages.
391 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
392 section.</para></listitem>
393 <listitem><para>Send changes to the core sooner than later
394 as others are likely to run into the same issues.
395 For some guidance on mailing lists to use, see the list in the
396 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
397 section.
398 For a description of the available mailing lists, see the
399 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
400 section in the Yocto Project Reference Manual.
401 </para></listitem>
402 </itemizedlist>
403 </para>
404 </section>
405</section>
406
407<section id='yocto-project-repositories'>
408 <title>Yocto Project Source Repositories</title>
409
410 <para>
411 The Yocto Project team maintains complete source repositories for all
412 Yocto Project files at
413 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
414 This web-based source code browser is organized into categories by
415 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
416 so forth.
417 From the interface, you can click on any particular item in the "Name"
418 column and see the URL at the bottom of the page that you need to clone
419 a Git repository for that particular item.
420 Having a local Git repository of the
421 <link linkend='source-directory'>Source Directory</link>, which is
422 usually named "poky", allows
423 you to make changes, contribute to the history, and ultimately enhance
424 the Yocto Project's tools, Board Support Packages, and so forth.
425 </para>
426
427 <para>
428 For any supported release of Yocto Project, you can also go to the
429 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
430 select the "Downloads" tab and get a released tarball of the
431 <filename>poky</filename> repository or any supported BSP tarballs.
432 Unpacking these tarballs gives you a snapshot of the released
433 files.
434 <note><title>Notes</title>
435 <itemizedlist>
436 <listitem><para>
437 The recommended method for setting up the Yocto Project
438 <link linkend='source-directory'>Source Directory</link>
439 and the files for supported BSPs
440 (e.g., <filename>meta-intel</filename>) is to use
441 <link linkend='git'>Git</link> to create a local copy of
442 the upstream repositories.
443 </para></listitem>
444 <listitem><para>
445 Be sure to always work in matching branches for both
446 the <filename>meta-intel</filename> repository and the
447 <link linkend='source-directory'>Source Directory</link>
448 (i.e. <filename>poky</filename>) repository.
449 For example, if you have checked out the "master" branch
450 of <filename>poky</filename> and you are going to use
451 <filename>meta-intel</filename>, be sure to checkout the
452 "master" branch of <filename>meta-intel</filename>.
453 </para></listitem>
454 </itemizedlist>
455 </note>
456 </para>
457
458 <para>
459 In summary, here is where you can get the project files needed for development:
460 <itemizedlist>
461 <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
462 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
463 Metadata Layers.
464 You can create local copies of Git repositories for each of these areas.</para>
465 <para>
466 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
467 </para></listitem>
468 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
469 This is an index of releases such as
470 the <trademark class='trade'>Eclipse</trademark>
471 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains,
472 and all released versions of Yocto Project in the form of images or tarballs.
473 Downloading and extracting these files does not produce a local copy of the
474 Git repository but rather a snapshot of a particular release or image.</para>
475 <para>
476 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
477 </para></listitem>
478 <listitem><para><emphasis>"Downloads" page for the
479 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis>
480 Access this page by going to the website and then selecting
481 the "Downloads" tab.
482 This page allows you to download any Yocto Project
483 release or Board Support Package (BSP) in tarball form.
484 The tarballs are similar to those found in the
485 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
486 <para>
487 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
488 </para></listitem>
489 </itemizedlist>
490 </para>
491</section>
492
493<section id='yocto-project-terms'>
494 <title>Yocto Project Terms</title>
495
496 <para>
497 Following is a list of terms and definitions users new to the Yocto Project development
498 environment might find helpful.
499 While some of these terms are universal, the list includes them just in case:
500 <itemizedlist>
501 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
502 a recipe file.
503 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
504 The OpenEmbedded build system expects every append file to have a corresponding
505 recipe (<filename>.bb</filename>) file.
506 Furthermore, the append file and corresponding recipe file
507 must use the same root filename.
508 The filenames can differ only in the file type suffix used (e.g.
509 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
510 </para>
511 <para>Information in append files overrides the information in the similarly-named recipe file.
512 For an example of an append file in use, see the
513 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
514 </para></listitem>
515 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
516 The task executor and scheduler used by the OpenEmbedded build
517 system to build images.
518 For more information on BitBake, see the
519 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
520 </para></listitem>
521 <listitem>
522 <para id='build-directory'><emphasis>Build Directory:</emphasis>
523 This term refers to the area used by the OpenEmbedded build
524 system for builds.
525 The area is created when you <filename>source</filename> the
526 setup environment script that is found in the Source Directory
527 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
528 or
529 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
530 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
531 variable points to the Build Directory.</para>
532
533 <para>
534 You have a lot of flexibility when creating the Build
535 Directory.
536 Following are some examples that show how to create the
537 directory.
538 The examples assume your
539 <link linkend='source-directory'>Source Directory</link> is
540 named <filename>poky</filename>:
541 <itemizedlist>
542 <listitem><para>Create the Build Directory inside your
543 Source Directory and let the name of the Build
544 Directory default to <filename>build</filename>:
545 <literallayout class='monospaced'>
546 $ cd $HOME/poky
547 $ source &OE_INIT_FILE;
548 </literallayout></para></listitem>
549 <listitem><para>Create the Build Directory inside your
550 home directory and specifically name it
551 <filename>test-builds</filename>:
552 <literallayout class='monospaced'>
553 $ cd $HOME
554 $ source poky/&OE_INIT_FILE; test-builds
555 </literallayout></para></listitem>
556 <listitem><para>
557 Provide a directory path and
558 specifically name the Build Directory.
559 Any intermediate folders in the pathname must
560 exist.
561 This next example creates a Build Directory named
562 <filename>YP-&POKYVERSION;</filename>
563 in your home directory within the existing
564 directory <filename>mybuilds</filename>:
565 <literallayout class='monospaced'>
566 $cd $HOME
567 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
568 </literallayout></para></listitem>
569 </itemizedlist>
570 <note>
571 By default, the Build Directory contains
572 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
573 which is a temporary directory the build system uses for
574 its work.
575 <filename>TMPDIR</filename> cannot be under NFS.
576 Thus, by default, the Build Directory cannot be under NFS.
577 However, if you need the Build Directory to be under NFS,
578 you can set this up by setting <filename>TMPDIR</filename>
579 in your <filename>local.conf</filename> file
580 to use a local drive.
581 Doing so effectively separates <filename>TMPDIR</filename>
582 from <filename>TOPDIR</filename>, which is the Build
583 Directory.
584 </note>
585 </para></listitem>
586 <listitem><para id='build-system-term'><emphasis>Build System:</emphasis>
587 In the context of the Yocto Project,
588 this term refers to the OpenEmbedded build system used by the project.
589 This build system is based on the project known as "Poky."
590 For some historical information about Poky, see the
591 <link linkend='poky'>Poky</link> term.
592 </para></listitem>
593 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
594 and inheritance so that commonly used patterns can be defined once and then easily used
595 in multiple recipes.
596 For reference information on the Yocto Project classes, see the
597 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
598 Yocto Project Reference Manual.
599 Class files end with the <filename>.bbclass</filename> filename extension.
600 </para></listitem>
601 <listitem><para><emphasis>Configuration File:</emphasis>
602 Configuration information in various <filename>.conf</filename>
603 files provides global definitions of variables.
604 The <filename>conf/local.conf</filename> configuration file in
605 the
606 <link linkend='build-directory'>Build Directory</link>
607 contains user-defined variables that affect every build.
608 The <filename>meta-yocto/conf/distro/poky.conf</filename>
609 configuration file defines Yocto "distro" configuration
610 variables used only when building with this policy.
611 Machine configuration files, which
612 are located throughout the
613 <link linkend='source-directory'>Source Directory</link>, define
614 variables for specific hardware and are only used when building
615 for that target (e.g. the
616 <filename>machine/beaglebone.conf</filename> configuration
617 file defines variables for the Texas Instruments ARM Cortex-A8
618 development board).
619 Configuration files end with a <filename>.conf</filename>
620 filename extension.
621 </para></listitem>
622 <listitem><para id='cross-development-toolchain'>
623 <emphasis>Cross-Development Toolchain:</emphasis>
624 In general, a cross-development toolchain is a collection of
625 software development tools and utilities that run on one
626 architecture and allow you to develop software for a
627 different, or targeted, architecture.
628 These toolchains contain cross-compilers, linkers, and
629 debuggers that are specific to the target architecture.
630 </para>
631
632 <para>The Yocto Project supports two different cross-development
633 toolchains:
634 <itemizedlist>
635 <listitem><para>A toolchain only used by and within
636 BitBake when building an image for a target
637 architecture.</para></listitem>
638 <listitem><para>A relocatable toolchain used outside of
639 BitBake by developers when developing applications
640 that will run on a targeted device.
641 Sometimes this relocatable cross-development
642 toolchain is referred to as the meta-toolchain.
643 </para></listitem>
644 </itemizedlist>
645 </para>
646
647 <para>
648 Creation of these toolchains is simple and automated.
649 For information on toolchain concepts as they apply to the
650 Yocto Project, see the
651 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
652 section in the Yocto Project Reference Manual.
653 You can also find more information on using the
654 relocatable toolchain in the
655 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
656 Application Developer's Guide</ulink>.
657 </para></listitem>
658 <listitem><para><emphasis>Image:</emphasis>
659 An image is the result produced when BitBake processes a given
660 collection of recipes and related Metadata.
661 Images are the binary output that run on specific hardware or
662 QEMU and are used for specific use-cases.
663 For a list of the supported image types that the Yocto Project provides, see the
664 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
665 chapter in the Yocto Project Reference Manual.</para></listitem>
666 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
667 a BSP, or an application stack.
668 For a discussion on BSP Layers, see the
669 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
670 section in the Yocto Project Board Support Packages (BSP)
671 Developer's Guide.</para></listitem>
672 <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis>
673 A term sometimes used for
674 <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
675 </para></listitem>
676 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
677 The files that BitBake parses when building an image.
678 In general, Metadata includes recipes, classes, and
679 configuration files.
680 In the context of the kernel ("kernel Metadata"),
681 it refers to Metadata in the <filename>meta</filename>
682 branches of the kernel source Git repositories.
683 </para></listitem>
684 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
685 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
686 This Metadata is found in the <filename>meta</filename> directory of the
687 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
688 <listitem><para><emphasis>Package:</emphasis>
689 In the context of the Yocto Project, this term refers a
690 recipe's packaged output produced by BitBake (i.e. a
691 "baked recipe").
692 A package is generally the compiled binaries produced from the
693 recipe's sources.
694 You "bake" something by running it through BitBake.</para>
695 <para>It is worth noting that the term "package" can, in general, have subtle
696 meanings. For example, the packages referred to in the
697 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are
698 compiled binaries that when installed add functionality to your Linux
699 distribution.</para>
700 <para>Another point worth noting is that historically within the Yocto Project,
701 recipes were referred to as packages - thus, the existence of several BitBake
702 variables that are seemingly mis-named,
703 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
704 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
705 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
706 </para></listitem>
707 <listitem><para><emphasis>Package Groups:</emphasis>
708 Arbitrary groups of software Recipes.
709 You use package groups to hold recipes that, when built,
710 usually accomplish a single task.
711 For example, a package group could contain the recipes for a
712 company’s proprietary or value-add software.
713 Or, the package group could contain the recipes that enable
714 graphics.
715 A package group is really just another recipe.
716 Because package group files are recipes, they end with the
717 <filename>.bb</filename> filename extension.</para></listitem>
718 <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
719 In its most general sense, it is an open-source project that was initially developed
720 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
721 build system becoming a build system for embedded images.
722 After Intel Corporation acquired OpenedHand, the project poky became the basis for
723 the Yocto Project's build system.</para>
724 <para>
725 Within the Yocto Project source repositories, <filename>poky</filename>
726 exists as a separate Git repository
727 that can be cloned to yield a local copy on the host system.
728 Thus, "poky" can refer to the local copy of the Source Directory used to develop within
729 the Yocto Project.</para></listitem>
730 <listitem><para><emphasis>Recipe:</emphasis>
731 A set of instructions for building packages.
732 A recipe describes where you get source code and which patches
733 to apply.
734 Recipes describe dependencies for libraries or for other
735 recipes, and they also contain configuration and compilation
736 options.
737 Recipes contain the logical unit of execution, the software
738 to build, the images to build, and use the
739 <filename>.bb</filename> file extension.
740 </para></listitem>
741 <listitem>
742 <para id='source-directory'><emphasis>Source Directory:</emphasis>
743 This term refers to the directory structure created as a result
744 of creating a local copy of the <filename>poky</filename> Git
745 repository <filename>git://git.yoctoproject.org/poky</filename>
746 or expanding a released <filename>poky</filename> tarball.
747 <note>
748 Creating a local copy of the <filename>poky</filename>
749 Git repository is the recommended method for setting up
750 your Source Directory.
751 </note>
752 Sometimes you might hear the term "poky directory" used to refer
753 to this directory structure.
754 <note>
755 The OpenEmbedded build system does not support file or
756 directory names that contain spaces.
757 Be sure that the Source Directory you use does not contain
758 these types of names.
759 </note></para>
760
761 <para>The Source Directory contains BitBake, Documentation,
762 Metadata and other files that all support the Yocto Project.
763 Consequently, you must have the Source Directory in place on
764 your development system in order to do any development using
765 the Yocto Project.</para>
766
767 <para>When you create a local copy of the Git repository, you
768 can name the repository anything you like.
769 Throughout much of the documentation, "poky"
770 is used as the name of the top-level folder of the local copy of
771 the poky Git repository.
772 So, for example, cloning the <filename>poky</filename> Git
773 repository results in a local Git repository whose top-level
774 folder is also named "poky".</para>
775
776 <para>While it is not recommended that you use tarball expansion
777 to setup the Source Directory, if you do, the top-level
778 directory name of the Source Directory is derived from the
779 Yocto Project release tarball.
780 For example, downloading and unpacking
781 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
782 Source Directory whose root folder is named
783 <filename>&YOCTO_POKY;</filename>.</para>
784
785 <para>It is important to understand the differences between the
786 Source Directory created by unpacking a released tarball as
787 compared to cloning
788 <filename>git://git.yoctoproject.org/poky</filename>.
789 When you unpack a tarball, you have an exact copy of the files
790 based on the time of release - a fixed release point.
791 Any changes you make to your local files in the Source Directory
792 are on top of the release and will remain local only.
793 On the other hand, when you clone the <filename>poky</filename>
794 Git repository, you have an active development repository with
795 access to the upstream repository's branches and tags.
796 In this case, any local changes you make to the local
797 Source Directory can be later applied to active development
798 branches of the upstream <filename>poky</filename> Git
799 repository.</para>
800
801 <para>For more information on concepts related to Git
802 repositories, branches, and tags, see the
803 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
804 section.</para></listitem>
805 <listitem><para><emphasis>Task:</emphasis>
806 A unit of execution for BitBake (e.g.
807 <filename>do_compile</filename>,
808 <filename>do_fetch</filename>, <filename>do_patch</filename>,
809 and so forth).
810 </para></listitem>
811 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
812 that are not local to the development system but located in a master area that is controlled
813 by the maintainer of the source code.
814 For example, in order for a developer to work on a particular piece of code, they need to
815 first get a copy of it from an "upstream" source.</para></listitem>
816 </itemizedlist>
817 </para>
818</section>
819
820<section id='licensing'>
821 <title>Licensing</title>
822
823 <para>
824 Because open source projects are open to the public, they have different licensing structures in place.
825 License evolution for both Open Source and Free Software has an interesting history.
826 If you are interested in this history, you can find basic information here:
827 <itemizedlist>
828 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
829 </para></listitem>
830 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license
831 history</ulink></para></listitem>
832 </itemizedlist>
833 </para>
834
835 <para>
836 In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
837 (MIT) License.
838 MIT licensing permits the reuse of software within proprietary software as long as the
839 license is distributed with that software.
840 MIT is also compatible with the GNU General Public License (GPL).
841 Patches to the Yocto Project follow the upstream licensing scheme.
842 You can find information on the MIT license at
843 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
844 You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>
845 here</ulink>.
846 </para>
847
848 <para>
849 When you build an image using the Yocto Project, the build process uses a
850 known list of licenses to ensure compliance.
851 You can find this list in the
852 <link linkend='source-directory'>Source Directory</link> at
853 <filename>meta/files/common-licenses</filename>.
854 Once the build completes, the list of all licenses found and used during that build are
855 kept in the
856 <link linkend='build-directory'>Build Directory</link> at
857 <filename>tmp/deploy/licenses</filename>.
858 </para>
859
860 <para>
861 If a module requires a license that is not in the base list, the build process
862 generates a warning during the build.
863 These tools make it easier for a developer to be certain of the licenses with which
864 their shipped products must comply.
865 However, even with these tools it is still up to the developer to resolve potential licensing issues.
866 </para>
867
868 <para>
869 The base list of licenses used by the build process is a combination of the Software Package
870 Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
871 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation
872 that maintains a specification
873 for a standard format for communicating the components, licenses, and copyrights
874 associated with a software package.
875 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
876 Definition and the effort for reviewing and approving licenses that
877 conform to the Open Source Definition (OSD).
878 </para>
879
880 <para>
881 You can find a list of the combined SPDX and OSI licenses that the
882 Yocto Project uses in the
883 <filename>meta/files/common-licenses</filename> directory in your
884 <link linkend='source-directory'>Source Directory</link>.
885 </para>
886
887 <para>
888 For information that can help you maintain compliance with various
889 open source licensing during the lifecycle of a product created using
890 the Yocto Project, see the
891 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"
892 section.
893 </para>
894</section>
895
896<section id='git'>
897 <title>Git</title>
898
899 <para>
900 The Yocto Project makes extensive use of Git,
901 which is a free, open source distributed version control system.
902 Git supports distributed development, non-linear development, and can handle large projects.
903 It is best that you have some fundamental understanding of how Git tracks projects and
904 how to work with Git if you are going to use the Yocto Project for development.
905 This section provides a quick overview of how Git works and provides you with a summary
906 of some essential Git commands.
907 </para>
908
909 <para>
910 For more information on Git, see
911 <ulink url='http://git-scm.com/documentation'></ulink>.
912 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
913 </para>
914
915 <section id='repositories-tags-and-branches'>
916 <title>Repositories, Tags, and Branches</title>
917
918 <para>
919 As mentioned earlier in the section
920 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
921 the Yocto Project maintains source repositories at
922 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
923 If you look at this web-interface of the repositories, each item is a separate
924 Git repository.
925 </para>
926
927 <para>
928 Git repositories use branching techniques that track content change (not files)
929 within a project (e.g. a new feature or updated documentation).
930 Creating a tree-like structure based on project divergence allows for excellent historical
931 information over the life of a project.
932 This methodology also allows for an environment from which you can do lots of
933 local experimentation on projects as you develop changes or new features.
934 </para>
935
936 <para>
937 A Git repository represents all development efforts for a given project.
938 For example, the Git repository <filename>poky</filename> contains all changes
939 and developments for Poky over the course of its entire life.
940 That means that all changes that make up all releases are captured.
941 The repository maintains a complete history of changes.
942 </para>
943
944 <para>
945 You can create a local copy of any repository by "cloning" it with the Git
946 <filename>clone</filename> command.
947 When you clone a Git repository, you end up with an identical copy of the
948 repository on your development system.
949 Once you have a local copy of a repository, you can take steps to develop locally.
950 For examples on how to clone Git repositories, see the
951 "<link linkend='getting-setup'>Getting Set Up</link>" section.
952 </para>
953
954 <para>
955 It is important to understand that Git tracks content change and
956 not files.
957 Git uses "branches" to organize different development efforts.
958 For example, the <filename>poky</filename> repository has
959 <filename>denzil</filename>, <filename>danny</filename>,
960 <filename>dylan</filename>, <filename>dora</filename>,
961 <filename>daisy</filename>, and <filename>master</filename> branches
962 among others.
963 You can see all the branches by going to
964 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
965 clicking on the
966 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
967 link beneath the "Branch" heading.
968 </para>
969
970 <para>
971 Each of these branches represents a specific area of development.
972 The <filename>master</filename> branch represents the current or most recent
973 development.
974 All other branches represent off-shoots of the <filename>master</filename>
975 branch.
976 </para>
977
978 <para>
979 When you create a local copy of a Git repository, the copy has the same set
980 of branches as the original.
981 This means you can use Git to create a local working area (also called a branch)
982 that tracks a specific development branch from the source Git repository.
983 in other words, you can define your local Git environment to work on any development
984 branch in the repository.
985 To help illustrate, here is a set of commands that creates a local copy of the
986 <filename>poky</filename> Git repository and then creates and checks out a local
987 Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
988 <literallayout class='monospaced'>
989 $ cd ~
990 $ git clone git://git.yoctoproject.org/poky
991 $ cd poky
992 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
993 </literallayout>
994 In this example, the name of the top-level directory of your local
995 <link linkend='source-directory'>Source Directory</link>
996 is "poky" and the name of that local working area (local branch)
997 you just created and checked out is "&DISTRO_NAME;".
998 The files in your local repository now reflect the same files that
999 are in the "&DISTRO_NAME;" development branch of the
1000 Yocto Project's "poky" upstream repository.
1001 It is important to understand that when you create and checkout a
1002 local working branch based on a branch name,
1003 your local environment matches the "tip" of that development branch
1004 at the time you created your local branch, which could be
1005 different from the files at the time of a similarly named release.
1006 In other words, creating and checking out a local branch based on
1007 the "&DISTRO_NAME;" branch name is not the same as
1008 cloning and checking out the "master" branch.
1009 Keep reading to see how you create a local snapshot of a Yocto
1010 Project Release.
1011 </para>
1012
1013 <para>
1014 Git uses "tags" to mark specific changes in a repository.
1015 Typically, a tag is used to mark a special point such as the final
1016 change before a project is released.
1017 You can see the tags used with the <filename>poky</filename> Git
1018 repository by going to
1019 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
1020 clicking on the
1021 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
1022 link beneath the "Tag" heading.
1023 </para>
1024
1025 <para>
1026 Some key tags are <filename>dylan-9.0.0</filename>,
1027 <filename>dora-10.0.0</filename>,
1028 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
1029 These tags represent Yocto Project releases.
1030 </para>
1031
1032 <para>
1033 When you create a local copy of the Git repository, you also have access to all the
1034 tags.
1035 Similar to branches, you can create and checkout a local working Git branch based
1036 on a tag name.
1037 When you do this, you get a snapshot of the Git repository that reflects
1038 the state of the files when the change was made associated with that tag.
1039 The most common use is to checkout a working branch that matches a specific
1040 Yocto Project release.
1041 Here is an example:
1042 <literallayout class='monospaced'>
1043 $ cd ~
1044 $ git clone git://git.yoctoproject.org/poky
1045 $ cd poky
1046 $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
1047 </literallayout>
1048 In this example, the name of the top-level directory of your local Yocto Project
1049 Files Git repository is <filename>poky</filename>.
1050 And, the name of the local branch you have created and checked out is
1051 <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.
1052 The files in your repository now exactly match the Yocto Project &DISTRO;
1053 Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).
1054 It is important to understand that when you create and checkout a local
1055 working branch based on a tag, your environment matches a specific point
1056 in time and not the entire development branch.
1057 </para>
1058 </section>
1059
1060 <section id='basic-commands'>
1061 <title>Basic Commands</title>
1062
1063 <para>
1064 Git has an extensive set of commands that lets you manage changes and perform
1065 collaboration over the life of a project.
1066 Conveniently though, you can manage with a small set of basic operations and workflows
1067 once you understand the basic philosophy behind Git.
1068 You do not have to be an expert in Git to be functional.
1069 A good place to look for instruction on a minimal set of Git commands is
1070 <ulink url='http://git-scm.com/documentation'>here</ulink>.
1071 If you need to download Git, you can do so
1072 <ulink url='http://git-scm.com/download'>here</ulink>.
1073 </para>
1074
1075 <para>
1076 If you do not know much about Git, you should educate
1077 yourself by visiting the links previously mentioned.
1078 </para>
1079
1080 <para>
1081 The following list briefly describes some basic Git operations as a way to get started.
1082 As with any set of commands, this list (in most cases) simply shows the base command and
1083 omits the many arguments they support.
1084 See the Git documentation for complete descriptions and strategies on how to use these commands:
1085 <itemizedlist>
1086 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
1087 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
1088 <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
1089 Creates a local clone of a Git repository.
1090 During collaboration, this command allows you to create a
1091 local Git repository that is on equal footing with a fellow
1092 developer’s Git repository.
1093 </para></listitem>
1094 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
1095 to the index that
1096 Git uses to track changes.
1097 You must stage all files that have changed before you can commit them.</para></listitem>
1098 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents
1099 the changes you made.
1100 Commits are used for historical purposes, for determining if a maintainer of a project
1101 will allow the change, and for ultimately pushing the change from your local Git repository
1102 into the project’s upstream (or master) repository.</para></listitem>
1103 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
1104 possibly need to be staged and committed.</para></listitem>
1105 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
1106 your working branch.
1107 This command is analogous to "cd".</para></listitem>
1108 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
1109 a working branch on your local machine where you can isolate work.
1110 It is a good idea to use local branches when adding specific features or changes.
1111 This way if you do not like what you have done you can easily get rid of the work.</para></listitem>
1112 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
1113 existing local branches and
1114 tells you the branch in which you are currently working.</para></listitem>
1115 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
1116 Deletes an existing local branch.
1117 You need to be in a local branch other than the one you are deleting
1118 in order to delete <filename>&lt;branch-name&gt;</filename>.</para></listitem>
1119 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
1120 from an upstream Git
1121 repository and places it in your local Git repository.
1122 You use this command to make sure you are synchronized with the repository
1123 from which you are basing changes (.e.g. the master branch).</para></listitem>
1124 <listitem><para><emphasis><filename>git push</filename>:</emphasis>
1125 Sends all your committed local changes to an upstream Git
1126 repository (e.g. a contribution repository).
1127 The maintainer of the project draws from these repositories
1128 when adding changes to the project’s master repository or
1129 other development branch.
1130 </para></listitem>
1131 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
1132 local branch of your repository with another branch.
1133 When you create a local Git repository, the default branch is named "master".
1134 A typical workflow is to create a temporary branch for isolated work, make and commit your
1135 changes, switch to your local master branch, merge the changes from the temporary branch into the
1136 local master branch, and then delete the temporary branch.</para></listitem>
1137 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
1138 commits from one branch into another branch.
1139 There are times when you might not be able to merge all the changes in one branch with
1140 another but need to pick out certain ones.</para></listitem>
1141 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
1142 and changes in your local Git repository.
1143 This command is a good way to graphically see where things have diverged in your
1144 local repository.</para></listitem>
1145 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
1146 repository.</para></listitem>
1147 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
1148 between your local working files and the same files in the upstream Git repository that your
1149 branch currently tracks.</para></listitem>
1150 </itemizedlist>
1151 </para>
1152 </section>
1153</section>
1154
1155<section id='workflows'>
1156 <title>Workflows</title>
1157
1158 <para>
1159 This section provides some overview on workflows using Git.
1160 In particular, the information covers basic practices that describe roles and actions in a
1161 collaborative development environment.
1162 Again, if you are familiar with this type of development environment, you might want to just
1163 skip this section.
1164 </para>
1165
1166 <para>
1167 The Yocto Project files are maintained using Git in a "master" branch whose Git history
1168 tracks every change and whose structure provides branches for all diverging functionality.
1169 Although there is no need to use Git, many open source projects do so.
1170 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
1171 branch of a given Git repository.
1172 The "master" branch is the “upstream” repository where the final builds of the project occur.
1173 The maintainer is responsible for allowing changes in from other developers and for
1174 organizing the underlying branch structure to reflect release strategies and so forth.
1175 <note>For information on finding out who is responsible (maintains)
1176 for a particular area of code, see the
1177 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1178 section.
1179 </note>
1180 </para>
1181
1182 <para>
1183 The project also has an upstream contribution Git repository named
1184 <filename>poky-contrib</filename>.
1185 You can see all the branches in this repository using the web interface
1186 of the
1187 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
1188 within the "Poky Support" area.
1189 These branches temporarily hold changes to the project that have been
1190 submitted or committed by the Yocto Project development team and by
1191 community members who contribute to the project.
1192 The maintainer determines if the changes are qualified to be moved
1193 from the "contrib" branches into the "master" branch of the Git
1194 repository.
1195 </para>
1196
1197 <para>
1198 Developers (including contributing community members) create and maintain cloned repositories
1199 of the upstream "master" branch.
1200 These repositories are local to their development platforms and are used to develop changes.
1201 When a developer is satisfied with a particular feature or change, they "push" the changes
1202 to the appropriate "contrib" repository.
1203 </para>
1204
1205 <para>
1206 Developers are responsible for keeping their local repository up-to-date with "master".
1207 They are also responsible for straightening out any conflicts that might arise within files
1208 that are being worked on simultaneously by more than one person.
1209 All this work is done locally on the developer’s machines before anything is pushed to a
1210 "contrib" area and examined at the maintainer’s level.
1211 </para>
1212
1213 <para>
1214 A somewhat formal method exists by which developers commit changes and push them into the
1215 "contrib" area and subsequently request that the maintainer include them into "master"
1216 This process is called “submitting a patch” or "submitting a change."
1217 For information on submitting patches and changes, see the
1218 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
1219 </para>
1220
1221 <para>
1222 To summarize the environment: a single point of entry exists for
1223 changes into the project’s "master" branch of the Git repository,
1224 which is controlled by the project’s maintainer.
1225 And, a set of developers exist who independently develop, test, and
1226 submit changes to "contrib" areas for the maintainer to examine.
1227 The maintainer then chooses which changes are going to become a
1228 permanent part of the project.
1229 </para>
1230
1231 <para>
1232 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
1233 </para>
1234
1235 <para>
1236 While each development environment is unique, there are some best practices or methods
1237 that help development run smoothly.
1238 The following list describes some of these practices.
1239 For more information about Git workflows, see the workflow topics in the
1240 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
1241 <itemizedlist>
1242 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
1243 small as compared to bundling many disparate changes into a single commit.
1244 This practice not only keeps things manageable but also allows the maintainer
1245 to more easily include or refuse changes.</para>
1246 <para>It is also good practice to leave the repository in a state that allows you to
1247 still successfully build your project. In other words, do not commit half of a feature,
1248 then add the other half as a separate, later commit.
1249 Each commit should take you from one buildable project state to another
1250 buildable state.</para></listitem>
1251 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
1252 delete local branches in your working Git repository.
1253 You can name these branches anything you like.
1254 It is helpful to give them names associated with the particular feature or change
1255 on which you are working.
1256 Once you are done with a feature or change and have merged it
1257 into your local master branch, simply discard the temporary
1258 branch.</para></listitem>
1259 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
1260 command allows you to take the
1261 changes from one branch and fold them into another branch.
1262 This process is especially helpful when more than a single developer might be working
1263 on different parts of the same feature.
1264 Merging changes also automatically identifies any collisions or "conflicts"
1265 that might happen as a result of the same lines of code being altered by two different
1266 developers.</para></listitem>
1267 <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
1268 use a system where branches indicate varying levels of code readiness.
1269 For example, you can have a "work" branch to develop in, a "test" branch where the code or
1270 change is tested, a "stage" branch where changes are ready to be committed, and so forth.
1271 As your project develops, you can merge code across the branches to reflect ever-increasing
1272 stable states of the development.</para></listitem>
1273 <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
1274 concept of developers "pushing" local commits to a remote repository, which is
1275 usually a contribution repository.
1276 This workflow is also based on developers "pulling" known states of the project down into their
1277 local development repositories.
1278 The workflow easily allows you to pull changes submitted by other developers from the
1279 upstream repository into your work area ensuring that you have the most recent software
1280 on which to develop.
1281 The Yocto Project has two scripts named <filename>create-pull-request</filename> and
1282 <filename>send-pull-request</filename> that ship with the release to facilitate this
1283 workflow.
1284 You can find these scripts in the <filename>scripts</filename>
1285 folder of the
1286 <link linkend='source-directory'>Source Directory</link>.
1287 For information on how to use these scripts, see the
1288 "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
1289 </para></listitem>
1290 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
1291 maintainer through an email that you have a change (or patch) you would like considered
1292 for the "master" branch of the Git repository.
1293 To send this type of change, you format the patch and then send the email using the Git commands
1294 <filename>git format-patch</filename> and <filename>git send-email</filename>.
1295 For information on how to use these scripts, see the
1296 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1297 section.
1298 </para></listitem>
1299 </itemizedlist>
1300 </para>
1301</section>
1302
1303<section id='tracking-bugs'>
1304 <title>Tracking Bugs</title>
1305
1306 <para>
1307 The Yocto Project uses its own implementation of
1308 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
1309 Implementations of Bugzilla work well for group development because they track bugs and code
1310 changes, can be used to communicate changes and problems with developers, can be used to
1311 submit and review patches, and can be used to manage quality assurance.
1312 The home page for the Yocto Project implementation of Bugzilla is
1313 <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
1314 </para>
1315
1316 <para>
1317 Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
1318 such as when discovering an issue with some component of the build system that acts contrary
1319 to the documentation or your expectations.
1320 Following is the general procedure for submitting a new bug using the Yocto Project
1321 Bugzilla.
1322 You can find more information on defect management, bug tracking, and feature request
1323 processes all accomplished through the Yocto Project Bugzilla on the wiki page
1324 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
1325 <orderedlist>
1326 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
1327 a bug.</para></listitem>
1328 <listitem><para>When submitting a new bug, be sure to choose the appropriate
1329 Classification, Product, and Component for which the issue was found.
1330 Defects for the Yocto Project fall into one of six classifications: Yocto Project
1331 Components, Infrastructure, Build System &amp; Metadata, Documentation,
1332 QA/Testing, and Runtime.
1333 Each of these Classifications break down into multiple Products and, in some
1334 cases, multiple Components.</para></listitem>
1335 <listitem><para>Use the bug form to choose the correct Hardware and Architecture
1336 for which the bug applies.</para></listitem>
1337 <listitem><para>Indicate the Yocto Project version you were using when the issue
1338 occurred.</para></listitem>
1339 <listitem><para>Be sure to indicate the Severity of the bug.
1340 Severity communicates how the bug impacted your work.</para></listitem>
1341 <listitem><para>Select the appropriate "Documentation change" item
1342 for the bug.
1343 Fixing a bug may or may not affect the Yocto Project
1344 documentation.</para></listitem>
1345 <listitem><para>Provide a brief summary of the issue.
1346 Try to limit your summary to just a line or two and be sure to capture the
1347 essence of the issue.</para></listitem>
1348 <listitem><para>Provide a detailed description of the issue.
1349 You should provide as much detail as you can about the context, behavior, output,
1350 and so forth that surrounds the issue.
1351 You can even attach supporting files for output from logs by
1352 using the "Add an attachment" button.</para></listitem>
1353 <listitem><para>Be sure to copy the appropriate people in the
1354 "CC List" for the bug.
1355 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1356 section for information about finding out who is responsible
1357 for code.</para></listitem>
1358 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
1359 </orderedlist>
1360 </para>
1361</section>
1362
1363<section id='how-to-submit-a-change'>
1364 <title>How to Submit a Change</title>
1365
1366 <para>
1367 Contributions to the Yocto Project and OpenEmbedded are very welcome.
1368 Because the system is extremely configurable and flexible, we recognize that developers
1369 will want to extend, configure or optimize it for their specific uses.
1370 You should send patches to the appropriate mailing list so that they
1371 can be reviewed and merged by the appropriate maintainer.
1372 </para>
1373
1374 <para>
1375 Before submitting any change, be sure to find out who you should be
1376 notifying.
1377 Several methods exist through which you find out who you should be copying
1378 or notifying:
1379 <itemizedlist>
1380 <listitem><para><emphasis>Maintenance File:</emphasis>
1381 Examine the <filename>maintainers.inc</filename> file, which is
1382 located in the
1383 <link linkend='source-directory'>Source Directory</link>
1384 at <filename>meta-yocto/conf/distro/include</filename>, to
1385 see who is responsible for code.
1386 </para></listitem>
1387 <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
1388 For BSP maintainers of supported BSPs, you can examine
1389 individual BSP <filename>README</filename> files.
1390 In addition, some layers (such as the <filename>meta-intel</filename> layer),
1391 include a <filename>MAINTAINERS</filename> file which contains
1392 a list of all supported BSP maintainers for that layer.
1393 </para></listitem>
1394 <listitem><para><emphasis>Search by File:</emphasis>
1395 Using <link linkend='git'>Git</link>, you can enter the
1396 following command to bring up a short list of all commits
1397 against a specific file:
1398 <literallayout class='monospaced'>
1399 git shortlog -- &lt;filename&gt;
1400 </literallayout>
1401 Just provide the name of the file for which you are interested.
1402 The information returned is not ordered by history but does
1403 include a list of all committers grouped by name.
1404 From the list, you can see who is responsible for the bulk of
1405 the changes against the file.
1406 </para></listitem>
1407 </itemizedlist>
1408 </para>
1409
1410 <para>
1411 For a list of the Yocto Project and related mailing lists, see the
1412 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
1413 the Yocto Project Reference Manual.
1414 </para>
1415
1416 <para>
1417 Here is some guidance on which mailing list to use for what type of change:
1418 <itemizedlist>
1419 <listitem><para>For changes to the core
1420 <link linkend='metadata'>Metadata</link>, send your patch to the
1421 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
1422 For example, a change to anything under the <filename>meta</filename> or
1423 <filename>scripts</filename> directories
1424 should be sent to this mailing list.</para></listitem>
1425 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
1426 directory), send your patch to the
1427 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
1428 <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
1429 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
1430 <listitem><para>For changes to other layers hosted on
1431 <filename>yoctoproject.org</filename> (unless the
1432 layer's documentation specifies otherwise), tools, and Yocto Project
1433 documentation, use the
1434 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
1435 <listitem><para>For additional recipes that do not fit into the core Metadata,
1436 you should determine which layer the recipe should go into and submit the
1437 change in the manner recommended by the documentation (e.g. README) supplied
1438 with the layer. If in doubt, please ask on the
1439 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
1440 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
1441 mailing lists.</para></listitem>
1442 </itemizedlist>
1443 </para>
1444
1445 <para>
1446 When you send a patch, be sure to include a "Signed-off-by:"
1447 line in the same style as required by the Linux kernel.
1448 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
1449 as follows:
1450 <literallayout class='monospaced'>
1451 Developer's Certificate of Origin 1.1
1452
1453 By making a contribution to this project, I certify that:
1454
1455 (a) The contribution was created in whole or in part by me and I
1456 have the right to submit it under the open source license
1457 indicated in the file; or
1458
1459 (b) The contribution is based upon previous work that, to the best
1460 of my knowledge, is covered under an appropriate open source
1461 license and I have the right under that license to submit that
1462 work with modifications, whether created in whole or in part
1463 by me, under the same open source license (unless I am
1464 permitted to submit under a different license), as indicated
1465 in the file; or
1466
1467 (c) The contribution was provided directly to me by some other
1468 person who certified (a), (b) or (c) and I have not modified
1469 it.
1470
1471 (d) I understand and agree that this project and the contribution
1472 are public and that a record of the contribution (including all
1473 personal information I submit with it, including my sign-off) is
1474 maintained indefinitely and may be redistributed consistent with
1475 this project or the open source license(s) involved.
1476 </literallayout>
1477 </para>
1478
1479 <para>
1480 In a collaborative environment, it is necessary to have some sort of standard
1481 or method through which you submit changes.
1482 Otherwise, things could get quite chaotic.
1483 One general practice to follow is to make small, controlled changes.
1484 Keeping changes small and isolated aids review, makes merging/rebasing easier
1485 and keeps the change history clean when anyone needs to refer to it in future.
1486 </para>
1487
1488 <para>
1489 When you make a commit, you must follow certain standards established by the
1490 OpenEmbedded and Yocto Project development teams.
1491 For each commit, you must provide a single-line summary of the change and you
1492 should almost always provide a more detailed description of what you did (i.e.
1493 the body of the commit message).
1494 The only exceptions for not providing a detailed description would be if your
1495 change is a simple, self-explanatory change that needs no further description
1496 beyond the summary.
1497 Here are the guidelines for composing a commit message:
1498 <itemizedlist>
1499 <listitem><para>Provide a single-line, short summary of the change.
1500 This summary is typically viewable in the "shortlist" of changes.
1501 Thus, providing something short and descriptive that gives the reader
1502 a summary of the change is useful when viewing a list of many commits.
1503 This short description should be prefixed by the recipe name (if changing a recipe), or
1504 else the short form path to the file being changed.
1505 </para></listitem>
1506 <listitem><para>For the body of the commit message, provide detailed information
1507 that describes what you changed, why you made the change, and the approach
1508 you used. It may also be helpful if you mention how you tested the change.
1509 Provide as much detail as you can in the body of the commit message.
1510 </para></listitem>
1511 <listitem><para>
1512 If the change addresses a specific bug or issue that is
1513 associated with a bug-tracking ID, include a reference to that
1514 ID in your detailed description.
1515 For example, the Yocto Project uses a specific convention for
1516 bug references - any commit that addresses a specific bug should
1517 use the following form for the detailed description:
1518 <literallayout class='monospaced'>
1519 Fixes [YOCTO #&lt;bug-id&gt;]
1520
1521 &lt;detailed description of change&gt;
1522 </literallayout></para></listitem>
1523 Where &lt;bug-id&gt; is replaced with the specific bug ID from
1524 the Yocto Project Bugzilla instance.
1525 </itemizedlist>
1526 </para>
1527
1528 <para>
1529 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1530 wiki page:
1531 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1532 </para>
1533
1534 <para>
1535 The next two sections describe general instructions for both pushing
1536 changes upstream and for submitting changes as patches.
1537 </para>
1538
1539 <section id='pushing-a-change-upstream'>
1540 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
1541
1542 <para>
1543 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1544 <itemizedlist>
1545 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1546 <listitem><para>Stage your changes by using the <filename>git add</filename>
1547 command on each file you changed.</para></listitem>
1548 <listitem><para>
1549 Commit the change by using the
1550 <filename>git commit</filename> command.
1551 Be sure to provide a commit message that follows the
1552 project’s commit message standards as described earlier.
1553 </para></listitem>
1554 <listitem><para>
1555 Push the change to the upstream "contrib" repository by
1556 using the <filename>git push</filename> command.
1557 </para></listitem>
1558 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1559 request.
1560 The Yocto Project provides two scripts that conveniently let you generate and send
1561 pull requests to the Yocto Project.
1562 These scripts are <filename>create-pull-request</filename> and
1563 <filename>send-pull-request</filename>.
1564 You can find these scripts in the <filename>scripts</filename> directory
1565 within the <link linkend='source-directory'>Source Directory</link>.</para>
1566 <para>Using these scripts correctly formats the requests without introducing any
1567 whitespace or HTML formatting.
1568 The maintainer that receives your patches needs to be able to save and apply them
1569 directly from your emails.
1570 Using these scripts is the preferred method for sending patches.</para>
1571 <para>For help on using these scripts, simply provide the
1572 <filename>-h</filename> argument as follows:
1573 <literallayout class='monospaced'>
1574 $ poky/scripts/create-pull-request -h
1575 $ poky/scripts/send-pull-request -h
1576 </literallayout></para></listitem>
1577 </itemizedlist>
1578 </para>
1579
1580 <para>
1581 You can find general Git information on how to push a change upstream in the
1582 <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>.
1583 </para>
1584 </section>
1585
1586 <section id='submitting-a-patch'>
1587 <title>Using Email to Submit a Patch</title>
1588
1589 <para>
1590 You can submit patches without using the <filename>create-pull-request</filename> and
1591 <filename>send-pull-request</filename> scripts described in the previous section.
1592 However, keep in mind, the preferred method is to use the scripts.
1593 </para>
1594
1595 <para>
1596 Depending on the components changed, you need to submit the email to a specific
1597 mailing list.
1598 For some guidance on which mailing list to use, see the list in the
1599 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1600 section.
1601 For a description of the available mailing lists, see the
1602 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
1603 section in the Yocto Project Reference Manual.
1604 </para>
1605
1606 <para>
1607 Here is the general procedure on how to submit a patch through email without using the
1608 scripts:
1609 <itemizedlist>
1610 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1611 <listitem><para>Stage your changes by using the <filename>git add</filename>
1612 command on each file you changed.</para></listitem>
1613 <listitem><para>Commit the change by using the
1614 <filename>git commit --signoff</filename> command.
1615 Using the <filename>--signoff</filename> option identifies you as the person
1616 making the change and also satisfies the Developer's Certificate of
1617 Origin (DCO) shown earlier.</para>
1618 <para>When you form a commit, you must follow certain standards established by the
1619 Yocto Project development team.
1620 See the earlier section
1621 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1622 for Yocto Project commit message standards.</para></listitem>
1623 <listitem><para>Format the commit into an email message.
1624 To format commits, use the <filename>git format-patch</filename> command.
1625 When you provide the command, you must include a revision list or a number of patches
1626 as part of the command.
1627 For example, either of these two commands takes your most
1628 recent single commit and formats it as an email message in
1629 the current directory:
1630 <literallayout class='monospaced'>
1631 $ git format-patch -1
1632 </literallayout>
1633 or
1634 <literallayout class='monospaced'>
1635 $ git format-patch HEAD~
1636 </literallayout></para>
1637 <para>After the command is run, the current directory contains a
1638 numbered <filename>.patch</filename> file for the commit.</para>
1639 <para>If you provide several commits as part of the command,
1640 the <filename>git format-patch</filename> command produces a
1641 series of numbered files in the current directory – one for each commit.
1642 If you have more than one patch, you should also use the
1643 <filename>--cover</filename> option with the command, which generates a
1644 cover letter as the first "patch" in the series.
1645 You can then edit the cover letter to provide a description for
1646 the series of patches.
1647 For information on the <filename>git format-patch</filename> command,
1648 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
1649 <filename>man git-format-patch</filename> command.</para>
1650 <note>If you are or will be a frequent contributor to the Yocto Project
1651 or to OpenEmbedded, you might consider requesting a contrib area and the
1652 necessary associated rights.</note></listitem>
1653 <listitem><para>Import the files into your mail client by using the
1654 <filename>git send-email</filename> command.
1655 <note>In order to use <filename>git send-email</filename>, you must have the
1656 the proper Git packages installed.
1657 For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para>
1658 <para>The <filename>git send-email</filename> command sends email by using a local
1659 or remote Mail Transport Agent (MTA) such as
1660 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
1661 <filename>smtp</filename> configuration in your Git <filename>config</filename>
1662 file.
1663 If you are submitting patches through email only, it is very important
1664 that you submit them without any whitespace or HTML formatting that
1665 either you or your mailer introduces.
1666 The maintainer that receives your patches needs to be able to save and
1667 apply them directly from your emails.
1668 A good way to verify that what you are sending will be applicable by the
1669 maintainer is to do a dry run and send them to yourself and then
1670 save and apply them as the maintainer would.</para>
1671 <para>The <filename>git send-email</filename> command is the preferred method
1672 for sending your patches since there is no risk of compromising whitespace
1673 in the body of the message, which can occur when you use your own mail client.
1674 The command also has several options that let you
1675 specify recipients and perform further editing of the email message.
1676 For information on how to use the <filename>git send-email</filename> command,
1677 see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
1678 the <filename>man git-send-email</filename> command.
1679 </para></listitem>
1680 </itemizedlist>
1681 </para>
1682 </section>
1683</section>
1684</chapter>
1685<!--
1686vim: expandtab tw=80 ts=4
1687-->
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000000..6ab93f79cf
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,415 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='dev-manual-start'>
6
7<title>Getting Started with the Yocto Project</title>
8
9<para>
10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
11 You can find enough information to set up your development host and build or use images for
12 hardware supported by the Yocto Project by reading the
13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
14</para>
15
16<para>
17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
18 some higher-level concepts you might want to consider.
19</para>
20
21<section id='introducing-the-yocto-project'>
22 <title>Introducing the Yocto Project</title>
23
24 <para>
25 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
26 The project currently provides a build system that is
27 referred to as the
28 <link linkend='build-system-term'>OpenEmbedded build system</link>
29 in the Yocto Project documentation.
30 The Yocto Project provides various ancillary tools for the embedded developer
31 and also features the Sato reference User Interface, which is optimized for
32 stylus driven, low-resolution screens.
33 </para>
34
35 <para>
36 You can use the OpenEmbedded build system, which uses
37 <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux
38 images and associated user-space applications for architectures based
39 on ARM, MIPS, PowerPC, x86 and x86-64.
40 <note>
41 By default, using the Yocto Project creates a Poky distribution.
42 However, you can create your own distribution by providing key
43 <link linkend='metadata'>Metadata</link>.
44 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
45 section for more information.
46 </note>
47 While the Yocto Project does not provide a strict testing framework,
48 it does provide or generate for you artifacts that let you perform target-level and
49 emulated testing and debugging.
50 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
51 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
52 develop within that familiar environment.
53 </para>
54</section>
55
56<section id='getting-setup'>
57 <title>Getting Set Up</title>
58
59 <para>
60 Here is what you need to use the Yocto Project:
61 <itemizedlist>
62 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
63 Linux-based host system.
64 You will have the best results with a recent release of Fedora,
65 openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
66 and officially supported.
67 For a list of the distributions under validation and their status, see the
68 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
69 in the Yocto Project Reference Manual and the wiki page at
70 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
71 <para>
72 You should also have about 50 Gbytes of free disk space for building images.
73 </para></listitem>
74 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
75 requires that certain packages exist on your development system (e.g. Python 2.6 or 2.7).
76 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
77 section in the Yocto Project Quick Start and the
78 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
79 section in the Yocto Project Reference Manual for the exact
80 package requirements and the installation commands to install
81 them for the supported distributions.
82 </para></listitem>
83 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
84 You need a release of the Yocto Project locally installed on
85 your development system.
86 The documentation refers to this set of locally installed files
87 as the <link linkend='source-directory'>Source Directory</link>.
88 You create your Source Directory by using
89 <link linkend='git'>Git</link> to clone a local copy
90 of the upstream <filename>poky</filename> repository,
91 or by downloading and unpacking a tarball of an official
92 Yocto Project release.</para>
93 <para>Working from a copy of the upstream repository allows you
94 to contribute back into the Yocto Project or simply work with
95 the latest software on a development branch.
96 Because Git maintains and creates an upstream repository with
97 a complete history of changes and you are working with a local
98 clone of that repository, you have access to all the Yocto
99 Project development branches and tag names used in the upstream
100 repository.</para>
101 <note>You can view the Yocto Project Source Repositories at
102 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>
103 </note>
104 <para>The following transcript shows how to clone the
105 <filename>poky</filename> Git repository into the current
106 working directory.
107 The command creates the local repository in a directory
108 named <filename>poky</filename>.
109 For information on Git used within the Yocto Project, see
110 the "<link linkend='git'>Git</link>" section.
111 <literallayout class='monospaced'>
112 $ git clone git://git.yoctoproject.org/poky
113 Cloning into 'poky'...
114 remote: Counting objects: 226790, done.
115 remote: Compressing objects: 100% (57465/57465), done.
116 remote: Total 226790 (delta 165212), reused 225887 (delta 164327)
117 Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
118 Resolving deltas: 100% (165212/165212), done.
119 </literallayout></para>
120 <para>For another example of how to set up your own local Git
121 repositories, see this
122 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
123 wiki page</ulink>, which describes how to create local
124 Git repositories for both
125 <filename>poky</filename> and <filename>meta-intel</filename>.
126 </para></listitem>
127 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
128 If you are going to be making modifications to a supported Yocto Project kernel, you
129 need to establish local copies of the source.
130 You can find Git repositories of supported Yocto Project kernels organized under
131 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
132 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
133 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
134 copying that cloned repository.
135 You can create the bare clone and the copy of the bare clone anywhere you like.
136 For simplicity, it is recommended that you create these structures outside of the
137 Source Directory, which is usually named <filename>poky</filename>.</para>
138 <para>As an example, the following transcript shows how to create the bare clone
139 of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of
140 that clone.
141 <note>When you have a local Yocto Project kernel Git repository, you can
142 reference that repository rather than the upstream Git repository as
143 part of the <filename>clone</filename> command.
144 Doing so can speed up the process.</note></para>
145 <para>In the following example, the bare clone is named
146 <filename>linux-yocto-3.10.git</filename>, while the
147 copy is named <filename>my-linux-yocto-3.10-work</filename>:
148 <literallayout class='monospaced'>
149 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git
150 Cloning into bare repository 'linux-yocto-3.10.git'...
151 remote: Counting objects: 3364487, done.
152 remote: Compressing objects: 100% (507178/507178), done.
153 remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709)
154 Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done.
155 Resolving deltas: 100% (2827715/2827715), done.
156 </literallayout></para>
157 <para>Now create a clone of the bare clone just created:
158 <literallayout class='monospaced'>
159 $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work
160 Cloning into 'my-linux-yocto-3.10-work'...
161 done.
162 </literallayout></para></listitem>
163 <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
164 The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
165 The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
166 only if you are modifying and building the kernel image.
167 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
168 files that you
169 edit to point to your locally modified kernel source files and to build the kernel
170 image.
171 Pointing to these local files is much more efficient than requiring a download of the
172 kernel's source files from upstream each time you make changes to the kernel.</para>
173 <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
174 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
175 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
176 It is good practice to create this Git repository inside the Source Directory.</para>
177 <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
178 repository inside the Source Directory, which is named <filename>poky</filename>
179 in this case:
180 <literallayout class='monospaced'>
181 $ cd ~/poky
182 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
183 Cloning into 'meta-yocto-kernel-extras'...
184 remote: Counting objects: 727, done.
185 remote: Compressing objects: 100% (452/452), done.
186 remote: Total 727 (delta 260), reused 719 (delta 252)
187 Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done.
188 Resolving deltas: 100% (260/260), done.
189 </literallayout></para></listitem>
190 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis>
191 The Yocto Project provides a layer called
192 <filename>meta-intel</filename> and it is maintained in its own
193 separate Git repository.
194 The <filename>meta-intel</filename> layer contains many
195 supported
196 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.
197 </para>
198
199 <para>The Yocto Project uses the following BSP layer naming
200 scheme:
201 <literallayout class='monospaced'>
202 meta-&lt;BSP_name&gt;
203 </literallayout>
204 where <filename>&lt;BSP_name&gt;</filename> is the recognized
205 BSP name.
206 Here are some examples:
207 <literallayout class='monospaced'>
208 meta-crownbay
209 meta-emenlow
210 meta-n450
211 </literallayout>
212 See the
213 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
214 section in the Yocto Project Board Support Package (BSP)
215 Developer's Guide for more information on BSP Layers.
216 </para>
217
218 <para>
219 You can locate the <filename>meta-intel</filename> Git
220 repository in the "Yocto Metadata Layers" area of the Yocto
221 Project Source Repositories at
222 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
223 </para>
224
225 <para>
226 Using
227 <link linkend='git'>Git</link> to create a local clone of the
228 upstream repository can be helpful if you are working with
229 BSPs.
230 Typically, you set up the <filename>meta-intel</filename>
231 Git repository inside the Source Directory.
232 For example, the following transcript shows the steps to clone
233 <filename>meta-intel</filename>.
234 <note>
235 Be sure to work in the <filename>meta-intel</filename>
236 branch that matches your
237 <link linkend='source-directory'>Source Directory</link>
238 (i.e. <filename>poky</filename>) branch.
239 For example, if you have checked out the "master" branch
240 of <filename>poky</filename> and you are going to use
241 <filename>meta-intel</filename>, be sure to checkout the
242 "master" branch of <filename>meta-intel</filename>.
243 </note>
244 <literallayout class='monospaced'>
245 $ cd ~/poky
246 $ git clone git://git.yoctoproject.org/meta-intel.git
247 Cloning into 'meta-intel'...
248 remote: Counting objects: 8844, done.
249 remote: Compressing objects: 100% (2864/2864), done.
250 remote: Total 8844 (delta 4931), reused 8780 (delta 4867)
251 Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done.
252 Resolving deltas: 100% (4931/4931), done.
253 </literallayout>
254 </para>
255
256 <para>
257 The same
258 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>
259 referenced earlier covers how to set up the
260 <filename>meta-intel</filename> Git repository.
261 </para></listitem>
262 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
263 applications using the Eclipse Integrated Development Environment (IDE),
264 you will need this plug-in.
265 See the
266 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
267 section for more information.</para></listitem>
268 </itemizedlist>
269 </para>
270</section>
271
272<section id='building-images'>
273 <title>Building Images</title>
274
275 <para>
276 The build process creates an entire Linux distribution, including the toolchain, from source.
277 For more information on this topic, see the
278 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
279 section in the Yocto Project Quick Start.
280 </para>
281
282 <para>
283 The build process is as follows:
284 <orderedlist>
285 <listitem><para>Make sure you have set up the Source Directory described in the
286 previous section.</para></listitem>
287 <listitem><para>Initialize the build environment by sourcing a build
288 environment script (i.e.
289 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
290 or
291 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
292 </para></listitem>
293 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
294 which is found in the
295 <link linkend='build-directory'>Build Directory</link>,
296 is set up how you want it.
297 This file defines many aspects of the build environment including
298 the target machine architecture through the
299 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
300 the development machine's processor use through the
301 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
302 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
303 a centralized tarball download directory through the
304 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
305 <listitem><para>
306 Build the image using the <filename>bitbake</filename> command.
307 If you want information on BitBake, see the
308 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
309 </para></listitem>
310 <listitem><para>Run the image either on the actual hardware or using the QEMU
311 emulator.</para></listitem>
312 </orderedlist>
313 </para>
314</section>
315
316<section id='using-pre-built-binaries-and-qemu'>
317 <title>Using Pre-Built Binaries and QEMU</title>
318
319 <para>
320 Another option you have to get started is to use pre-built binaries.
321 The Yocto Project provides many types of binaries with each release.
322 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
323 chapter in the Yocto Project Reference Manual
324 for descriptions of the types of binaries that ship with a Yocto Project
325 release.
326 </para>
327
328 <para>
329 Using a pre-built binary is ideal for developing software applications to run on your
330 target hardware.
331 To do this, you need to be able to access the appropriate cross-toolchain tarball for
332 the architecture on which you are developing.
333 If you are using an SDK type image, the image ships with the complete toolchain native to
334 the architecture.
335 If you are not using an SDK type image, you need to separately download and
336 install the stand-alone Yocto Project cross-toolchain tarball.
337 </para>
338
339 <para>
340 Regardless of the type of image you are using, you need to download the pre-built kernel
341 that you will boot in the QEMU emulator and then download and extract the target root
342 filesystem for your target machine’s architecture.
343 You can get architecture-specific binaries and file systems from
344 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
345 You can get installation scripts for stand-alone toolchains from
346 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
347 Once you have all your files, you set up the environment to emulate the hardware
348 by sourcing an environment setup script.
349 Finally, you start the QEMU emulator.
350 You can find details on all these steps in the
351 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
352 section of the Yocto Project Quick Start.
353 </para>
354
355 <para>
356 Using QEMU to emulate your hardware can result in speed issues
357 depending on the target and host architecture mix.
358 For example, using the <filename>qemux86</filename> image in the emulator
359 on an Intel-based 32-bit (x86) host machine is fast because the target and
360 host architectures match.
361 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
362 host can be slower.
363 But, you still achieve faithful emulation of ARM-specific issues.
364 </para>
365
366 <para>
367 To speed things up, the QEMU images support using <filename>distcc</filename>
368 to call a cross-compiler outside the emulated system.
369 If you used <filename>runqemu</filename> to start QEMU, and the
370 <filename>distccd</filename> application is present on the host system, any
371 BitBake cross-compiling toolchain available from the build system is automatically
372 used from within QEMU simply by calling <filename>distcc</filename>.
373 You can accomplish this by defining the cross-compiler variable
374 (e.g. <filename>export CC="distcc"</filename>).
375 Alternatively, if you are using a suitable SDK image or the appropriate
376 stand-alone toolchain is present,
377 the toolchain is also automatically used.
378 </para>
379
380 <note>
381 Several mechanisms exist that let you connect to the system running on the
382 QEMU emulator:
383 <itemizedlist>
384 <listitem><para>QEMU provides a framebuffer interface that makes standard
385 consoles available.</para></listitem>
386 <listitem><para>Generally, headless embedded devices have a serial port.
387 If so, you can configure the operating system of the running image
388 to use that port to run a console.
389 The connection uses standard IP networking.</para></listitem>
390 <listitem><para>
391 SSH servers exist in some QEMU images.
392 The <filename>core-image-sato</filename> QEMU image has a
393 Dropbear secure shell (SSH) server that runs with the root
394 password disabled.
395 The <filename>core-image-full-cmdline</filename> and
396 <filename>core-image-lsb</filename> QEMU images
397 have OpenSSH instead of Dropbear.
398 Including these SSH servers allow you to use standard
399 <filename>ssh</filename> and <filename>scp</filename> commands.
400 The <filename>core-image-minimal</filename> QEMU image,
401 however, contains no SSH server.
402 </para></listitem>
403 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
404 using a local copy of the root filesystem on the host.
405 In order to make this connection, you must extract a root filesystem tarball by using the
406 <filename>runqemu-extract-sdk</filename> command.
407 After running the command, you must then point the <filename>runqemu</filename>
408 script to the extracted directory instead of a root filesystem image file.</para></listitem>
409 </itemizedlist>
410 </note>
411</section>
412</chapter>
413<!--
414vim: expandtab tw=80 ts=4
415-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
new file mode 100644
index 0000000000..a5d52cd2d7
--- /dev/null
+++ b/documentation/dev-manual/dev-manual.xml
@@ -0,0 +1,107 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='dev-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/dev-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Development Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Scott</firstname> <surname>Rifenbark</surname>
26 <affiliation>
27 <orgname>Intel Corporation</orgname>
28 </affiliation>
29 <email>scott.m.rifenbark@intel.com</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>1.1</revnumber>
36 <date>6 October 2011</date>
37 <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.2</revnumber>
41 <date>April 2012</date>
42 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>1.3</revnumber>
46 <date>October 2012</date>
47 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.4</revnumber>
51 <date>April 2013</date>
52 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.5</revnumber>
56 <date>October 2013</date>
57 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>1.5.1</revnumber>
61 <date>January 2014</date>
62 <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>1.6</revnumber>
66 <date>April 2014</date>
67 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
68 </revision>
69 </revhistory>
70
71 <copyright>
72 <year>&COPYRIGHT_YEAR;</year>
73 <holder>Linux Foundation</holder>
74 </copyright>
75
76 <legalnotice>
77 <para>
78 Permission is granted to copy, distribute and/or modify this document under
79 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
80 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
81 Creative Commons.
82 </para>
83
84 <note>
85 For the latest version of this manual associated with this
86 Yocto Project release, see the
87 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
88 from the Yocto Project website.
89 </note>
90 </legalnotice>
91
92 </bookinfo>
93
94 <xi:include href="dev-manual-intro.xml"/>
95
96 <xi:include href="dev-manual-start.xml"/>
97
98 <xi:include href="dev-manual-newbie.xml"/>
99
100 <xi:include href="dev-manual-model.xml"/>
101
102 <xi:include href="dev-manual-common-tasks.xml"/>
103
104</book>
105<!--
106vim: expandtab tw=80 ts=4
107-->
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..540b0abb9f
--- /dev/null
+++ b/documentation/dev-manual/figures/bsp-dev-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/dev-title.png b/documentation/dev-manual/figures/dev-title.png
new file mode 100644
index 0000000000..d3cac4a7e5
--- /dev/null
+++ b/documentation/dev-manual/figures/dev-title.png
Binary files differ
diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/dev-manual/figures/git-workflow.png
new file mode 100644
index 0000000000..e401330a12
--- /dev/null
+++ b/documentation/dev-manual/figures/git-workflow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/index-downloads.png b/documentation/dev-manual/figures/index-downloads.png
new file mode 100644
index 0000000000..41251d5d18
--- /dev/null
+++ b/documentation/dev-manual/figures/index-downloads.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png
new file mode 100644
index 0000000000..009105d122
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-dev-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png
new file mode 100644
index 0000000000..116c0b9bd4
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-1.png
Binary files differ
diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png
new file mode 100644
index 0000000000..889ff1bf0d
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-2-generic.png
Binary files differ
diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png
new file mode 100644
index 0000000000..c0e960b13b
--- /dev/null
+++ b/documentation/dev-manual/figures/recipe-workflow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/source-repos.png b/documentation/dev-manual/figures/source-repos.png
new file mode 100644
index 0000000000..65c5f29a43
--- /dev/null
+++ b/documentation/dev-manual/figures/source-repos.png
Binary files differ
diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png
new file mode 100644
index 0000000000..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-20 07:16:04 +0000