summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorTudor Florea <tudor.florea@enea.com>2015-10-09 20:59:03 (GMT)
committerTudor Florea <tudor.florea@enea.com>2015-10-09 20:59:03 (GMT)
commit972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch)
tree97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /documentation/dev-manual
downloadpoky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml9738
-rw-r--r--documentation/dev-manual/dev-manual-customization.xsl19
-rw-r--r--documentation/dev-manual/dev-manual-eclipse-customization.xsl27
-rw-r--r--documentation/dev-manual/dev-manual-intro.xml240
-rw-r--r--documentation/dev-manual/dev-manual-model.xml2112
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml1692
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml419
-rw-r--r--documentation/dev-manual/dev-manual-start.xml418
-rw-r--r--documentation/dev-manual/dev-manual.xml124
-rw-r--r--documentation/dev-manual/dev-style.css984
-rw-r--r--documentation/dev-manual/figures/app-dev-flow.pngbin0 -> 53301 bytes
-rw-r--r--documentation/dev-manual/figures/bsp-dev-flow.pngbin0 -> 42751 bytes
-rw-r--r--documentation/dev-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/dev-manual/figures/git-workflow.pngbin0 -> 26586 bytes
-rw-r--r--documentation/dev-manual/figures/index-downloads.pngbin0 -> 100374 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-dev-flow.pngbin0 -> 35561 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-1.pngbin0 -> 35839 bytes
-rw-r--r--documentation/dev-manual/figures/kernel-overview-2-generic.pngbin0 -> 39931 bytes
-rw-r--r--documentation/dev-manual/figures/recipe-workflow.pngbin0 -> 48276 bytes
-rw-r--r--documentation/dev-manual/figures/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/dev-manual/figures/yp-download.pngbin0 -> 230971 bytes
21 files changed, 15773 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
new file mode 100644
index 0000000..6450429
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,9738 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='extendpoky'>
6
7<title>Common Tasks</title>
8 <para>
9 This chapter describes fundamental procedures such as creating layers,
10 adding new software packages, extending or customizing images,
11 porting work to new hardware (adding a new machine), and so forth.
12 You will find that the procedures documented here occur often in the
13 development cycle using the Yocto Project.
14 </para>
15
16 <section id="understanding-and-creating-layers">
17 <title>Understanding and Creating Layers</title>
18
19 <para>
20 The OpenEmbedded build system supports organizing
21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from
23 each other.
24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular your Metadata, the easier
27 it is to cope with future changes.
28 </para>
29
30 <para>
31 To illustrate how layers are used to keep things modular, consider
32 machine customizations.
33 These types of customizations typically reside in a special layer,
34 rather than a general layer, called a Board Support Package (BSP)
35 Layer.
36 Furthermore, the machine customizations should be isolated from
37 recipes and Metadata that support a new GUI environment,
38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
44 with those machine-specific changes.
45 You can accomplish this through a recipe that is a BitBake append
46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
48 </para>
49
50 <para>
51 </para>
52
53 <section id='yocto-project-layers'>
54 <title>Layers</title>
55
56 <para>
57 The <link linkend='source-directory'>Source Directory</link>
58 contains both general layers and BSP
59 layers right out of the box.
60 You can easily identify layers that ship with a
61 Yocto Project release in the Source Directory by their
62 folder names.
63 Folders that represent layers typically have names that begin with
64 the string <filename>meta-</filename>.
65 <note>
66 It is not a requirement that a layer name begin with the
67 prefix <filename>meta-</filename>, but it is a commonly
68 accepted standard in the Yocto Project community.
69 </note>
70 For example, when you set up the Source Directory structure,
71 you will see several layers:
72 <filename>meta</filename>,
73 <filename>meta-skeleton</filename>,
74 <filename>meta-selftest</filename>,
75 <filename>meta-yocto</filename>, and
76 <filename>meta-yocto-bsp</filename>.
77 Each of these folders represents a distinct layer.
78 </para>
79
80 <para>
81 As another example, if you set up a local copy of the
82 <filename>meta-intel</filename> Git repository
83 and then explore the folder of that general layer,
84 you will discover many Intel-specific BSP layers inside.
85 For more information on BSP layers, see the
86 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
87 section in the Yocto Project Board Support Package (BSP)
88 Developer's Guide.
89 </para>
90 </section>
91
92 <section id='creating-your-own-layer'>
93 <title>Creating Your Own Layer</title>
94
95 <para>
96 It is very easy to create your own layers to use with the
97 OpenEmbedded build system.
98 The Yocto Project ships with scripts that speed up creating
99 general layers and BSP layers.
100 This section describes the steps you perform by hand to create
101 a layer so that you can better understand them.
102 For information about the layer-creation scripts, see the
103 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
104 section in the Yocto Project Board Support Package (BSP)
105 Developer's Guide and the
106 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
107 section further down in this manual.
108 </para>
109
110 <para>
111 Follow these general steps to create your layer:
112 <orderedlist>
113 <listitem><para><emphasis>Check Existing Layers:</emphasis>
114 Before creating a new layer, you should be sure someone
115 has not already created a layer containing the Metadata
116 you need.
117 You can see the
118 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
119 for a list of layers from the OpenEmbedded community
120 that can be used in the Yocto Project.
121 </para></listitem>
122 <listitem><para><emphasis>Create a Directory:</emphasis>
123 Create the directory for your layer.
124 While not strictly required, prepend the name of the
125 folder with the string <filename>meta-</filename>.
126 For example:
127 <literallayout class='monospaced'>
128 meta-mylayer
129 meta-GUI_xyz
130 meta-mymachine
131 </literallayout>
132 </para></listitem>
133 <listitem><para><emphasis>Create a Layer Configuration
134 File:</emphasis>
135 Inside your new layer folder, you need to create a
136 <filename>conf/layer.conf</filename> file.
137 It is easiest to take an existing layer configuration
138 file and copy that to your layer's
139 <filename>conf</filename> directory and then modify the
140 file as needed.</para>
141 <para>The
142 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
143 demonstrates the required syntax:
144 <literallayout class='monospaced'>
145 # We have a conf and classes directory, add to BBPATH
146 BBPATH .= ":${LAYERDIR}"
147
148 # We have recipes-* directories, add to BBFILES
149 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
150 ${LAYERDIR}/recipes-*/*/*.bbappend"
151
152 BBFILE_COLLECTIONS += "yoctobsp"
153 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
154 BBFILE_PRIORITY_yoctobsp = "5"
155 LAYERVERSION_yoctobsp = "3"
156 </literallayout></para>
157 <para>Here is an explanation of the example:
158 <itemizedlist>
159 <listitem><para>The configuration and
160 classes directory is appended to
161 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
162 <note>
163 All non-distro layers, which include all BSP
164 layers, are expected to append the layer
165 directory to the
166 <filename>BBPATH</filename>.
167 On the other hand, distro layers, such as
168 <filename>meta-yocto</filename>, can choose
169 to enforce their own precedence over
170 <filename>BBPATH</filename>.
171 For an example of that syntax, see the
172 <filename>layer.conf</filename> file for
173 the <filename>meta-yocto</filename> layer.
174 </note></para></listitem>
175 <listitem><para>The recipes for the layers are
176 appended to
177 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
178 </para></listitem>
179 <listitem><para>The
180 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
181 variable is then appended with the layer name.
182 </para></listitem>
183 <listitem><para>The
184 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
185 variable is set to a regular expression and is
186 used to match files from
187 <filename>BBFILES</filename> into a particular
188 layer.
189 In this case,
190 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
191 is used to make <filename>BBFILE_PATTERN</filename> match within the
192 layer's path.</para></listitem>
193 <listitem><para>The
194 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
195 variable then assigns a priority to the layer.
196 Applying priorities is useful in situations
197 where the same recipe might appear in multiple
198 layers and allows you to choose the layer
199 that takes precedence.</para></listitem>
200 <listitem><para>The
201 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
202 variable optionally specifies the version of a
203 layer as a single number.</para></listitem>
204 </itemizedlist></para>
205 <para>Note the use of the
206 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
207 variable, which expands to the directory of the current
208 layer.</para>
209 <para>Through the use of the <filename>BBPATH</filename>
210 variable, BitBake locates class files
211 (<filename>.bbclass</filename>),
212 configuration files, and files that are included
213 with <filename>include</filename> and
214 <filename>require</filename> statements.
215 For these cases, BitBake uses the first file that
216 matches the name found in <filename>BBPATH</filename>.
217 This is similar to the way the <filename>PATH</filename>
218 variable is used for binaries.
219 It is recommended, therefore, that you use unique
220 class and configuration
221 filenames in your custom layer.</para></listitem>
222 <listitem><para><emphasis>Add Content:</emphasis> Depending
223 on the type of layer, add the content.
224 If the layer adds support for a machine, add the machine
225 configuration in a <filename>conf/machine/</filename>
226 file within the layer.
227 If the layer adds distro policy, add the distro
228 configuration in a <filename>conf/distro/</filename>
229 file within the layer.
230 If the layer introduces new recipes, put the recipes
231 you need in <filename>recipes-*</filename>
232 subdirectories within the layer.
233 <note>In order to be compliant with the Yocto Project,
234 a layer must contain a
235 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
236 </note></para></listitem>
237 </orderedlist>
238 </para>
239 </section>
240
241 <section id='best-practices-to-follow-when-creating-layers'>
242 <title>Best Practices to Follow When Creating Layers</title>
243
244 <para>
245 To create layers that are easier to maintain and that will
246 not impact builds for other machines, you should consider the
247 information in the following sections.
248 </para>
249
250 <section id='avoid-overlaying-entire-recipes'>
251 <title>Avoid "Overlaying" Entire Recipes</title>
252
253 <para>
254 Avoid "overlaying" entire recipes from other layers in your
255 configuration.
256 In other words, do not copy an entire recipe into your
257 layer and then modify it.
258 Rather, use an append file (<filename>.bbappend</filename>)
259 to override
260 only those parts of the original recipe you need to modify.
261 </para>
262 </section>
263
264 <section id='avoid-duplicating-include-files'>
265 <title>Avoid Duplicating Include Files</title>
266
267 <para>
268 Avoid duplicating include files.
269 Use append files (<filename>.bbappend</filename>)
270 for each recipe
271 that uses an include file.
272 Or, if you are introducing a new recipe that requires
273 the included file, use the path relative to the original
274 layer directory to refer to the file.
275 For example, use
276 <filename>require recipes-core/somepackage/somefile.inc</filename>
277 instead of <filename>require somefile.inc</filename>.
278 If you're finding you have to overlay the include file,
279 it could indicate a deficiency in the include file in
280 the layer to which it originally belongs.
281 If this is the case, you need to address that deficiency
282 instead of overlaying the include file.
283 </para>
284
285 <para>
286 For example, consider how support plug-ins for the Qt 4
287 database are configured.
288 The Source Directory does not have MySQL or PostgreSQL.
289 However, OpenEmbedded's layer <filename>meta-oe</filename>
290 does.
291 Consequently, <filename>meta-oe</filename> uses
292 append files to modify the
293 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
294 enable the appropriate plug-ins.
295 This variable was added to the <filename>qt4.inc</filename>
296 include file in the Source Directory specifically to allow
297 the <filename>meta-oe</filename> layer to be able to control
298 which plug-ins are built.
299 </para>
300 </section>
301
302 <section id='structure-your-layers'>
303 <title>Structure Your Layers</title>
304
305 <para>
306 Proper use of overrides within append files and placement
307 of machine-specific files within your layer can ensure that
308 a build is not using the wrong Metadata and negatively
309 impacting a build for a different machine.
310 Following are some examples:
311 <itemizedlist>
312 <listitem><para><emphasis>Modifying Variables to Support
313 a Different Machine:</emphasis>
314 Suppose you have a layer named
315 <filename>meta-one</filename> that adds support
316 for building machine "one".
317 To do so, you use an append file named
318 <filename>base-files.bbappend</filename> and
319 create a dependency on "foo" by altering the
320 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
321 variable:
322 <literallayout class='monospaced'>
323 DEPENDS = "foo"
324 </literallayout>
325 The dependency is created during any build that
326 includes the layer
327 <filename>meta-one</filename>.
328 However, you might not want this dependency
329 for all machines.
330 For example, suppose you are building for
331 machine "two" but your
332 <filename>bblayers.conf</filename> file has the
333 <filename>meta-one</filename> layer included.
334 During the build, the
335 <filename>base-files</filename> for machine
336 "two" will also have the dependency on
337 <filename>foo</filename>.</para>
338 <para>To make sure your changes apply only when
339 building machine "one", use a machine override
340 with the <filename>DEPENDS</filename> statement:
341 <literallayout class='monospaced'>
342 DEPENDS_one = "foo"
343 </literallayout>
344 You should follow the same strategy when using
345 <filename>_append</filename> and
346 <filename>_prepend</filename> operations:
347 <literallayout class='monospaced'>
348 DEPENDS_append_one = " foo"
349 DEPENDS_prepend_one = "foo "
350 </literallayout>
351 As an actual example, here's a line from the recipe for
352 the OProfile profiler, which lists an extra build-time
353 dependency when building specifically for 64-bit PowerPC:
354 <literallayout class='monospaced'>
355 DEPENDS_append_powerpc64 = " libpfm4"
356 </literallayout>
357 <note>
358 Avoiding "+=" and "=+" and using
359 machine-specific
360 <filename>_append</filename>
361 and <filename>_prepend</filename> operations
362 is recommended as well.
363 </note></para></listitem>
364 <listitem><para><emphasis>Place Machine-Specific Files
365 in Machine-Specific Locations:</emphasis>
366 When you have a base recipe, such as
367 <filename>base-files.bb</filename>, that
368 contains a
369 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
370 statement to a file, you can use an append file
371 to cause the build to use your own version of
372 the file.
373 For example, an append file in your layer at
374 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
375 could extend
376 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
377 using
378 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
379 as follows:
380 <literallayout class='monospaced'>
381 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
382 </literallayout>
383 The build for machine "one" will pick up your
384 machine-specific file as long as you have the
385 file in
386 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
387 However, if you are building for a different
388 machine and the
389 <filename>bblayers.conf</filename> file includes
390 the <filename>meta-one</filename> layer and
391 the location of your machine-specific file is
392 the first location where that file is found
393 according to <filename>FILESPATH</filename>,
394 builds for all machines will also use that
395 machine-specific file.</para>
396 <para>You can make sure that a machine-specific
397 file is used for a particular machine by putting
398 the file in a subdirectory specific to the
399 machine.
400 For example, rather than placing the file in
401 <filename>meta-one/recipes-core/base-files/base-files/</filename>
402 as shown above, put it in
403 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
404 Not only does this make sure the file is used
405 only when building for machine "one", but the
406 build process locates the file more quickly.</para>
407 <para>In summary, you need to place all files
408 referenced from <filename>SRC_URI</filename>
409 in a machine-specific subdirectory within the
410 layer in order to restrict those files to
411 machine-specific builds.</para></listitem>
412 </itemizedlist>
413 </para>
414 </section>
415
416 <section id='other-recommendations'>
417 <title>Other Recommendations</title>
418
419 <para>
420 We also recommend the following:
421 <itemizedlist>
422 <listitem><para>Store custom layers in a Git repository
423 that uses the
424 <filename>meta-<replaceable>layer_name</replaceable></filename> format.
425 </para></listitem>
426 <listitem><para>Clone the repository alongside other
427 <filename>meta</filename> directories in the
428 <link linkend='source-directory'>Source Directory</link>.
429 </para></listitem>
430 </itemizedlist>
431 Following these recommendations keeps your Source Directory and
432 its configuration entirely inside the Yocto Project's core
433 base.
434 </para>
435 </section>
436 </section>
437
438 <section id='enabling-your-layer'>
439 <title>Enabling Your Layer</title>
440
441 <para>
442 Before the OpenEmbedded build system can use your new layer,
443 you need to enable it.
444 To enable your layer, simply add your layer's path to the
445 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
446 variable in your <filename>conf/bblayers.conf</filename> file,
447 which is found in the
448 <link linkend='build-directory'>Build Directory</link>.
449 The following example shows how to enable a layer named
450 <filename>meta-mylayer</filename>:
451 <literallayout class='monospaced'>
452 LCONF_VERSION = "6"
453
454 BBPATH = "${TOPDIR}"
455 BBFILES ?= ""
456
457 BBLAYERS ?= " \
458 $HOME/poky/meta \
459 $HOME/poky/meta-yocto \
460 $HOME/poky/meta-yocto-bsp \
461 $HOME/poky/meta-mylayer \
462 "
463
464 BBLAYERS_NON_REMOVABLE ?= " \
465 $HOME/poky/meta \
466 $HOME/poky/meta-yocto \
467 "
468 </literallayout>
469 </para>
470
471 <para>
472 BitBake parses each <filename>conf/layer.conf</filename> file
473 as specified in the <filename>BBLAYERS</filename> variable
474 within the <filename>conf/bblayers.conf</filename> file.
475 During the processing of each
476 <filename>conf/layer.conf</filename> file, BitBake adds the
477 recipes, classes and configurations contained within the
478 particular layer to the source directory.
479 </para>
480 </section>
481
482 <section id='using-bbappend-files'>
483 <title>Using .bbappend Files</title>
484
485 <para>
486 Recipes used to append Metadata to other recipes are called
487 BitBake append files.
488 BitBake append files use the <filename>.bbappend</filename> file
489 type suffix, while the corresponding recipes to which Metadata
490 is being appended use the <filename>.bb</filename> file type
491 suffix.
492 </para>
493
494 <para>
495 A <filename>.bbappend</filename> file allows your layer to make
496 additions or changes to the content of another layer's recipe
497 without having to copy the other recipe into your layer.
498 Your <filename>.bbappend</filename> file resides in your layer,
499 while the main <filename>.bb</filename> recipe file to
500 which you are appending Metadata resides in a different layer.
501 </para>
502
503 <para>
504 Append files must have the same root names as their corresponding
505 recipes.
506 For example, the append file
507 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
508 <filename>someapp_&DISTRO;.bb</filename>.
509 This means the original recipe and append file names are version
510 number-specific.
511 If the corresponding recipe is renamed to update to a newer
512 version, the corresponding <filename>.bbappend</filename> file must
513 be renamed (and possibly updated) as well.
514 During the build process, BitBake displays an error on starting
515 if it detects a <filename>.bbappend</filename> file that does
516 not have a corresponding recipe with a matching name.
517 See the
518 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
519 variable for information on how to handle this error.
520 </para>
521
522 <para>
523 Being able to append information to an existing recipe not only
524 avoids duplication, but also automatically applies recipe
525 changes in a different layer to your layer.
526 If you were copying recipes, you would have to manually merge
527 changes as they occur.
528 </para>
529
530 <para>
531 As an example, consider the main formfactor recipe and a
532 corresponding formfactor append file both from the
533 <link linkend='source-directory'>Source Directory</link>.
534 Here is the main formfactor recipe, which is named
535 <filename>formfactor_0.0.bb</filename> and located in the
536 "meta" layer at
537 <filename>meta/recipes-bsp/formfactor</filename>:
538 <literallayout class='monospaced'>
539 SUMMARY = "Device formfactor information"
540 SECTION = "base"
541 LICENSE = "MIT"
542 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
543 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
544 PR = "r45"
545
546 SRC_URI = "file://config file://machconfig"
547 S = "${WORKDIR}"
548
549 PACKAGE_ARCH = "${MACHINE_ARCH}"
550 INHIBIT_DEFAULT_DEPS = "1"
551
552 do_install() {
553 # Install file only if it has contents
554 install -d ${D}${sysconfdir}/formfactor/
555 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
556 if [ -s "${S}/machconfig" ]; then
557 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
558 fi
559 }
560 </literallayout>
561 In the main recipe, note the
562 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
563 variable, which tells the OpenEmbedded build system where to
564 find files during the build.
565 </para>
566
567 <para>
568 Following is the append file, which is named
569 <filename>formfactor_0.0.bbappend</filename> and is from the
570 Crown Bay BSP Layer named
571 <filename>meta-intel/meta-crownbay</filename>.
572 The file is in <filename>recipes-bsp/formfactor</filename>:
573 <literallayout class='monospaced'>
574 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
575 </literallayout>
576 </para>
577
578 <para>
579 By default, the build system uses the
580 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
581 variable to locate files.
582 This append file extends the locations by setting the
583 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
584 variable.
585 Setting this variable in the <filename>.bbappend</filename>
586 file is the most reliable and recommended method for adding
587 directories to the search path used by the build system
588 to find files.
589 </para>
590
591 <para>
592 The statement in this example extends the directories to include
593 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
594 which resolves to a directory named
595 <filename>formfactor</filename> in the same directory
596 in which the append file resides (i.e.
597 <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
598 This implies that you must have the supporting directory
599 structure set up that will contain any files or patches you
600 will be including from the layer.
601 </para>
602
603 <para>
604 Using the immediate expansion assignment operator
605 <filename>:=</filename> is important because of the reference to
606 <filename>THISDIR</filename>.
607 The trailing colon character is important as it ensures that
608 items in the list remain colon-separated.
609 <note>
610 <para>
611 BitBake automatically defines the
612 <filename>THISDIR</filename> variable.
613 You should never set this variable yourself.
614 Using "_prepend" ensures your path will
615 be searched prior to other paths in the final list.
616 </para>
617
618 <para>
619 Also, not all append files add extra files.
620 Many append files simply exist to add build options
621 (e.g. <filename>systemd</filename>).
622 For these cases, it is not necessary to use the
623 "_prepend" part of the statement.
624 </para>
625 </note>
626 </para>
627 </section>
628
629 <section id='prioritizing-your-layer'>
630 <title>Prioritizing Your Layer</title>
631
632 <para>
633 Each layer is assigned a priority value.
634 Priority values control which layer takes precedence if there
635 are recipe files with the same name in multiple layers.
636 For these cases, the recipe file from the layer with a higher
637 priority number takes precedence.
638 Priority values also affect the order in which multiple
639 <filename>.bbappend</filename> files for the same recipe are
640 applied.
641 You can either specify the priority manually, or allow the
642 build system to calculate it based on the layer's dependencies.
643 </para>
644
645 <para>
646 To specify the layer's priority manually, use the
647 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
648 variable.
649 For example:
650 <literallayout class='monospaced'>
651 BBFILE_PRIORITY_mylayer = "1"
652 </literallayout>
653 </para>
654
655 <note>
656 <para>It is possible for a recipe with a lower version number
657 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
658 in a layer that has a higher priority to take precedence.</para>
659 <para>Also, the layer priority does not currently affect the
660 precedence order of <filename>.conf</filename>
661 or <filename>.bbclass</filename> files.
662 Future versions of BitBake might address this.</para>
663 </note>
664 </section>
665
666 <section id='managing-layers'>
667 <title>Managing Layers</title>
668
669 <para>
670 You can use the BitBake layer management tool to provide a view
671 into the structure of recipes across a multi-layer project.
672 Being able to generate output that reports on configured layers
673 with their paths and priorities and on
674 <filename>.bbappend</filename> files and their applicable
675 recipes can help to reveal potential problems.
676 </para>
677
678 <para>
679 Use the following form when running the layer management tool.
680 <literallayout class='monospaced'>
681 $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>]
682 </literallayout>
683 The following list describes the available commands:
684 <itemizedlist>
685 <listitem><para><filename><emphasis>help:</emphasis></filename>
686 Displays general help or help on a specified command.
687 </para></listitem>
688 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
689 Shows the current configured layers.
690 </para></listitem>
691 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
692 Lists available recipes and the layers that provide them.
693 </para></listitem>
694 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
695 Lists overlayed recipes.
696 A recipe is overlayed when a recipe with the same name
697 exists in another layer that has a higher layer
698 priority.
699 </para></listitem>
700 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
701 Lists <filename>.bbappend</filename> files and the
702 recipe files to which they apply.
703 </para></listitem>
704 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
705 Lists dependency relationships between recipes that
706 cross layer boundaries.
707 </para></listitem>
708 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
709 Flattens the layer configuration into a separate output
710 directory.
711 Flattening your layer configuration builds a "flattened"
712 directory that contains the contents of all layers,
713 with any overlayed recipes removed and any
714 <filename>.bbappend</filename> files appended to the
715 corresponding recipes.
716 You might have to perform some manual cleanup of the
717 flattened layer as follows:
718 <itemizedlist>
719 <listitem><para>Non-recipe files (such as patches)
720 are overwritten.
721 The flatten command shows a warning for these
722 files.
723 </para></listitem>
724 <listitem><para>Anything beyond the normal layer
725 setup has been added to the
726 <filename>layer.conf</filename> file.
727 Only the lowest priority layer's
728 <filename>layer.conf</filename> is used.
729 </para></listitem>
730 <listitem><para>Overridden and appended items from
731 <filename>.bbappend</filename> files need to be
732 cleaned up.
733 The contents of each
734 <filename>.bbappend</filename> end up in the
735 flattened recipe.
736 However, if there are appended or changed
737 variable values, you need to tidy these up
738 yourself.
739 Consider the following example.
740 Here, the <filename>bitbake-layers</filename>
741 command adds the line
742 <filename>#### bbappended ...</filename> so that
743 you know where the following lines originate:
744 <literallayout class='monospaced'>
745 ...
746 DESCRIPTION = "A useful utility"
747 ...
748 EXTRA_OECONF = "&dash;&dash;enable-something"
749 ...
750
751 #### bbappended from meta-anotherlayer ####
752
753 DESCRIPTION = "Customized utility"
754 EXTRA_OECONF += "&dash;&dash;enable-somethingelse"
755 </literallayout>
756 Ideally, you would tidy up these utilities as
757 follows:
758 <literallayout class='monospaced'>
759 ...
760 DESCRIPTION = "Customized utility"
761 ...
762 EXTRA_OECONF = "&dash;&dash;enable-something &dash;&dash;enable-somethingelse"
763 ...
764 </literallayout></para></listitem>
765 </itemizedlist></para></listitem>
766 </itemizedlist>
767 </para>
768 </section>
769
770 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
771 <title>Creating a General Layer Using the yocto-layer Script</title>
772
773 <para>
774 The <filename>yocto-layer</filename> script simplifies
775 creating a new general layer.
776 <note>
777 For information on BSP layers, see the
778 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
779 section in the Yocto Project Board Specific (BSP)
780 Developer's Guide.
781 </note>
782 The default mode of the script's operation is to prompt you for
783 information needed to generate the layer:
784 <itemizedlist>
785 <listitem><para>The layer priority.
786 </para></listitem>
787 <listitem><para>Whether or not to create a sample recipe.
788 </para></listitem>
789 <listitem><para>Whether or not to create a sample
790 append file.
791 </para></listitem>
792 </itemizedlist>
793 </para>
794
795 <para>
796 Use the <filename>yocto-layer create</filename> sub-command
797 to create a new general layer.
798 In its simplest form, you can create a layer as follows:
799 <literallayout class='monospaced'>
800 $ yocto-layer create mylayer
801 </literallayout>
802 The previous example creates a layer named
803 <filename>meta-mylayer</filename> in the current directory.
804 </para>
805
806 <para>
807 As the <filename>yocto-layer create</filename> command runs,
808 default values for the prompts appear in brackets.
809 Pressing enter without supplying anything for the prompts
810 or pressing enter and providing an invalid response causes the
811 script to accept the default value.
812 Once the script completes, the new layer
813 is created in the current working directory.
814 The script names the layer by prepending
815 <filename>meta-</filename> to the name you provide.
816 </para>
817
818 <para>
819 Minimally, the script creates the following within the layer:
820 <itemizedlist>
821 <listitem><para><emphasis>The <filename>conf</filename>
822 directory:</emphasis>
823 This directory contains the layer's configuration file.
824 The root name for the file is the same as the root name
825 your provided for the layer (e.g.
826 <filename><replaceable>layer</replaceable>.conf</filename>).
827 </para></listitem>
828 <listitem><para><emphasis>The
829 <filename>COPYING.MIT</filename> file:</emphasis>
830 The copyright and use notice for the software.
831 </para></listitem>
832 <listitem><para><emphasis>The <filename>README</filename>
833 file:</emphasis>
834 A file describing the contents of your new layer.
835 </para></listitem>
836 </itemizedlist>
837 </para>
838
839 <para>
840 If you choose to generate a sample recipe file, the script
841 prompts you for the name for the recipe and then creates it
842 in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>.
843 The script creates a <filename>.bb</filename> file and a
844 directory, which contains a sample
845 <filename>helloworld.c</filename> source file, along with
846 a sample patch file.
847 If you do not provide a recipe name, the script uses
848 "example".
849 </para>
850
851 <para>
852 If you choose to generate a sample append file, the script
853 prompts you for the name for the file and then creates it
854 in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>.
855 The script creates a <filename>.bbappend</filename> file and a
856 directory, which contains a sample patch file.
857 If you do not provide a recipe name, the script uses
858 "example".
859 The script also prompts you for the version of the append file.
860 The version should match the recipe to which the append file
861 is associated.
862 </para>
863
864 <para>
865 The easiest way to see how the <filename>yocto-layer</filename>
866 script works is to experiment with the script.
867 You can also read the usage information by entering the
868 following:
869 <literallayout class='monospaced'>
870 $ yocto-layer help
871 </literallayout>
872 </para>
873
874 <para>
875 Once you create your general layer, you must add it to your
876 <filename>bblayers.conf</filename> file.
877 Here is an example where a layer named
878 <filename>meta-mylayer</filename> is added:
879 <literallayout class='monospaced'>
880 BBLAYERS = ?" \
881 /usr/local/src/yocto/meta \
882 /usr/local/src/yocto/meta-yocto \
883 /usr/local/src/yocto/meta-yocto-bsp \
884 /usr/local/src/yocto/meta-mylayer \
885 "
886
887 BBLAYERS_NON_REMOVABLE ?= " \
888 /usr/local/src/yocto/meta \
889 /usr/local/src/yocto/meta-yocto \
890 "
891 </literallayout>
892 Adding the layer to this file enables the build system to
893 locate the layer during the build.
894 </para>
895 </section>
896 </section>
897
898 <section id='usingpoky-extend-customimage'>
899 <title>Customizing Images</title>
900
901 <para>
902 You can customize images to satisfy particular requirements.
903 This section describes several methods and provides guidelines for each.
904 </para>
905
906 <section id='usingpoky-extend-customimage-localconf'>
907 <title>Customizing Images Using <filename>local.conf</filename></title>
908
909 <para>
910 Probably the easiest way to customize an image is to add a
911 package by way of the <filename>local.conf</filename>
912 configuration file.
913 Because it is limited to local use, this method generally only
914 allows you to add packages and is not as flexible as creating
915 your own customized image.
916 When you add packages using local variables this way, you need
917 to realize that these variable changes are in effect for every
918 build and consequently affect all images, which might not
919 be what you require.
920 </para>
921
922 <para>
923 To add a package to your image using the local configuration
924 file, use the
925 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
926 variable with the <filename>_append</filename> operator:
927 <literallayout class='monospaced'>
928 IMAGE_INSTALL_append = " strace"
929 </literallayout>
930 Use of the syntax is important - specifically, the space between
931 the quote and the package name, which is
932 <filename>strace</filename> in this example.
933 This space is required since the <filename>_append</filename>
934 operator does not add the space.
935 </para>
936
937 <para>
938 Furthermore, you must use <filename>_append</filename> instead
939 of the <filename>+=</filename> operator if you want to avoid
940 ordering issues.
941 The reason for this is because doing so unconditionally appends
942 to the variable and avoids ordering problems due to the
943 variable being set in image recipes and
944 <filename>.bbclass</filename> files with operators like
945 <filename>?=</filename>.
946 Using <filename>_append</filename> ensures the operation takes
947 affect.
948 </para>
949
950 <para>
951 As shown in its simplest use,
952 <filename>IMAGE_INSTALL_append</filename> affects all images.
953 It is possible to extend the syntax so that the variable
954 applies to a specific image only.
955 Here is an example:
956 <literallayout class='monospaced'>
957 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
958 </literallayout>
959 This example adds <filename>strace</filename> to the
960 <filename>core-image-minimal</filename> image only.
961 </para>
962
963 <para>
964 You can add packages using a similar approach through the
965 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
966 variable.
967 If you use this variable, only
968 <filename>core-image-*</filename> images are affected.
969 </para>
970 </section>
971
972 <section id='usingpoky-extend-customimage-imagefeatures'>
973 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
974 <filename>EXTRA_IMAGE_FEATURES</filename></title>
975
976 <para>
977 Another method for customizing your image is to enable or
978 disable high-level image features by using the
979 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
980 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
981 variables.
982 Although the functions for both variables are nearly equivalent,
983 best practices dictate using <filename>IMAGE_FEATURES</filename>
984 from within a recipe and using
985 <filename>EXTRA_IMAGE_FEATURES</filename> from within
986 your <filename>local.conf</filename> file, which is found in the
987 <link linkend='build-directory'>Build Directory</link>.
988 </para>
989
990 <para>
991 To understand how these features work, the best reference is
992 <filename>meta/classes/core-image.bbclass</filename>.
993 In summary, the file looks at the contents of the
994 <filename>IMAGE_FEATURES</filename> variable and then maps
995 those contents into a set of package groups.
996 Based on this information, the build system automatically
997 adds the appropriate packages to the
998 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
999 variable.
1000 Effectively, you are enabling extra features by extending the
1001 class or creating a custom class for use with specialized image
1002 <filename>.bb</filename> files.
1003 </para>
1004
1005 <para>
1006 Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
1007 from within your local configuration file.
1008 Using a separate area from which to enable features with
1009 this variable helps you avoid overwriting the features in the
1010 image recipe that are enabled with
1011 <filename>IMAGE_FEATURES</filename>.
1012 The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
1013 to <filename>IMAGE_FEATURES</filename> within
1014 <filename>meta/conf/bitbake.conf</filename>.
1015 </para>
1016
1017 <para>
1018 To illustrate how you can use these variables to modify your
1019 image, consider an example that selects the SSH server.
1020 The Yocto Project ships with two SSH servers you can use
1021 with your images: Dropbear and OpenSSH.
1022 Dropbear is a minimal SSH server appropriate for
1023 resource-constrained environments, while OpenSSH is a
1024 well-known standard SSH server implementation.
1025 By default, the <filename>core-image-sato</filename> image
1026 is configured to use Dropbear.
1027 The <filename>core-image-full-cmdline</filename> and
1028 <filename>core-image-lsb</filename> images both
1029 include OpenSSH.
1030 The <filename>core-image-minimal</filename> image does not
1031 contain an SSH server.
1032 </para>
1033
1034 <para>
1035 You can customize your image and change these defaults.
1036 Edit the <filename>IMAGE_FEATURES</filename> variable
1037 in your recipe or use the
1038 <filename>EXTRA_IMAGE_FEATURES</filename> in your
1039 <filename>local.conf</filename> file so that it configures the
1040 image you are working with to include
1041 <filename>ssh-server-dropbear</filename> or
1042 <filename>ssh-server-openssh</filename>.
1043 </para>
1044
1045 <note>
1046 See the
1047 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1048 section in the Yocto Project Reference Manual for a complete
1049 list of image features that ship with the Yocto Project.
1050 </note>
1051 </section>
1052
1053 <section id='usingpoky-extend-customimage-custombb'>
1054 <title>Customizing Images Using Custom .bb Files</title>
1055
1056 <para>
1057 You can also customize an image by creating a custom recipe
1058 that defines additional software as part of the image.
1059 The following example shows the form for the two lines you need:
1060 <literallayout class='monospaced'>
1061 IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
1062
1063 inherit core-image
1064 </literallayout>
1065 </para>
1066
1067 <para>
1068 Defining the software using a custom recipe gives you total
1069 control over the contents of the image.
1070 It is important to use the correct names of packages in the
1071 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
1072 variable.
1073 You must use the OpenEmbedded notation and not the Debian notation for the names
1074 (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>).
1075 </para>
1076
1077 <para>
1078 The other method for creating a custom image is to base it on an existing image.
1079 For example, if you want to create an image based on <filename>core-image-sato</filename>
1080 but add the additional package <filename>strace</filename> to the image,
1081 copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
1082 new <filename>.bb</filename> and add the following line to the end of the copy:
1083 <literallayout class='monospaced'>
1084 IMAGE_INSTALL += "strace"
1085 </literallayout>
1086 </para>
1087 </section>
1088
1089 <section id='usingpoky-extend-customimage-customtasks'>
1090 <title>Customizing Images Using Custom Package Groups</title>
1091
1092 <para>
1093 For complex custom images, the best approach for customizing
1094 an image is to create a custom package group recipe that is
1095 used to build the image or images.
1096 A good example of a package group recipe is
1097 <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
1098 The
1099 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
1100 variable lists the package group packages you wish to produce.
1101 <filename>inherit packagegroup</filename> sets appropriate
1102 default values and automatically adds <filename>-dev</filename>,
1103 <filename>-dbg</filename>, and <filename>-ptest</filename>
1104 complementary packages for every package specified in
1105 <filename>PACKAGES</filename>.
1106 Note that the inherit line should be towards
1107 the top of the recipe, certainly before you set
1108 <filename>PACKAGES</filename>.
1109 For each package you specify in <filename>PACKAGES</filename>,
1110 you can use
1111 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
1112 and
1113 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
1114 entries to provide a list of packages the parent task package
1115 should contain.
1116 Following is an example:
1117 <literallayout class='monospaced'>
1118 DESCRIPTION = "My Custom Package Groups"
1119
1120 inherit packagegroup
1121
1122 PACKAGES = "\
1123 packagegroup-custom-apps \
1124 packagegroup-custom-tools \
1125 "
1126
1127 RDEPENDS_packagegroup-custom-apps = "\
1128 dropbear \
1129 portmap \
1130 psplash"
1131
1132 RDEPENDS_packagegroup-custom-tools = "\
1133 oprofile \
1134 oprofileui-server \
1135 lttng-control \
1136 lttng-viewer"
1137
1138 RRECOMMENDS_packagegroup-custom-tools = "\
1139 kernel-module-oprofile"
1140 </literallayout>
1141 </para>
1142
1143 <para>
1144 In the previous example, two package group packages are created with their dependencies and their
1145 recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
1146 <filename>packagegroup-custom-tools</filename>.
1147 To build an image using these package group packages, you need to add
1148 <filename>packagegroup-custom-apps</filename> and/or
1149 <filename>packagegroup-custom-tools</filename> to
1150 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
1151 For other forms of image dependencies see the other areas of this section.
1152 </para>
1153 </section>
1154 </section>
1155
1156 <section id='new-recipe-writing-a-new-recipe'>
1157 <title>Writing a New Recipe</title>
1158
1159 <para>
1160 Recipes (<filename>.bb</filename> files) are fundamental components
1161 in the Yocto Project environment.
1162 Each software component built by the OpenEmbedded build system
1163 requires a recipe to define the component.
1164 This section describes how to create, write, and test a new
1165 recipe.
1166 <note>
1167 For information on variables that are useful for recipes and
1168 for information about recipe naming issues, see the
1169 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
1170 section of the Yocto Project Reference Manual.
1171 </note>
1172 </para>
1173
1174 <section id='new-recipe-overview'>
1175 <title>Overview</title>
1176
1177 <para>
1178 The following figure shows the basic process for creating a
1179 new recipe.
1180 The remainder of the section provides details for the steps.
1181 <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" />
1182 </para>
1183 </section>
1184
1185 <section id='new-recipe-locate-a-base-recipe'>
1186 <title>Locate a Base Recipe</title>
1187
1188 <para>
1189 Before writing a recipe from scratch, it is often useful to
1190 discover whether someone else has already written one that
1191 meets (or comes close to meeting) your needs.
1192 The Yocto Project and OpenEmbedded communities maintain many
1193 recipes that might be candidates for what you are doing.
1194 You can find a good central index of these recipes in the
1195 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1196 </para>
1197
1198 <para>
1199 Working from an existing recipe or a skeleton recipe is the
1200 best way to get started.
1201 Here are some points on both methods:
1202 <itemizedlist>
1203 <listitem><para><emphasis>Locate and modify a recipe that
1204 is close to what you want to do:</emphasis>
1205 This method works when you are familiar with the
1206 current recipe space.
1207 The method does not work so well for those new to
1208 the Yocto Project or writing recipes.</para>
1209 <para>Some risks associated with this method are
1210 using a recipe that has areas totally unrelated to
1211 what you are trying to accomplish with your recipe,
1212 not recognizing areas of the recipe that you might
1213 have to add from scratch, and so forth.
1214 All these risks stem from unfamiliarity with the
1215 existing recipe space.</para></listitem>
1216 <listitem><para><emphasis>Use and modify the following
1217 skeleton recipe:</emphasis>
1218 <literallayout class='monospaced'>
1219 SUMMARY = ""
1220 HOMEPAGE = ""
1221 LICENSE = ""
1222
1223 LIC_FILES_CHKSUM = ""
1224
1225 SRC_URI = ""
1226 SRC_URI[md5sum] = ""
1227 SRC_URI[sha256sum] = ""
1228
1229 S = "${WORKDIR}/${PN}-${PV}"
1230
1231 inherit <replaceable>stuff</replaceable>
1232 </literallayout>
1233 Modifying this recipe is the recommended method for
1234 creating a new recipe.
1235 The recipe provides the fundamental areas that you need
1236 to include, exclude, or alter to fit your needs.
1237 </para></listitem>
1238 </itemizedlist>
1239 </para>
1240 </section>
1241
1242 <section id='new-recipe-storing-and-naming-the-recipe'>
1243 <title>Storing and Naming the Recipe</title>
1244
1245 <para>
1246 Once you have your base recipe, you should put it in your
1247 own layer and name it appropriately.
1248 Locating it correctly ensures that the OpenEmbedded build
1249 system can find it when you use BitBake to process the
1250 recipe.
1251 </para>
1252
1253 <itemizedlist>
1254 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1255 The OpenEmbedded build system locates your recipe
1256 through the layer's <filename>conf/layer.conf</filename>
1257 file and the
1258 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1259 variable.
1260 This variable sets up a path from which the build system can
1261 locate recipes.
1262 Here is the typical use:
1263 <literallayout class='monospaced'>
1264 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1265 ${LAYERDIR}/recipes-*/*/*.bbappend"
1266 </literallayout>
1267 Consequently, you need to be sure you locate your new recipe
1268 inside your layer such that it can be found.</para>
1269 <para>You can find more information on how layers are
1270 structured in the
1271 "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
1272 section.</para></listitem>
1273 <listitem><para><emphasis>Naming Your Recipe:</emphasis>
1274 When you name your recipe, you need to follow this naming
1275 convention:
1276 <literallayout class='monospaced'>
1277 <replaceable>basename</replaceable>_<replaceable>version</replaceable>.bb
1278 </literallayout>
1279 Use lower-cased characters and do not include the reserved
1280 suffixes <filename>-native</filename>,
1281 <filename>-cross</filename>, <filename>-initial</filename>,
1282 or <filename>-dev</filename> casually (i.e. do not use them
1283 as part of your recipe name unless the string applies).
1284 Here are some examples:
1285 <literallayout class='monospaced'>
1286 cups_1.7.0.bb
1287 gawk_4.0.2.bb
1288 irssi_0.8.16-rc1.bb
1289 </literallayout></para></listitem>
1290 </itemizedlist>
1291 </section>
1292
1293 <section id='understanding-recipe-syntax'>
1294 <title>Understanding Recipe Syntax</title>
1295
1296 <para>
1297 Understanding recipe file syntax is important for
1298 writing recipes.
1299 The following list overviews the basic items that make up a
1300 BitBake recipe file.
1301 For more complete BitBake syntax descriptions, see the
1302 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
1303 chapter of the BitBake User Manual.
1304 <itemizedlist>
1305 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1306 Variable assignments allow a value to be assigned to a
1307 variable.
1308 The assignment can be static text or might include
1309 the contents of other variables.
1310 In addition to the assignment, appending and prepending
1311 operations are also supported.</para>
1312 <para>The following example shows some of the ways
1313 you can use variables in recipes:
1314 <literallayout class='monospaced'>
1315 S = "${WORKDIR}/postfix-${PV}"
1316 CFLAGS += "-DNO_ASM"
1317 SRC_URI_append = " file://fixup.patch"
1318 </literallayout>
1319 </para></listitem>
1320 <listitem><para><emphasis>Functions:</emphasis>
1321 Functions provide a series of actions to be performed.
1322 You usually use functions to override the default
1323 implementation of a task function or to complement
1324 a default function (i.e. append or prepend to an
1325 existing function).
1326 Standard functions use <filename>sh</filename> shell
1327 syntax, although access to OpenEmbedded variables and
1328 internal methods are also available.</para>
1329 <para>The following is an example function from the
1330 <filename>sed</filename> recipe:
1331 <literallayout class='monospaced'>
1332 do_install () {
1333 autotools_do_install
1334 install -d ${D}${base_bindir}
1335 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
1336 rmdir ${D}${bindir}/
1337 }
1338 </literallayout>
1339 It is also possible to implement new functions that
1340 are called between existing tasks as long as the
1341 new functions are not replacing or complementing the
1342 default functions.
1343 You can implement functions in Python
1344 instead of shell.
1345 Both of these options are not seen in the majority of
1346 recipes.</para></listitem>
1347 <listitem><para><emphasis>Keywords:</emphasis>
1348 BitBake recipes use only a few keywords.
1349 You use keywords to include common
1350 functions (<filename>inherit</filename>), load parts
1351 of a recipe from other files
1352 (<filename>include</filename> and
1353 <filename>require</filename>) and export variables
1354 to the environment (<filename>export</filename>).</para>
1355 <para>The following example shows the use of some of
1356 these keywords:
1357 <literallayout class='monospaced'>
1358 export POSTCONF = "${STAGING_BINDIR}/postconf"
1359 inherit autoconf
1360 require otherfile.inc
1361 </literallayout>
1362 </para></listitem>
1363 <listitem><para><emphasis>Comments:</emphasis>
1364 Any lines that begin with the hash character
1365 (<filename>#</filename>) are treated as comment lines
1366 and are ignored:
1367 <literallayout class='monospaced'>
1368 # This is a comment
1369 </literallayout>
1370 </para></listitem>
1371 </itemizedlist>
1372 </para>
1373
1374 <para>
1375 This next list summarizes the most important and most commonly
1376 used parts of the recipe syntax.
1377 For more information on these parts of the syntax, you can
1378 reference the
1379 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1380 chapter in the BitBake User Manual.
1381 <itemizedlist>
1382 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1383 Use the backward slash (<filename>\</filename>)
1384 character to split a statement over multiple lines.
1385 Place the slash character at the end of the line that
1386 is to be continued on the next line:
1387 <literallayout class='monospaced'>
1388 VAR = "A really long \
1389 line"
1390 </literallayout>
1391 <note>
1392 You cannot have any characters including spaces
1393 or tabs after the slash character.
1394 </note>
1395 </para></listitem>
1396 <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1397 Use the <filename>${<replaceable>varname</replaceable>}</filename> syntax to
1398 access the contents of a variable:
1399 <literallayout class='monospaced'>
1400 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1401 </literallayout>
1402 </para></listitem>
1403 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1404 Use double quotes around the value in all variable
1405 assignments.
1406 <literallayout class='monospaced'>
1407 VAR1 = "${OTHERVAR}"
1408 VAR2 = "The version is ${PV}"
1409 </literallayout>
1410 </para></listitem>
1411 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1412 Conditional assignment is used to assign a value to
1413 a variable, but only when the variable is currently
1414 unset.
1415 Use the question mark followed by the equal sign
1416 (<filename>?=</filename>) to make a "soft" assignment
1417 used for conditional assignment.
1418 Typically, "soft" assignments are used in the
1419 <filename>local.conf</filename> file for variables
1420 that are allowed to come through from the external
1421 environment.
1422 </para>
1423 <para>Here is an example where
1424 <filename>VAR1</filename> is set to "New value" if
1425 it is currently empty.
1426 However, if <filename>VAR1</filename> has already been
1427 set, it remains unchanged:
1428 <literallayout class='monospaced'>
1429 VAR1 ?= "New value"
1430 </literallayout>
1431 In this next example, <filename>VAR1</filename>
1432 is left with the value "Original value":
1433 <literallayout class='monospaced'>
1434 VAR1 = "Original value"
1435 VAR1 ?= "New value"
1436 </literallayout>
1437 </para></listitem>
1438 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1439 Use the plus character followed by the equals sign
1440 (<filename>+=</filename>) to append values to existing
1441 variables.
1442 <note>
1443 This operator adds a space between the existing
1444 content of the variable and the new content.
1445 </note></para>
1446 <para>Here is an example:
1447 <literallayout class='monospaced'>
1448 SRC_URI += "file://fix-makefile.patch"
1449 </literallayout>
1450 </para></listitem>
1451 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1452 Use the equals sign followed by the plus character
1453 (<filename>=+</filename>) to prepend values to existing
1454 variables.
1455 <note>
1456 This operator adds a space between the new content
1457 and the existing content of the variable.
1458 </note></para>
1459 <para>Here is an example:
1460 <literallayout class='monospaced'>
1461 VAR =+ "Starts"
1462 </literallayout>
1463 </para></listitem>
1464 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1465 Use the <filename>_append</filename> operator to
1466 append values to existing variables.
1467 This operator does not add any additional space.
1468 Also, the operator is applied after all the
1469 <filename>+=</filename>, and
1470 <filename>=+</filename> operators have been applied and
1471 after all <filename>=</filename> assignments have
1472 occurred.
1473 </para>
1474 <para>The following example shows the space being
1475 explicitly added to the start to ensure the appended
1476 value is not merged with the existing value:
1477 <literallayout class='monospaced'>
1478 SRC_URI_append = " file://fix-makefile.patch"
1479 </literallayout>
1480 You can also use the <filename>_append</filename>
1481 operator with overrides, which results in the actions
1482 only being performed for the specified target or
1483 machine:
1484 <literallayout class='monospaced'>
1485 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1486 </literallayout>
1487 </para></listitem>
1488 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1489 Use the <filename>_prepend</filename> operator to
1490 prepend values to existing variables.
1491 This operator does not add any additional space.
1492 Also, the operator is applied after all the
1493 <filename>+=</filename>, and
1494 <filename>=+</filename> operators have been applied and
1495 after all <filename>=</filename> assignments have
1496 occurred.
1497 </para>
1498 <para>The following example shows the space being
1499 explicitly added to the end to ensure the prepended
1500 value is not merged with the existing value:
1501 <literallayout class='monospaced'>
1502 CFLAGS_prepend = "-I${S}/myincludes "
1503 </literallayout>
1504 You can also use the <filename>_prepend</filename>
1505 operator with overrides, which results in the actions
1506 only being performed for the specified target or
1507 machine:
1508 <literallayout class='monospaced'>
1509 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1510 </literallayout>
1511 </para></listitem>
1512 <listitem><para><emphasis>Overrides:</emphasis> -
1513 You can use overrides to set a value conditionally,
1514 typically based on how the recipe is being built.
1515 For example, to set the
1516 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1517 variable's value to "standard/base" for any target
1518 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1519 except for qemuarm where it should be set to
1520 "standard/arm-versatile-926ejs", you would do the
1521 following:
1522 <literallayout class='monospaced'>
1523 KBRANCH = "standard/base"
1524 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1525 </literallayout>
1526 Overrides are also used to separate alternate values
1527 of a variable in other situations.
1528 For example, when setting variables such as
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1530 and
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1532 that are specific to individual packages produced by
1533 a recipe, you should always use an override that
1534 specifies the name of the package.
1535 </para></listitem>
1536 <listitem><para><emphasis>Indentation:</emphasis>
1537 Use spaces for indentation rather than than tabs.
1538 For shell functions, both currently work.
1539 However, it is a policy decision of the Yocto Project
1540 to use tabs in shell functions.
1541 Realize that some layers have a policy to use spaces
1542 for all indentation.
1543 </para></listitem>
1544 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1545 For more advanced processing, it is possible to use
1546 Python code during variable assignments (e.g.
1547 search and replacement on a variable).</para>
1548 <para>You indicate Python code using the
1549 <filename>${@<replaceable>python_code</replaceable>}</filename>
1550 syntax for the variable assignment:
1551 <literallayout class='monospaced'>
1552 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1553 </literallayout>
1554 </para></listitem>
1555 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1556 Write shell functions as if you were writing a shell
1557 script when you describe a list of actions to take.
1558 You should ensure that your script works with a generic
1559 <filename>sh</filename> and that it does not require
1560 any <filename>bash</filename> or other shell-specific
1561 functionality.
1562 The same considerations apply to various system
1563 utilities (e.g. <filename>sed</filename>,
1564 <filename>grep</filename>, <filename>awk</filename>,
1565 and so forth) that you might wish to use.
1566 If in doubt, you should check with multiple
1567 implementations - including those from BusyBox.
1568 </para></listitem>
1569 </itemizedlist>
1570 </para>
1571 </section>
1572
1573 <section id='new-recipe-running-a-build-on-the-recipe'>
1574 <title>Running a Build on the Recipe</title>
1575
1576 <para>
1577 Creating a new recipe is usually an iterative process that
1578 requires using BitBake to process the recipe multiple times in
1579 order to progressively discover and add information to the
1580 recipe file.
1581 </para>
1582
1583 <para>
1584 Assuming you have sourced a build environment setup script (i.e.
1585 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1586 or
1587 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
1588 and you are in the
1589 <link linkend='build-directory'>Build Directory</link>,
1590 use BitBake to process your recipe.
1591 All you need to provide is the
1592 <filename><replaceable>basename</replaceable></filename> of the recipe as described
1593 in the previous section:
1594 <literallayout class='monospaced'>
1595 $ bitbake <replaceable>basename</replaceable>
1596 </literallayout>
1597
1598 </para>
1599
1600 <para>
1601 During the build, the OpenEmbedded build system creates a
1602 temporary work directory for each recipe
1603 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1604 where it keeps extracted source files, log files, intermediate
1605 compilation and packaging files, and so forth.
1606 </para>
1607
1608 <para>
1609 The per-recipe temporary work directory is constructed as follows and
1610 depends on several factors:
1611 <literallayout class='monospaced'>
1612 BASE_WORKDIR ?= "${TMPDIR}/work"
1613 WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
1614 </literallayout>
1615 As an example, assume a Source Directory top-level folder named
1616 <filename>poky</filename>, a default Build Directory at
1617 <filename>poky/build</filename>, and a
1618 <filename>qemux86-poky-linux</filename> machine target system.
1619 Furthermore, suppose your recipe is named
1620 <filename>foo_1.3.0.bb</filename>.
1621 In this case, the work directory the build system uses to
1622 build the package would be as follows:
1623 <literallayout class='monospaced'>
1624 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1625 </literallayout>
1626 Inside this directory you can find sub-directories such as
1627 <filename>image</filename>, <filename>packages-split</filename>,
1628 and <filename>temp</filename>.
1629 After the build, you can examine these to determine how well
1630 the build went.
1631 <note>
1632 You can find log files for each task in the recipe's
1633 <filename>temp</filename> directory (e.g.
1634 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1635 Log files are named <filename>log.<replaceable>taskname</replaceable></filename>
1636 (e.g. <filename>log.do_configure</filename>,
1637 <filename>log.do_fetch</filename>, and
1638 <filename>log.do_compile</filename>).
1639 </note>
1640 </para>
1641
1642 <para>
1643 You can find more information about the build process in the
1644 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1645 chapter of the Yocto Project Reference Manual.
1646 </para>
1647
1648 <para>
1649 You can also reference the following variables in the
1650 Yocto Project Reference Manual's glossary for more information:
1651 <itemizedlist>
1652 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1653 The top-level build output directory</listitem>
1654 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1655 The target system identifier</listitem>
1656 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1657 The recipe name</listitem>
1658 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1659 The epoch - (if
1660 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1661 is not specified, which is usually the case for most
1662 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1663 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1664 The recipe version</listitem>
1665 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1666 The recipe revision</listitem>
1667 </itemizedlist>
1668 </para>
1669 </section>
1670
1671 <section id='new-recipe-fetching-code'>
1672 <title>Fetching Code</title>
1673
1674 <para>
1675 The first thing your recipe must do is specify how to fetch
1676 the source files.
1677 Fetching is controlled mainly through the
1678 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1679 variable.
1680 Your recipe must have a <filename>SRC_URI</filename> variable
1681 that points to where the source is located.
1682 For a graphical representation of source locations, see the
1683 "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
1684 section in the Yocto Project Reference Manual.
1685 </para>
1686
1687 <para>
1688 The
1689 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1690 task uses the prefix of each entry in the
1691 <filename>SRC_URI</filename> variable value to determine which
1692 fetcher to use to get your source files.
1693 It is the <filename>SRC_URI</filename> variable that triggers
1694 the fetcher.
1695 The
1696 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1697 task uses the variable after source is fetched to apply
1698 patches.
1699 The OpenEmbedded build system uses
1700 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1701 for scanning directory locations for local files in
1702 <filename>SRC_URI</filename>.
1703 </para>
1704
1705 <para>
1706 The <filename>SRC_URI</filename> variable in your recipe must
1707 define each unique location for your source files.
1708 It is good practice to not hard-code pathnames in an URL used
1709 in <filename>SRC_URI</filename>.
1710 Rather than hard-code these paths, use
1711 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1712 which causes the fetch process to use the version specified in
1713 the recipe filename.
1714 Specifying the version in this manner means that upgrading the
1715 recipe to a future version is as simple as renaming the recipe
1716 to match the new version.
1717 </para>
1718
1719 <para>
1720 Here is a simple example from the
1721 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb</filename>
1722 recipe where the source comes from a single tarball.
1723 Notice the use of the
1724 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1725 variable:
1726 <literallayout class='monospaced'>
1727 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1728 </literallayout>
1729 </para>
1730
1731 <para>
1732 Files mentioned in <filename>SRC_URI</filename> whose names end
1733 in a typical archive extension (e.g. <filename>.tar</filename>,
1734 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1735 <filename>.zip</filename>, and so forth), are automatically
1736 extracted during the
1737 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1738 task.
1739 For another example that specifies these types of files, see
1740 the
1741 "<link linkend='new-recipe-autotooled-package'>Autotooled Package</link>"
1742 section.
1743 </para>
1744
1745 <para>
1746 Another way of specifying source is from an SCM.
1747 For Git repositories, you must specify
1748 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1749 and you should specify
1750 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1751 to include the revision with
1752 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1753 Here is an example from the recipe
1754 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1755 <literallayout class='monospaced'>
1756 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1757
1758 PR = "r6"
1759 PV = "1.0.5+git${SRCPV}"
1760
1761 SRC_URI = "git://git.kernel.dk/blktrace.git \
1762 file://ldflags.patch"
1763 </literallayout>
1764 </para>
1765
1766 <para>
1767 If your <filename>SRC_URI</filename> statement includes
1768 URLs pointing to individual files fetched from a remote server
1769 other than a version control system, BitBake attempts to
1770 verify the files against checksums defined in your recipe to
1771 ensure they have not been tampered with or otherwise modified
1772 since the recipe was written.
1773 Two checksums are used:
1774 <filename>SRC_URI[md5sum]</filename> and
1775 <filename>SRC_URI[sha256sum]</filename>.
1776 </para>
1777
1778 <para>
1779 If your <filename>SRC_URI</filename> variable points to
1780 more than a single URL (excluding SCM URLs), you need to
1781 provide the <filename>md5</filename> and
1782 <filename>sha256</filename> checksums for each URL.
1783 For these cases, you provide a name for each URL as part of
1784 the <filename>SRC_URI</filename> and then reference that name
1785 in the subsequent checksum statements.
1786 Here is an example:
1787 <literallayout class='monospaced'>
1788 SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \
1789 ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch
1790
1791 SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8"
1792 SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d"
1793
1794 SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92"
1795 SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430"
1796 </literallayout>
1797 </para>
1798
1799 <para>
1800 Proper values for <filename>md5</filename> and
1801 <filename>sha256</filename> checksums might be available
1802 with other signatures on the download page for the upstream
1803 source (e.g. <filename>md5</filename>,
1804 <filename>sha1</filename>, <filename>sha256</filename>,
1805 <filename>GPG</filename>, and so forth).
1806 Because the OpenEmbedded build system only deals with
1807 <filename>sha256sum</filename> and <filename>md5sum</filename>,
1808 you should verify all the signatures you find by hand.
1809 </para>
1810
1811 <para>
1812 If no <filename>SRC_URI</filename> checksums are specified
1813 when you attempt to build the recipe, the build will produce
1814 an error for each missing checksum.
1815 As part of the error message, the build system provides
1816 the checksum string corresponding to the fetched file.
1817 Once you have the correct checksums, you can copy and paste
1818 them into your recipe and then run the build again to continue.
1819 <note>
1820 As mentioned, if the upstream source provides signatures
1821 for verifying the downloaded source code, you should
1822 verify those manually before setting the checksum values
1823 in the recipe and continuing with the build.
1824 </note>
1825 </para>
1826
1827 <para>
1828 This final example is a bit more complicated and is from the
1829 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb</filename>
1830 recipe.
1831 The example's <filename>SRC_URI</filename> statement identifies
1832 multiple files as the source files for the recipe: a tarball, a
1833 patch file, a desktop file, and an icon.
1834 <literallayout class='monospaced'>
1835 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1836 file://xwc.patch \
1837 file://rxvt.desktop \
1838 file://rxvt.png"
1839 </literallayout>
1840 </para>
1841
1842 <para>
1843 When you specify local files using the
1844 <filename>file://</filename> URI protocol, the build system
1845 fetches files from the local machine.
1846 The path is relative to the
1847 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1848 variable and searches specific directories in a certain order:
1849 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1850 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1851 and <filename>files</filename>.
1852 The directories are assumed to be subdirectories of the
1853 directory in which the recipe or append file resides.
1854 For another example that specifies these types of files, see the
1855 "<link linkend='new-recipe-single-c-file-package-hello-world'>Single .c File Package (Hello World!)</link>"
1856 section.
1857 </para>
1858
1859 <para>
1860 The previous example also specifies a patch file.
1861 Patch files are files whose names end in
1862 <filename>.patch</filename> or <filename>.diff</filename>.
1863 The build system automatically applies patches as described
1864 in the
1865 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1866 </para>
1867 </section>
1868
1869 <section id='new-recipe-unpacking-code'>
1870 <title>Unpacking Code</title>
1871
1872 <para>
1873 During the build, the
1874 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1875 task unpacks the source with
1876 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>
1877 pointing to where it is unpacked.
1878 </para>
1879
1880 <para>
1881 If you are fetching your source files from an upstream source
1882 archived tarball and the tarball's internal structure matches
1883 the common convention of a top-level subdirectory named
1884 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1885 then you do not need to set <filename>S</filename>.
1886 However, if <filename>SRC_URI</filename> specifies to fetch
1887 source from an archive that does not use this convention,
1888 or from an SCM like Git or Subversion, your recipe needs to
1889 define <filename>S</filename>.
1890 </para>
1891
1892 <para>
1893 If processing your recipe using BitBake successfully unpacks
1894 the source files, you need to be sure that the directory
1895 pointed to by <filename>${S}</filename> matches the structure
1896 of the source.
1897 </para>
1898 </section>
1899
1900 <section id='new-recipe-patching-code'>
1901 <title>Patching Code</title>
1902
1903 <para>
1904 Sometimes it is necessary to patch code after it has been
1905 fetched.
1906 Any files mentioned in <filename>SRC_URI</filename> whose
1907 names end in <filename>.patch</filename> or
1908 <filename>.diff</filename> are treated as patches.
1909 The
1910 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1911 task automatically applies these patches.
1912 </para>
1913
1914 <para>
1915 The build system should be able to apply patches with the "-p1"
1916 option (i.e. one directory level in the path will be stripped
1917 off).
1918 If your patch needs to have more directory levels stripped off,
1919 specify the number of levels using the "striplevel" option in
1920 the <filename>SRC_URI</filename> entry for the patch.
1921 Alternatively, if your patch needs to be applied in a specific
1922 subdirectory that is not specified in the patch file, use the
1923 "patchdir" option in the entry.
1924 </para>
1925
1926 <para>
1927 As with all local files referenced in
1928 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1929 using <filename>file://</filename>, you should place
1930 patch files in a directory next to the recipe either
1931 named the same as the base name of the recipe
1932 (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
1933 or "files".
1934 </para>
1935 </section>
1936
1937 <section id='new-recipe-licensing'>
1938 <title>Licensing</title>
1939
1940 <para>
1941 Your recipe needs to have both the
1942 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1943 and
1944 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1945 variables:
1946 <itemizedlist>
1947 <listitem><para><emphasis><filename>LICENSE</filename>:</emphasis>
1948 This variable specifies the license for the software.
1949 If you do not know the license under which the software
1950 you are building is distributed, you should go to the
1951 source code and look for that information.
1952 Typical files containing this information include
1953 <filename>COPYING</filename>,
1954 <filename>LICENSE</filename>, and
1955 <filename>README</filename> files.
1956 You could also find the information near the top of
1957 a source file.
1958 For example, given a piece of software licensed under
1959 the GNU General Public License version 2, you would
1960 set <filename>LICENSE</filename> as follows:
1961 <literallayout class='monospaced'>
1962 LICENSE = "GPLv2"
1963 </literallayout></para>
1964 <para>The licenses you specify within
1965 <filename>LICENSE</filename> can have any name as long
1966 as you do not use spaces, since spaces are used as
1967 separators between license names.
1968 For standard licenses, use the names of the files in
1969 <filename>meta/files/common-licenses/</filename>
1970 or the <filename>SPDXLICENSEMAP</filename> flag names
1971 defined in <filename>meta/conf/licenses.conf</filename>.
1972 </para></listitem>
1973 <listitem><para><emphasis><filename>LIC_FILES_CHKSUM</filename>:</emphasis>
1974 The OpenEmbedded build system uses this variable to
1975 make sure the license text has not changed.
1976 If it has, the build produces an error and it affords
1977 you the chance to figure it out and correct the problem.
1978 </para>
1979 <para>You need to specify all applicable licensing
1980 files for the software.
1981 At the end of the configuration step, the build process
1982 will compare the checksums of the files to be sure
1983 the text has not changed.
1984 Any differences result in an error with the message
1985 containing the current checksum.
1986 For more explanation and examples of how to set the
1987 <filename>LIC_FILES_CHKSUM</filename> variable, see the
1988 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
1989 section in the Yocto Project Reference Manual.</para>
1990 <para>To determine the correct checksum string, you
1991 can list the appropriate files in the
1992 <filename>LIC_FILES_CHKSUM</filename> variable with
1993 incorrect md5 strings, attempt to build the software,
1994 and then note the resulting error messages that will
1995 report the correct md5 strings.
1996 See the
1997 "<link linkend='new-recipe-fetching-code'>Fetching Code</link>"
1998 section for additional information.
1999 </para>
2000
2001 <para>
2002 Here is an example that assumes the software has a
2003 <filename>COPYING</filename> file:
2004 <literallayout class='monospaced'>
2005 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
2006 </literallayout>
2007 When you try to build the software, the build system
2008 will produce an error and give you the correct string
2009 that you can substitute into the recipe file for a
2010 subsequent build.
2011 </para></listitem>
2012 </itemizedlist>
2013 </para>
2014
2015<!--
2016
2017 <para>
2018 For trying this out I created a new recipe named
2019 <filename>htop_1.0.2.bb</filename> and put it in
2020 <filename>poky/meta/recipes-extended/htop</filename>.
2021 There are two license type statements in my very simple
2022 recipe:
2023 <literallayout class='monospaced'>
2024 LICENSE = ""
2025
2026 LIC_FILES_CHKSUM = ""
2027
2028 SRC_URI[md5sum] = ""
2029 SRC_URI[sha256sum] = ""
2030 </literallayout>
2031 Evidently, you need to run a <filename>bitbake -c cleanall htop</filename>.
2032 Next, you delete or comment out the two <filename>SRC_URI</filename>
2033 lines at the end and then attempt to build the software with
2034 <filename>bitbake htop</filename>.
2035 Doing so causes BitBake to report some errors and and give
2036 you the actual strings you need for the last two
2037 <filename>SRC_URI</filename> lines.
2038 Prior to this, you have to dig around in the home page of the
2039 source for <filename>htop</filename> and determine that the
2040 software is released under GPLv2.
2041 You can provide that in the <filename>LICENSE</filename>
2042 statement.
2043 Now you edit your recipe to have those two strings for
2044 the <filename>SRC_URI</filename> statements:
2045 <literallayout class='monospaced'>
2046 LICENSE = "GPLv2"
2047
2048 LIC_FILES_CHKSUM = ""
2049
2050 SRC_URI = "${SOURCEFORGE_MIRROR}/htop/htop-${PV}.tar.gz"
2051 SRC_URI[md5sum] = "0d01cca8df3349c74569cefebbd9919e"
2052 SRC_URI[sha256sum] = "ee60657b044ece0df096c053060df7abf3cce3a568ab34d260049e6a37ccd8a1"
2053 </literallayout>
2054 At this point, you can build the software again using the
2055 <filename>bitbake htop</filename> command.
2056 There is just a set of errors now associated with the
2057 empty <filename>LIC_FILES_CHKSUM</filename> variable now.
2058 </para>
2059-->
2060
2061 </section>
2062
2063 <section id='new-recipe-configuring-the-recipe'>
2064 <title>Configuring the Recipe</title>
2065
2066 <para>
2067 Most software provides some means of setting build-time
2068 configuration options before compilation.
2069 Typically, setting these options is accomplished by running a
2070 configure script with some options, or by modifying a build
2071 configuration file.
2072 </para>
2073
2074 <para>
2075 A major part of build-time configuration is about checking for
2076 build-time dependencies and possibly enabling optional
2077 functionality as a result.
2078 You need to specify any build-time dependencies for the
2079 software you are building in your recipe's
2080 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2081 value, in terms of other recipes that satisfy those
2082 dependencies.
2083 You can often find build-time or runtime
2084 dependencies described in the software's documentation.
2085 </para>
2086
2087 <para>
2088 The following list provides configuration items of note based
2089 on how your software is built:
2090 <itemizedlist>
2091 <listitem><para><emphasis>Autotools:</emphasis>
2092 If your source files have a
2093 <filename>configure.ac</filename> file, then your
2094 software is built using Autotools.
2095 If this is the case, you just need to worry about
2096 modifying the configuration.</para>
2097 <para>When using Autotools, your recipe needs to inherit
2098 the
2099 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2100 class and your recipe does not have to contain a
2101 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2102 task.
2103 However, you might still want to make some adjustments.
2104 For example, you can set
2105 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
2106 to pass any needed configure options that are specific
2107 to the recipe.</para></listitem>
2108 <listitem><para><emphasis>CMake:</emphasis>
2109 If your source files have a
2110 <filename>CMakeLists.txt</filename> file, then your
2111 software is built using CMake.
2112 If this is the case, you just need to worry about
2113 modifying the configuration.</para>
2114 <para>When you use CMake, your recipe needs to inherit
2115 the
2116 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2117 class and your recipe does not have to contain a
2118 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2119 task.
2120 You can make some adjustments by setting
2121 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
2122 to pass any needed configure options that are specific
2123 to the recipe.</para></listitem>
2124 <listitem><para><emphasis>Other:</emphasis>
2125 If your source files do not have a
2126 <filename>configure.ac</filename> or
2127 <filename>CMakeLists.txt</filename> file, then your
2128 software is built using some method other than Autotools
2129 or CMake.
2130 If this is the case, you normally need to provide a
2131 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2132 task in your recipe
2133 unless, of course, there is nothing to configure.
2134 </para>
2135 <para>Even if your software is not being built by
2136 Autotools or CMake, you still might not need to deal
2137 with any configuration issues.
2138 You need to determine if configuration is even a required step.
2139 You might need to modify a Makefile or some configuration file
2140 used for the build to specify necessary build options.
2141 Or, perhaps you might need to run a provided, custom
2142 configure script with the appropriate options.</para>
2143 <para>For the case involving a custom configure
2144 script, you would run
2145 <filename>./configure &dash;&dash;help</filename> and look for
2146 the options you need to set.</para></listitem>
2147 </itemizedlist>
2148 </para>
2149
2150 <para>
2151 Once configuration succeeds, it is always good practice to
2152 look at the <filename>log.do_configure</filename> file to
2153 ensure that the appropriate options have been enabled and no
2154 additional build-time dependencies need to be added to
2155 <filename>DEPENDS</filename>.
2156 For example, if the configure script reports that it found
2157 something not mentioned in <filename>DEPENDS</filename>, or
2158 that it did not find something that it needed for some
2159 desired optional functionality, then you would need to add
2160 those to <filename>DEPENDS</filename>.
2161 Looking at the log might also reveal items being checked for,
2162 enabled, or both that you do not want, or items not being found
2163 that are in <filename>DEPENDS</filename>, in which case
2164 you would need to look at passing extra options to the
2165 configure script as needed.
2166 For reference information on configure options specific to the
2167 software you are building, you can consult the output of the
2168 <filename>./configure &dash;&dash;help</filename> command within
2169 <filename>${S}</filename> or consult the software's upstream
2170 documentation.
2171 </para>
2172 </section>
2173
2174 <section id='new-recipe-compilation'>
2175 <title>Compilation</title>
2176
2177 <para>
2178 During a build, the <filename>do_compile</filename> task
2179 happens after source is fetched, unpacked, and configured.
2180 If the recipe passes through <filename>do_compile</filename>
2181 successfully, nothing needs to be done.
2182 </para>
2183
2184 <para>
2185 However, if the compile step fails, you need to diagnose the
2186 failure.
2187 Here are some common issues that cause failures:
2188 <itemizedlist>
2189 <listitem><para><emphasis>Parallel build failures:</emphasis>
2190 These failures manifest themselves as intermittent
2191 errors, or errors reporting that a file or directory
2192 that should be created by some other part of the build
2193 process could not be found.
2194 This type of failure can occur even if, upon inspection,
2195 the file or directory does exist after the build has
2196 failed, because that part of the build process happened
2197 in the wrong order.</para>
2198 <para>To fix the problem, you need to either satisfy
2199 the missing dependency in the Makefile or whatever
2200 script produced the Makefile, or (as a workaround)
2201 set
2202 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
2203 to an empty string:
2204 <literallayout class='monospaced'>
2205 PARALLEL_MAKE = ""
2206 </literallayout></para>
2207 <para>
2208 For information on parallel Makefile issues, see the
2209 "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
2210 section.
2211 </para></listitem>
2212 <listitem><para><emphasis>Improper host path usage:</emphasis>
2213 This failure applies to recipes building for the target
2214 or <filename>nativesdk</filename> only.
2215 The failure occurs when the compilation process uses
2216 improper headers, libraries, or other files from the
2217 host system when cross-compiling for the target.
2218 </para>
2219 <para>To fix the problem, examine the
2220 <filename>log.do_compile</filename> file to identify
2221 the host paths being used (e.g.
2222 <filename>/usr/include</filename>,
2223 <filename>/usr/lib</filename>, and so forth) and then
2224 either add configure options, apply a patch, or do both.
2225 </para></listitem>
2226 <listitem><para><emphasis>Failure to find required
2227 libraries/headers:</emphasis>
2228 If a build-time dependency is missing because it has
2229 not been declared in
2230 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
2231 or because the dependency exists but the path used by
2232 the build process to find the file is incorrect and the
2233 configure step did not detect it, the compilation
2234 process could fail.
2235 For either of these failures, the compilation process
2236 notes that files could not be found.
2237 In these cases, you need to go back and add additional
2238 options to the configure script as well as possibly
2239 add additional build-time dependencies to
2240 <filename>DEPENDS</filename>.</para>
2241 <para>Occasionally, it is necessary to apply a patch
2242 to the source to ensure the correct paths are used.
2243 If you need to specify paths to find files staged
2244 into the sysroot from other recipes, use the variables
2245 that the OpenEmbedded build system provides
2246 (e.g.
2247 <filename>STAGING_BINDIR</filename>,
2248 <filename>STAGING_INCDIR</filename>,
2249 <filename>STAGING_DATADIR</filename>, and so forth).
2250<!--
2251 (e.g.
2252 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
2253 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
2254 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
2255 and so forth).
2256-->
2257 </para></listitem>
2258 </itemizedlist>
2259 </para>
2260 </section>
2261
2262 <section id='new-recipe-installing'>
2263 <title>Installing</title>
2264
2265 <para>
2266 During <filename>do_install</filename>, the task copies the
2267 built files along with their hierarchy to locations that
2268 would mirror their locations on the target device.
2269 The installation process copies files from the
2270 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
2271 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>,
2272 and
2273 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
2274 directories to the
2275 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
2276 directory to create the structure as it should appear on the
2277 target system.
2278 </para>
2279
2280 <para>
2281 How your software is built affects what you must do to be
2282 sure your software is installed correctly.
2283 The following list describes what you must do for installation
2284 depending on the type of build system used by the software
2285 being built:
2286 <itemizedlist>
2287 <listitem><para><emphasis>Autotools and CMake:</emphasis>
2288 If the software your recipe is building uses Autotools
2289 or CMake, the OpenEmbedded build
2290 system understands how to install the software.
2291 Consequently, you do not have to have a
2292 <filename>do_install</filename> task as part of your
2293 recipe.
2294 You just need to make sure the install portion of the
2295 build completes with no issues.
2296 However, if you wish to install additional files not
2297 already being installed by
2298 <filename>make install</filename>, you should do this
2299 using a <filename>do_install_append</filename> function
2300 using the install command as described in
2301 the "Manual" bulleted item later in this list.
2302 </para></listitem>
2303 <listitem><para><emphasis>Other (using
2304 <filename>make install</filename>):</emphasis>
2305 You need to define a
2306 <filename>do_install</filename> function in your
2307 recipe.
2308 The function should call
2309 <filename>oe_runmake install</filename> and will likely
2310 need to pass in the destination directory as well.
2311 How you pass that path is dependent on how the
2312 <filename>Makefile</filename> being run is written
2313 (e.g. <filename>DESTDIR=${D}</filename>,
2314 <filename>PREFIX=${D}</filename>,
2315 <filename>INSTALLROOT=${D}</filename>, and so forth).
2316 </para>
2317 <para>For an example recipe using
2318 <filename>make install</filename>, see the
2319 "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>"
2320 section.</para></listitem>
2321 <listitem><para><emphasis>Manual:</emphasis>
2322 You need to define a
2323 <filename>do_install</filename> function in your
2324 recipe.
2325 The function must first use
2326 <filename>install -d</filename> to create the
2327 directories under
2328 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
2329 Once the directories exist, your function can use
2330 <filename>install</filename> to manually install the
2331 built software into the directories.</para>
2332 <para>You can find more information on
2333 <filename>install</filename> at
2334 <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>.
2335 </para></listitem>
2336 </itemizedlist>
2337 </para>
2338
2339 <para>
2340 For the scenarios that do not use Autotools or
2341 CMake, you need to track the installation
2342 and diagnose and fix any issues until everything installs
2343 correctly.
2344 You need to look in the default location of
2345 <filename>${D}</filename>, which is
2346 <filename>${WORKDIR}/image</filename>, to be sure your
2347 files have been installed correctly.
2348 </para>
2349
2350 <note><title>Notes</title>
2351 <itemizedlist>
2352 <listitem><para>
2353 During the installation process, you might need to
2354 modify some of the installed files to suit the target
2355 layout.
2356 For example, you might need to replace hard-coded paths
2357 in an initscript with values of variables provided by
2358 the build system, such as replacing
2359 <filename>/usr/bin/</filename> with
2360 <filename>${bindir}</filename>.
2361 If you do perform such modifications during
2362 <filename>do_install</filename>, be sure to modify the
2363 destination file after copying rather than before
2364 copying.
2365 Modifying after copying ensures that the build system
2366 can re-execute <filename>do_install</filename> if
2367 needed.
2368 </para></listitem>
2369 <listitem><para>
2370 <filename>oe_runmake install</filename>, which can be
2371 run directly or can be run indirectly by the
2372 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2373 and
2374 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink>
2375 classes, runs <filename>make install</filename> in
2376 parallel.
2377 Sometimes, a Makefile can have missing dependencies
2378 between targets that can result in race conditions.
2379 If you experience intermittent failures during
2380 <filename>do_install</filename>, you might be able to
2381 work around them by disabling parallel Makefile
2382 installs by adding the following to the recipe:
2383 <literallayout class='monospaced'>
2384 PARALLEL_MAKEINST = ""
2385 </literallayout>
2386 See
2387 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
2388 for additional information.
2389 </para></listitem>
2390 </itemizedlist>
2391 </note>
2392 </section>
2393
2394 <section id='new-recipe-enabling-system-services'>
2395 <title>Enabling System Services</title>
2396
2397 <para>
2398 If you want to install a service, which is a process that
2399 usually starts on boot and runs in the background, then
2400 you must include some additional definitions in your recipe.
2401 </para>
2402
2403 <para>
2404 If you are adding services and the service initialization
2405 script or the service file itself is not installed, you must
2406 provide for that installation in your recipe using a
2407 <filename>do_install_append</filename> function.
2408 If your recipe already has a <filename>do_install</filename>
2409 function, update the function near its end rather than
2410 adding an additional <filename>do_install_append</filename>
2411 function.
2412 </para>
2413
2414 <para>
2415 When you create the installation for your services, you need
2416 to accomplish what is normally done by
2417 <filename>make install</filename>.
2418 In other words, make sure your installation arranges the output
2419 similar to how it is arranged on the target system.
2420 </para>
2421
2422 <para>
2423 The OpenEmbedded build system provides support for starting
2424 services two different ways:
2425 <itemizedlist>
2426 <listitem><para><emphasis>SysVinit:</emphasis>
2427 SysVinit is a system and service manager that
2428 manages the init system used to control the very basic
2429 functions of your system.
2430 The init program is the first program
2431 started by the Linux kernel when the system boots.
2432 Init then controls the startup, running and shutdown
2433 of all other programs.</para>
2434 <para>To enable a service using SysVinit, your recipe
2435 needs to inherit the
2436 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink>
2437 class.
2438 The class helps facilitate safely installing the
2439 package on the target.</para>
2440 <para>You will need to set the
2441 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>,
2442 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>,
2443 and
2444 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink>
2445 variables within your recipe.</para></listitem>
2446 <listitem><para><emphasis>systemd:</emphasis>
2447 System Management Daemon (systemd) was designed to
2448 replace SysVinit and to provide
2449 enhanced management of services.
2450 For more information on systemd, see the systemd
2451 homepage at
2452 <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>.
2453 </para>
2454 <para>To enable a service using systemd, your recipe
2455 needs to inherit the
2456 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink>
2457 class.
2458 See the <filename>systemd.bbclass</filename> file
2459 located in your
2460 <link linkend='source-directory'>Source Directory</link>.
2461 section for more information.
2462 </para></listitem>
2463 </itemizedlist>
2464 </para>
2465 </section>
2466
2467 <section id='new-recipe-packaging'>
2468 <title>Packaging</title>
2469
2470 <para>
2471 Successful packaging is a combination of automated processes
2472 performed by the OpenEmbedded build system and some
2473 specific steps you need to take.
2474 The following list describes the process:
2475 <itemizedlist>
2476 <listitem><para><emphasis>Splitting Files</emphasis>:
2477 The <filename>do_package</filename> task splits the
2478 files produced by the recipe into logical components.
2479 Even software that produces a single binary might
2480 still have debug symbols, documentation, and other
2481 logical components that should be split out.
2482 The <filename>do_package</filename> task ensures
2483 that files are split up and packaged correctly.
2484 </para></listitem>
2485 <listitem><para><emphasis>Running QA Checks</emphasis>:
2486 The
2487 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2488 class adds a step to
2489 the package generation process so that output quality
2490 assurance checks are generated by the OpenEmbedded
2491 build system.
2492 This step performs a range of checks to be sure the
2493 build's output is free of common problems that show
2494 up during runtime.
2495 For information on these checks, see the
2496 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
2497 class and the
2498 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
2499 chapter in the Yocto Project Reference Manual.
2500 </para></listitem>
2501 <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
2502 After you build your software, you need to be sure
2503 your packages are correct.
2504 Examine the
2505 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
2506 directory and make sure files are where you expect
2507 them to be.
2508 If you discover problems, you can set
2509 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
2510 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2511 <filename>do_install(_append)</filename>, and so forth as
2512 needed.
2513 </para></listitem>
2514 <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
2515 If you need to split an application into several
2516 packages, see the
2517 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2518 section for an example.
2519 </para></listitem>
2520 <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
2521 For an example showing how to install a
2522 post-installation script, see the
2523 "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
2524 section.
2525 </para></listitem>
2526 <listitem><para><emphasis>Marking Package Architecture</emphasis>:
2527 Depending on what your recipe is building and how it
2528 is configured, it might be important to mark the
2529 packages produced as being specific to a particular
2530 machine, or to mark them as not being specific to
2531 a particular machine or architecture at all.
2532 By default, packages produced for the target are
2533 marked as being specific to the architecture of the
2534 target machine because that is usually the desired
2535 result.
2536 However, if the recipe configures the software to be
2537 built specific to the target machine (e.g. the
2538 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
2539 value is passed into the configure script or a patch
2540 is applied only for a particular machine), then you
2541 should mark the packages produced as being
2542 machine-specific by adding the following to the
2543 recipe:
2544 <literallayout class='monospaced'>
2545 PACKAGE_ARCH = "${MACHINE_ARCH}"
2546 </literallayout>
2547 On the other hand, if the recipe produces packages
2548 that do not contain anything specific to the target
2549 machine or architecture at all (e.g. recipes
2550 that simply package script files or configuration
2551 files), you should use the
2552 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
2553 class to do this for you by adding this to your
2554 recipe:
2555 <literallayout class='monospaced'>
2556 inherit allarch
2557 </literallayout>
2558 Ensuring that the package architecture is correct is
2559 not critical while you are doing the first few builds
2560 of your recipe.
2561 However, it is important in order
2562 to ensure that your recipe rebuilds (or does not
2563 rebuild) appropriately in response to changes in
2564 configuration, and to ensure that you get the
2565 appropriate packages installed on the target machine,
2566 particularly if you run separate builds for more
2567 than one target machine.
2568 </para></listitem>
2569 </itemizedlist>
2570 </para>
2571 </section>
2572
2573 <section id='properly-versioning-pre-release-recipes'>
2574 <title>Properly Versioning Pre-Release Recipes</title>
2575
2576 <para>
2577 Sometimes the name of a recipe can lead to versioning
2578 problems when the recipe is upgraded to a final release.
2579 For example, consider the
2580 <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
2581 the list of example recipes in the
2582 "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
2583 section.
2584 This recipe is at a release candidate stage (i.e.
2585 "rc1").
2586 When the recipe is released, the recipe filename becomes
2587 <filename>irssi_0.8.16.bb</filename>.
2588 The version change from <filename>0.8.16-rc1</filename>
2589 to <filename>0.8.16</filename> is seen as a decrease by the
2590 build system and package managers, so the resulting packages
2591 will not correctly trigger an upgrade.
2592 </para>
2593
2594 <para>
2595 In order to ensure the versions compare properly, the
2596 recommended convention is to set
2597 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
2598 within the recipe to
2599 "<replaceable>previous_version</replaceable>+<replaceable>current_version</replaceable>".
2600 You can use an additional variable so that you can use the
2601 current version elsewhere.
2602 Here is an example:
2603 <literallayout class='monospaced'>
2604 REALPV = "0.8.16-rc1"
2605 PV = "0.8.15+${REALPV}"
2606 </literallayout>
2607 </para>
2608 </section>
2609
2610 <section id='new-recipe-post-installation-scripts'>
2611 <title>Post-Installation Scripts</title>
2612
2613 <para>
2614 Post-installation scripts run immediately after installing
2615 a package on the target or during image creation when a
2616 package is included in an image.
2617 To add a post-installation script to a package, add a
2618 <filename>pkg_postinst_PACKAGENAME()</filename> function to
2619 the recipe file (<filename>.bb</filename>) and replace
2620 <filename>PACKAGENAME</filename> with the name of the package
2621 you want to attach to the <filename>postinst</filename>
2622 script.
2623 To apply the post-installation script to the main package
2624 for the recipe, which is usually what is required, specify
2625 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2626 in place of <filename>PACKAGENAME</filename>.
2627 </para>
2628
2629 <para>
2630 A post-installation function has the following structure:
2631 <literallayout class='monospaced'>
2632 pkg_postinst_PACKAGENAME() {
2633 #!/bin/sh -e
2634 # Commands to carry out
2635 }
2636 </literallayout>
2637 </para>
2638
2639 <para>
2640 The script defined in the post-installation function is
2641 called when the root filesystem is created.
2642 If the script succeeds, the package is marked as installed.
2643 If the script fails, the package is marked as unpacked and
2644 the script is executed when the image boots again.
2645 </para>
2646
2647 <para>
2648 Sometimes it is necessary for the execution of a
2649 post-installation script to be delayed until the first boot.
2650 For example, the script might need to be executed on the
2651 device itself.
2652 To delay script execution until boot time, use the following
2653 structure in the post-installation script:
2654 <literallayout class='monospaced'>
2655 pkg_postinst_PACKAGENAME() {
2656 #!/bin/sh -e
2657 if [ x"$D" = "x" ]; then
2658 # Actions to carry out on the device go here
2659 else
2660 exit 1
2661 fi
2662 }
2663 </literallayout>
2664 </para>
2665
2666 <para>
2667 The previous example delays execution until the image boots
2668 again because the environment variable <filename>D</filename>
2669 points to the directory containing the image when
2670 the root filesystem is created at build time but is unset
2671 when executed on the first boot.
2672 </para>
2673
2674 <note>
2675 Equivalent support for pre-install, pre-uninstall, and
2676 post-uninstall scripts exist by way of
2677 <filename>pkg_preinst</filename>,
2678 <filename>pkg_prerm</filename>, and
2679 <filename>pkg_postrm</filename>, respectively.
2680 These scrips work in exactly the same way as does
2681 <filename>pkg_postinst</filename> with the exception that they
2682 run at different times.
2683 Also, because of when they run, they are not applicable to
2684 being run at image creation time like
2685 <filename>pkg_postinst</filename>.
2686 </note>
2687 </section>
2688
2689 <section id='new-recipe-testing'>
2690 <title>Testing</title>
2691
2692 <para>
2693 The final step for completing your recipe is to be sure that
2694 the software you built runs correctly.
2695 To accomplish runtime testing, add the build's output
2696 packages to your image and test them on the target.
2697 </para>
2698
2699 <para>
2700 For information on how to customize your image by adding
2701 specific packages, see the
2702 "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>"
2703 section.
2704 </para>
2705 </section>
2706
2707 <section id='new-recipe-testing-examples'>
2708 <title>Examples</title>
2709
2710 <para>
2711 To help summarize how to write a recipe, this section provides
2712 some examples given various scenarios:
2713 <itemizedlist>
2714 <listitem><para>Recipes that use local files</para></listitem>
2715 <listitem><para>Using an Autotooled package</para></listitem>
2716 <listitem><para>Using a Makefile-based package</para></listitem>
2717 <listitem><para>Splitting an application into multiple packages</para></listitem>
2718 <listitem><para>Adding binaries to an image</para></listitem>
2719 </itemizedlist>
2720 </para>
2721
2722 <section id='new-recipe-single-c-file-package-hello-world'>
2723 <title>Single .c File Package (Hello World!)</title>
2724
2725 <para>
2726 Building an application from a single file that is stored
2727 locally (e.g. under <filename>files</filename>) requires
2728 a recipe that has the file listed in the
2729 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
2730 variable.
2731 Additionally, you need to manually write the
2732 <filename>do_compile</filename> and
2733 <filename>do_install</filename> tasks.
2734 The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
2735 variable defines the directory containing the source code,
2736 which is set to
2737 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
2738 in this case - the directory BitBake uses for the build.
2739 <literallayout class='monospaced'>
2740 SUMMARY = "Simple helloworld application"
2741 SECTION = "examples"
2742 LICENSE = "MIT"
2743 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2744
2745 SRC_URI = "file://helloworld.c"
2746
2747 S = "${WORKDIR}"
2748
2749 do_compile() {
2750 ${CC} helloworld.c -o helloworld
2751 }
2752
2753 do_install() {
2754 install -d ${D}${bindir}
2755 install -m 0755 helloworld ${D}${bindir}
2756 }
2757 </literallayout>
2758 </para>
2759
2760 <para>
2761 By default, the <filename>helloworld</filename>,
2762 <filename>helloworld-dbg</filename>, and
2763 <filename>helloworld-dev</filename> packages are built.
2764 For information on how to customize the packaging process,
2765 see the
2766 "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
2767 section.
2768 </para>
2769 </section>
2770
2771 <section id='new-recipe-autotooled-package'>
2772 <title>Autotooled Package</title>
2773 <para>
2774 Applications that use Autotools such as <filename>autoconf</filename> and
2775 <filename>automake</filename> require a recipe that has a source archive listed in
2776 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
2777 also inherit the
2778 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2779 class, which contains the definitions of all the steps
2780 needed to build an Autotool-based application.
2781 The result of the build is automatically packaged.
2782 And, if the application uses NLS for localization, packages with local information are
2783 generated (one package per language).
2784 Following is one example: (<filename>hello_2.3.bb</filename>)
2785 <literallayout class='monospaced'>
2786 SUMMARY = "GNU Helloworld application"
2787 SECTION = "examples"
2788 LICENSE = "GPLv2+"
2789 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2790
2791 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2792
2793 inherit autotools gettext
2794 </literallayout>
2795 </para>
2796
2797 <para>
2798 The variable
2799 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
2800 is used to track source license changes as described in the
2801 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
2802 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2803 </para>
2804 </section>
2805
2806 <section id='new-recipe-makefile-based-package'>
2807 <title>Makefile-Based Package</title>
2808
2809 <para>
2810 Applications that use GNU <filename>make</filename> also require a recipe that has
2811 the source archive listed in
2812 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
2813 You do not need to add a <filename>do_compile</filename> step since by default BitBake
2814 starts the <filename>make</filename> command to compile the application.
2815 If you need additional <filename>make</filename> options, you should store them in the
2816 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
2817 variable.
2818 BitBake passes these options into the GNU <filename>make</filename> invocation.
2819 Note that a <filename>do_install</filename> task is still required.
2820 Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
2821 </para>
2822
2823 <para>
2824 Some applications might require extra parameters to be passed to the compiler.
2825 For example, the application might need an additional header path.
2826 You can accomplish this by adding to the
2827 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
2828 The following example shows this:
2829 <literallayout class='monospaced'>
2830 CFLAGS_prepend = "-I ${S}/include "
2831 </literallayout>
2832 </para>
2833
2834 <para>
2835 In the following example, <filename>mtd-utils</filename> is a makefile-based package:
2836 <literallayout class='monospaced'>
2837 SUMMARY = "Tools for managing memory technology devices"
2838 SECTION = "base"
2839 DEPENDS = "zlib lzo e2fsprogs util-linux"
2840 HOMEPAGE = "http://www.linux-mtd.infradead.org/"
2841 LICENSE = "GPLv2+"
2842 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2843 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2844
2845 # Use the latest version at 26 Oct, 2013
2846 SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b"
2847 SRC_URI = "git://git.infradead.org/mtd-utils.git \
2848 file://add-exclusion-to-mkfs-jffs2-git-2.patch \
2849 "
2850
2851 PV = "1.5.1+git${SRCPV}"
2852
2853 S = "${WORKDIR}/git/"
2854
2855 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2856
2857 do_install () {
2858 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir}
2859 }
2860
2861 PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc"
2862
2863 FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool"
2864 FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*"
2865 FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image"
2866
2867 PARALLEL_MAKE = ""
2868
2869 BBCLASSEXTEND = "native"
2870 </literallayout>
2871 </para>
2872 </section>
2873
2874 <section id='splitting-an-application-into-multiple-packages'>
2875 <title>Splitting an Application into Multiple Packages</title>
2876
2877 <para>
2878 You can use the variables
2879 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
2880 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
2881 to split an application into multiple packages.
2882 </para>
2883
2884 <para>
2885 Following is an example that uses the <filename>libxpm</filename> recipe.
2886 By default, this recipe generates a single package that contains the library along
2887 with a few binaries.
2888 You can modify the recipe to split the binaries into separate packages:
2889 <literallayout class='monospaced'>
2890 require xorg-lib-common.inc
2891
2892 SUMMARY = "X11 Pixmap library"
2893 LICENSE = "X-BSD"
2894 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2895 DEPENDS += "libxext libsm libxt"
2896 PR = "r3"
2897 PE = "1"
2898
2899 XORG_PN = "libXpm"
2900
2901 PACKAGES =+ "sxpm cxpm"
2902 FILES_cxpm = "${bindir}/cxpm"
2903 FILES_sxpm = "${bindir}/sxpm"
2904 </literallayout>
2905 </para>
2906
2907 <para>
2908 In the previous example, we want to ship the <filename>sxpm</filename>
2909 and <filename>cxpm</filename> binaries in separate packages.
2910 Since <filename>bindir</filename> would be packaged into the main
2911 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
2912 package by default, we prepend the <filename>PACKAGES</filename>
2913 variable so additional package names are added to the start of list.
2914 This results in the extra <filename>FILES_*</filename>
2915 variables then containing information that define which files and
2916 directories go into which packages.
2917 Files included by earlier packages are skipped by latter packages.
2918 Thus, the main <filename>PN</filename> package
2919 does not include the above listed files.
2920 </para>
2921 </section>
2922
2923 <section id='packaging-externally-produced-binaries'>
2924 <title>Packaging Externally Produced Binaries</title>
2925
2926 <para>
2927 Sometimes, you need to add pre-compiled binaries to an
2928 image.
2929 For example, suppose that binaries for proprietary code
2930 exist, which are created by a particular division of a
2931 company.
2932 Your part of the company needs to use those binaries as
2933 part of an image that you are building using the
2934 OpenEmbedded build system.
2935 Since you only have the binaries and not the source code,
2936 you cannot use a typical recipe that expects to fetch the
2937 source specified in
2938 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2939 and then compile it.
2940 </para>
2941
2942 <para>
2943 One method is to package the binaries and then install them
2944 as part of the image.
2945 Generally, it is not a good idea to package binaries
2946 since, among other things, it can hinder the ability to
2947 reproduce builds and could lead to compatibility problems
2948 with ABI in the future.
2949 However, sometimes you have no choice.
2950 </para>
2951
2952 <para>
2953 The easiest solution is to create a recipe that uses
2954 the
2955 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-bin-package'><filename>bin_package</filename></ulink>
2956 class and to be sure that you are using default locations
2957 for build artifacts.
2958 In most cases, the <filename>bin_package</filename> class
2959 handles "skipping" the configure and compile steps as well
2960 as sets things up to grab packages from the appropriate
2961 area.
2962 In particular, this class sets <filename>noexec</filename>
2963 on both the
2964 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2965 and
2966 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2967 tasks, sets
2968 <filename>FILES_${PN}</filename> to "/" so that it picks
2969 up all files, and sets up a
2970 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
2971 task, which effectively copies all files from
2972 <filename>${S}</filename> to <filename>${D}</filename>.
2973 The <filename>bin_package</filename> class works well when
2974 the files extracted into <filename>${S}</filename> are
2975 already laid out in the way they should be laid out
2976 on the target.
2977 For more information on these variables, see the
2978 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
2979 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
2980 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>,
2981 and
2982 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
2983 variables in the Yocto Project Reference Manual's variable
2984 glossary.
2985 </para>
2986
2987 <para>
2988 If you can't use the <filename>bin_package</filename>
2989 class, you need to be sure you are doing the following:
2990 <itemizedlist>
2991 <listitem><para>Create a recipe where the
2992 <filename>do_configure</filename> and
2993 <filename>do_compile</filename> tasks do nothing:
2994 <literallayout class='monospaced'>
2995 do_configure[noexec] = "1"
2996 do_compile[noexec] = "1"
2997 </literallayout>
2998 Alternatively, you can make these tasks an empty
2999 function.
3000 </para></listitem>
3001 <listitem><para>Make sure your
3002 <filename>do_install</filename> task installs the
3003 binaries appropriately.
3004 </para></listitem>
3005 <listitem><para>Ensure that you set up
3006 <filename>FILES</filename> (usually
3007 <filename>FILES_${PN}</filename>) to point to the
3008 files you have installed, which of course depends
3009 on where you have installed them and whether
3010 those files are in different locations than the
3011 defaults.
3012 </para></listitem>
3013 </itemizedlist>
3014 </para>
3015 </section>
3016 </section>
3017 </section>
3018
3019 <section id="platdev-newmachine">
3020 <title>Adding a New Machine</title>
3021
3022 <para>
3023 Adding a new machine to the Yocto Project is a straightforward
3024 process.
3025 This section describes how to add machines that are similar
3026 to those that the Yocto Project already supports.
3027 <note>
3028 Although well within the capabilities of the Yocto Project,
3029 adding a totally new architecture might require
3030 changes to <filename>gcc/glibc</filename> and to the site
3031 information, which is beyond the scope of this manual.
3032 </note>
3033 </para>
3034
3035 <para>
3036 For a complete example that shows how to add a new machine,
3037 see the
3038 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
3039 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
3040 </para>
3041
3042 <section id="platdev-newmachine-conffile">
3043 <title>Adding the Machine Configuration File</title>
3044
3045 <para>
3046 To add a new machine, you need to add a new machine
3047 configuration file to the layer's
3048 <filename>conf/machine</filename> directory.
3049 This configuration file provides details about the device
3050 you are adding.
3051 </para>
3052
3053 <para>
3054 The OpenEmbedded build system uses the root name of the
3055 machine configuration file to reference the new machine.
3056 For example, given a machine configuration file named
3057 <filename>crownbay.conf</filename>, the build system
3058 recognizes the machine as "crownbay".
3059 </para>
3060
3061 <para>
3062 The most important variables you must set in your machine
3063 configuration file or include from a lower-level configuration
3064 file are as follows:
3065 <itemizedlist>
3066 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
3067 (e.g. "arm")</para></listitem>
3068 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
3069 </para></listitem>
3070 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
3071 (e.g. "apm screen wifi")</para></listitem>
3072 </itemizedlist>
3073 </para>
3074
3075 <para>
3076 You might also need these variables:
3077 <itemizedlist>
3078 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
3079 (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem>
3080 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
3081 (e.g. "zImage")</para></listitem>
3082 <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
3083 (e.g. "tar.gz jffs2")</para></listitem>
3084 </itemizedlist>
3085 </para>
3086
3087 <para>
3088 You can find full details on these variables in the reference
3089 section.
3090 You can leverage existing machine <filename>.conf</filename>
3091 files from <filename>meta-yocto-bsp/conf/machine/</filename>.
3092 </para>
3093 </section>
3094
3095 <section id="platdev-newmachine-kernel">
3096 <title>Adding a Kernel for the Machine</title>
3097
3098 <para>
3099 The OpenEmbedded build system needs to be able to build a kernel
3100 for the machine.
3101 You need to either create a new kernel recipe for this machine,
3102 or extend an existing kernel recipe.
3103 You can find several kernel recipe examples in the
3104 Source Directory at
3105 <filename>meta/recipes-kernel/linux</filename>
3106 that you can use as references.
3107 </para>
3108
3109 <para>
3110 If you are creating a new kernel recipe, normal recipe-writing
3111 rules apply for setting up a
3112 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
3113 Thus, you need to specify any necessary patches and set
3114 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
3115 to point at the source code.
3116 You need to create a <filename>do_configure</filename> task that
3117 configures the unpacked kernel with a
3118 <filename>defconfig</filename> file.
3119 You can do this by using a <filename>make defconfig</filename>
3120 command or, more commonly, by copying in a suitable
3121 <filename>defconfig</filename> file and then running
3122 <filename>make oldconfig</filename>.
3123 By making use of <filename>inherit kernel</filename> and
3124 potentially some of the <filename>linux-*.inc</filename> files,
3125 most other functionality is centralized and the defaults of the
3126 class normally work well.
3127 </para>
3128
3129 <para>
3130 If you are extending an existing kernel recipe, it is usually
3131 a matter of adding a suitable <filename>defconfig</filename>
3132 file.
3133 The file needs to be added into a location similar to
3134 <filename>defconfig</filename> files used for other machines
3135 in a given kernel recipe.
3136 A possible way to do this is by listing the file in the
3137 <filename>SRC_URI</filename> and adding the machine to the
3138 expression in
3139 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
3140 <literallayout class='monospaced'>
3141 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
3142 </literallayout>
3143 </para>
3144 </section>
3145
3146 <section id="platdev-newmachine-formfactor">
3147 <title>Adding a Formfactor Configuration File</title>
3148
3149 <para>
3150 A formfactor configuration file provides information about the
3151 target hardware for which the image is being built and information that
3152 the build system cannot obtain from other sources such as the kernel.
3153 Some examples of information contained in a formfactor configuration file include
3154 framebuffer orientation, whether or not the system has a keyboard,
3155 the positioning of the keyboard in relation to the screen, and
3156 the screen resolution.
3157 </para>
3158
3159 <para>
3160 The build system uses reasonable defaults in most cases.
3161 However, if customization is
3162 necessary, you need to create a <filename>machconfig</filename> file
3163 in the <filename>meta/recipes-bsp/formfactor/files</filename>
3164 directory.
3165 This directory contains directories for specific machines such as
3166 <filename>qemuarm</filename> and <filename>qemux86</filename>.
3167 For information about the settings available and the defaults, see the
3168 <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
3169 same area.
3170 </para>
3171
3172 <para>
3173 Following is an example for "qemuarm" machine:
3174 <literallayout class='monospaced'>
3175 HAVE_TOUCHSCREEN=1
3176 HAVE_KEYBOARD=1
3177
3178 DISPLAY_CAN_ROTATE=0
3179 DISPLAY_ORIENTATION=0
3180 #DISPLAY_WIDTH_PIXELS=640
3181 #DISPLAY_HEIGHT_PIXELS=480
3182 #DISPLAY_BPP=16
3183 DISPLAY_DPI=150
3184 DISPLAY_SUBPIXEL_ORDER=vrgb
3185 </literallayout>
3186 </para>
3187 </section>
3188 </section>
3189
3190 <section id="platdev-working-with-libraries">
3191 <title>Working With Libraries</title>
3192
3193 <para>
3194 Libraries are an integral part of your system.
3195 This section describes some common practices you might find
3196 helpful when working with libraries to build your system:
3197 <itemizedlist>
3198 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
3199 </para></listitem>
3200 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
3201 </para></listitem>
3202 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
3203 </para></listitem>
3204 </itemizedlist>
3205 </para>
3206
3207 <section id='including-static-library-files'>
3208 <title>Including Static Library Files</title>