diff options
Diffstat (limited to 'documentation/dev-manual')
21 files changed, 15773 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml new file mode 100644 index 0000000000..64504299cc --- /dev/null +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
@@ -0,0 +1,9738 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='extendpoky'> | ||
6 | |||
7 | <title>Common Tasks</title> | ||
8 | <para> | ||
9 | This chapter describes fundamental procedures such as creating layers, | ||
10 | adding new software packages, extending or customizing images, | ||
11 | porting work to new hardware (adding a new machine), and so forth. | ||
12 | You will find that the procedures documented here occur often in the | ||
13 | development cycle using the Yocto Project. | ||
14 | </para> | ||
15 | |||
16 | <section id="understanding-and-creating-layers"> | ||
17 | <title>Understanding and Creating Layers</title> | ||
18 | |||
19 | <para> | ||
20 | The OpenEmbedded build system supports organizing | ||
21 | <link linkend='metadata'>Metadata</link> into multiple layers. | ||
22 | Layers allow you to isolate different types of customizations from | ||
23 | each other. | ||
24 | You might find it tempting to keep everything in one layer when | ||
25 | working on a single project. | ||
26 | However, the more modular your Metadata, the easier | ||
27 | it is to cope with future changes. | ||
28 | </para> | ||
29 | |||
30 | <para> | ||
31 | To illustrate how layers are used to keep things modular, consider | ||
32 | machine customizations. | ||
33 | These types of customizations typically reside in a special layer, | ||
34 | rather than a general layer, called a Board Support Package (BSP) | ||
35 | Layer. | ||
36 | Furthermore, the machine customizations should be isolated from | ||
37 | recipes and Metadata that support a new GUI environment, | ||
38 | for example. | ||
39 | This situation gives you a couple of layers: one for the machine | ||
40 | configurations, and one for the GUI environment. | ||
41 | It is important to understand, however, that the BSP layer can | ||
42 | still make machine-specific additions to recipes within the GUI | ||
43 | environment layer without polluting the GUI layer itself | ||
44 | with those machine-specific changes. | ||
45 | You can accomplish this through a recipe that is a BitBake append | ||
46 | (<filename>.bbappend</filename>) file, which is described later | ||
47 | in this section. | ||
48 | </para> | ||
49 | |||
50 | <para> | ||
51 | </para> | ||
52 | |||
53 | <section id='yocto-project-layers'> | ||
54 | <title>Layers</title> | ||
55 | |||
56 | <para> | ||
57 | The <link linkend='source-directory'>Source Directory</link> | ||
58 | contains both general layers and BSP | ||
59 | layers right out of the box. | ||
60 | You can easily identify layers that ship with a | ||
61 | Yocto Project release in the Source Directory by their | ||
62 | folder names. | ||
63 | Folders that represent layers typically have names that begin with | ||
64 | the string <filename>meta-</filename>. | ||
65 | <note> | ||
66 | It is not a requirement that a layer name begin with the | ||
67 | prefix <filename>meta-</filename>, but it is a commonly | ||
68 | accepted standard in the Yocto Project community. | ||
69 | </note> | ||
70 | For example, when you set up the Source Directory structure, | ||
71 | you will see several layers: | ||
72 | <filename>meta</filename>, | ||
73 | <filename>meta-skeleton</filename>, | ||
74 | <filename>meta-selftest</filename>, | ||
75 | <filename>meta-yocto</filename>, and | ||
76 | <filename>meta-yocto-bsp</filename>. | ||
77 | Each of these folders represents a distinct layer. | ||
78 | </para> | ||
79 | |||
80 | <para> | ||
81 | As another example, if you set up a local copy of the | ||
82 | <filename>meta-intel</filename> Git repository | ||
83 | and then explore the folder of that general layer, | ||
84 | you will discover many Intel-specific BSP layers inside. | ||
85 | For more information on BSP layers, see the | ||
86 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | ||
87 | section in the Yocto Project Board Support Package (BSP) | ||
88 | Developer's Guide. | ||
89 | </para> | ||
90 | </section> | ||
91 | |||
92 | <section id='creating-your-own-layer'> | ||
93 | <title>Creating Your Own Layer</title> | ||
94 | |||
95 | <para> | ||
96 | It is very easy to create your own layers to use with the | ||
97 | OpenEmbedded build system. | ||
98 | The Yocto Project ships with scripts that speed up creating | ||
99 | general layers and BSP layers. | ||
100 | This section describes the steps you perform by hand to create | ||
101 | a layer so that you can better understand them. | ||
102 | For information about the layer-creation scripts, see the | ||
103 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | ||
104 | section in the Yocto Project Board Support Package (BSP) | ||
105 | Developer's Guide and the | ||
106 | "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" | ||
107 | section further down in this manual. | ||
108 | </para> | ||
109 | |||
110 | <para> | ||
111 | Follow these general steps to create your layer: | ||
112 | <orderedlist> | ||
113 | <listitem><para><emphasis>Check Existing Layers:</emphasis> | ||
114 | Before creating a new layer, you should be sure someone | ||
115 | has not already created a layer containing the Metadata | ||
116 | you need. | ||
117 | You can see the | ||
118 | <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink> | ||
119 | for a list of layers from the OpenEmbedded community | ||
120 | that can be used in the Yocto Project. | ||
121 | </para></listitem> | ||
122 | <listitem><para><emphasis>Create a Directory:</emphasis> | ||
123 | Create the directory for your layer. | ||
124 | While not strictly required, prepend the name of the | ||
125 | folder with the string <filename>meta-</filename>. | ||
126 | For example: | ||
127 | <literallayout class='monospaced'> | ||
128 | meta-mylayer | ||
129 | meta-GUI_xyz | ||
130 | meta-mymachine | ||
131 | </literallayout> | ||
132 | </para></listitem> | ||
133 | <listitem><para><emphasis>Create a Layer Configuration | ||
134 | File:</emphasis> | ||
135 | Inside your new layer folder, you need to create a | ||
136 | <filename>conf/layer.conf</filename> file. | ||
137 | It is easiest to take an existing layer configuration | ||
138 | file and copy that to your layer's | ||
139 | <filename>conf</filename> directory and then modify the | ||
140 | file as needed.</para> | ||
141 | <para>The | ||
142 | <filename>meta-yocto-bsp/conf/layer.conf</filename> file | ||
143 | demonstrates the required syntax: | ||
144 | <literallayout class='monospaced'> | ||
145 | # We have a conf and classes directory, add to BBPATH | ||
146 | BBPATH .= ":${LAYERDIR}" | ||
147 | |||
148 | # We have recipes-* directories, add to BBFILES | ||
149 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ | ||
150 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
151 | |||
152 | BBFILE_COLLECTIONS += "yoctobsp" | ||
153 | BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" | ||
154 | BBFILE_PRIORITY_yoctobsp = "5" | ||
155 | LAYERVERSION_yoctobsp = "3" | ||
156 | </literallayout></para> | ||
157 | <para>Here is an explanation of the example: | ||
158 | <itemizedlist> | ||
159 | <listitem><para>The configuration and | ||
160 | classes directory is appended to | ||
161 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>. | ||
162 | <note> | ||
163 | All non-distro layers, which include all BSP | ||
164 | layers, are expected to append the layer | ||
165 | directory to the | ||
166 | <filename>BBPATH</filename>. | ||
167 | On the other hand, distro layers, such as | ||
168 | <filename>meta-yocto</filename>, can choose | ||
169 | to enforce their own precedence over | ||
170 | <filename>BBPATH</filename>. | ||
171 | For an example of that syntax, see the | ||
172 | <filename>layer.conf</filename> file for | ||
173 | the <filename>meta-yocto</filename> layer. | ||
174 | </note></para></listitem> | ||
175 | <listitem><para>The recipes for the layers are | ||
176 | appended to | ||
177 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>. | ||
178 | </para></listitem> | ||
179 | <listitem><para>The | ||
180 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> | ||
181 | variable is then appended with the layer name. | ||
182 | </para></listitem> | ||
183 | <listitem><para>The | ||
184 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename> | ||
185 | variable is set to a regular expression and is | ||
186 | used to match files from | ||
187 | <filename>BBFILES</filename> into a particular | ||
188 | layer. | ||
189 | In this case, | ||
190 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> | ||
191 | is used to make <filename>BBFILE_PATTERN</filename> match within the | ||
192 | layer's path.</para></listitem> | ||
193 | <listitem><para>The | ||
194 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename> | ||
195 | variable then assigns a priority to the layer. | ||
196 | Applying priorities is useful in situations | ||
197 | where the same recipe might appear in multiple | ||
198 | layers and allows you to choose the layer | ||
199 | that takes precedence.</para></listitem> | ||
200 | <listitem><para>The | ||
201 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename> | ||
202 | variable optionally specifies the version of a | ||
203 | layer as a single number.</para></listitem> | ||
204 | </itemizedlist></para> | ||
205 | <para>Note the use of the | ||
206 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> | ||
207 | variable, which expands to the directory of the current | ||
208 | layer.</para> | ||
209 | <para>Through the use of the <filename>BBPATH</filename> | ||
210 | variable, BitBake locates class files | ||
211 | (<filename>.bbclass</filename>), | ||
212 | configuration files, and files that are included | ||
213 | with <filename>include</filename> and | ||
214 | <filename>require</filename> statements. | ||
215 | For these cases, BitBake uses the first file that | ||
216 | matches the name found in <filename>BBPATH</filename>. | ||
217 | This is similar to the way the <filename>PATH</filename> | ||
218 | variable is used for binaries. | ||
219 | It is recommended, therefore, that you use unique | ||
220 | class and configuration | ||
221 | filenames in your custom layer.</para></listitem> | ||
222 | <listitem><para><emphasis>Add Content:</emphasis> Depending | ||
223 | on the type of layer, add the content. | ||
224 | If the layer adds support for a machine, add the machine | ||
225 | configuration in a <filename>conf/machine/</filename> | ||
226 | file within the layer. | ||
227 | If the layer adds distro policy, add the distro | ||
228 | configuration in a <filename>conf/distro/</filename> | ||
229 | file within the layer. | ||
230 | If the layer introduces new recipes, put the recipes | ||
231 | you need in <filename>recipes-*</filename> | ||
232 | subdirectories within the layer. | ||
233 | <note>In order to be compliant with the Yocto Project, | ||
234 | a layer must contain a | ||
235 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> | ||
236 | </note></para></listitem> | ||
237 | </orderedlist> | ||
238 | </para> | ||
239 | </section> | ||
240 | |||
241 | <section id='best-practices-to-follow-when-creating-layers'> | ||
242 | <title>Best Practices to Follow When Creating Layers</title> | ||
243 | |||
244 | <para> | ||
245 | To create layers that are easier to maintain and that will | ||
246 | not impact builds for other machines, you should consider the | ||
247 | information in the following sections. | ||
248 | </para> | ||
249 | |||
250 | <section id='avoid-overlaying-entire-recipes'> | ||
251 | <title>Avoid "Overlaying" Entire Recipes</title> | ||
252 | |||
253 | <para> | ||
254 | Avoid "overlaying" entire recipes from other layers in your | ||
255 | configuration. | ||
256 | In other words, do not copy an entire recipe into your | ||
257 | layer and then modify it. | ||
258 | Rather, use an append file (<filename>.bbappend</filename>) | ||
259 | to override | ||
260 | only those parts of the original recipe you need to modify. | ||
261 | </para> | ||
262 | </section> | ||
263 | |||
264 | <section id='avoid-duplicating-include-files'> | ||
265 | <title>Avoid Duplicating Include Files</title> | ||
266 | |||
267 | <para> | ||
268 | Avoid duplicating include files. | ||
269 | Use append files (<filename>.bbappend</filename>) | ||
270 | for each recipe | ||
271 | that uses an include file. | ||
272 | Or, if you are introducing a new recipe that requires | ||
273 | the included file, use the path relative to the original | ||
274 | layer directory to refer to the file. | ||
275 | For example, use | ||
276 | <filename>require recipes-core/somepackage/somefile.inc</filename> | ||
277 | instead of <filename>require somefile.inc</filename>. | ||
278 | If you're finding you have to overlay the include file, | ||
279 | it could indicate a deficiency in the include file in | ||
280 | the layer to which it originally belongs. | ||
281 | If this is the case, you need to address that deficiency | ||
282 | instead of overlaying the include file. | ||
283 | </para> | ||
284 | |||
285 | <para> | ||
286 | For example, consider how support plug-ins for the Qt 4 | ||
287 | database are configured. | ||
288 | The Source Directory does not have MySQL or PostgreSQL. | ||
289 | However, OpenEmbedded's layer <filename>meta-oe</filename> | ||
290 | does. | ||
291 | Consequently, <filename>meta-oe</filename> uses | ||
292 | append files to modify the | ||
293 | <filename>QT_SQL_DRIVER_FLAGS</filename> variable to | ||
294 | enable the appropriate plug-ins. | ||
295 | This variable was added to the <filename>qt4.inc</filename> | ||
296 | include file in the Source Directory specifically to allow | ||
297 | the <filename>meta-oe</filename> layer to be able to control | ||
298 | which plug-ins are built. | ||
299 | </para> | ||
300 | </section> | ||
301 | |||
302 | <section id='structure-your-layers'> | ||
303 | <title>Structure Your Layers</title> | ||
304 | |||
305 | <para> | ||
306 | Proper use of overrides within append files and placement | ||
307 | of machine-specific files within your layer can ensure that | ||
308 | a build is not using the wrong Metadata and negatively | ||
309 | impacting a build for a different machine. | ||
310 | Following are some examples: | ||
311 | <itemizedlist> | ||
312 | <listitem><para><emphasis>Modifying Variables to Support | ||
313 | a Different Machine:</emphasis> | ||
314 | Suppose you have a layer named | ||
315 | <filename>meta-one</filename> that adds support | ||
316 | for building machine "one". | ||
317 | To do so, you use an append file named | ||
318 | <filename>base-files.bbappend</filename> and | ||
319 | create a dependency on "foo" by altering the | ||
320 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
321 | variable: | ||
322 | <literallayout class='monospaced'> | ||
323 | DEPENDS = "foo" | ||
324 | </literallayout> | ||
325 | The dependency is created during any build that | ||
326 | includes the layer | ||
327 | <filename>meta-one</filename>. | ||
328 | However, you might not want this dependency | ||
329 | for all machines. | ||
330 | For example, suppose you are building for | ||
331 | machine "two" but your | ||
332 | <filename>bblayers.conf</filename> file has the | ||
333 | <filename>meta-one</filename> layer included. | ||
334 | During the build, the | ||
335 | <filename>base-files</filename> for machine | ||
336 | "two" will also have the dependency on | ||
337 | <filename>foo</filename>.</para> | ||
338 | <para>To make sure your changes apply only when | ||
339 | building machine "one", use a machine override | ||
340 | with the <filename>DEPENDS</filename> statement: | ||
341 | <literallayout class='monospaced'> | ||
342 | DEPENDS_one = "foo" | ||
343 | </literallayout> | ||
344 | You should follow the same strategy when using | ||
345 | <filename>_append</filename> and | ||
346 | <filename>_prepend</filename> operations: | ||
347 | <literallayout class='monospaced'> | ||
348 | DEPENDS_append_one = " foo" | ||
349 | DEPENDS_prepend_one = "foo " | ||
350 | </literallayout> | ||
351 | As an actual example, here's a line from the recipe for | ||
352 | the OProfile profiler, which lists an extra build-time | ||
353 | dependency when building specifically for 64-bit PowerPC: | ||
354 | <literallayout class='monospaced'> | ||
355 | DEPENDS_append_powerpc64 = " libpfm4" | ||
356 | </literallayout> | ||
357 | <note> | ||
358 | Avoiding "+=" and "=+" and using | ||
359 | machine-specific | ||
360 | <filename>_append</filename> | ||
361 | and <filename>_prepend</filename> operations | ||
362 | is recommended as well. | ||
363 | </note></para></listitem> | ||
364 | <listitem><para><emphasis>Place Machine-Specific Files | ||
365 | in Machine-Specific Locations:</emphasis> | ||
366 | When you have a base recipe, such as | ||
367 | <filename>base-files.bb</filename>, that | ||
368 | contains a | ||
369 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
370 | statement to a file, you can use an append file | ||
371 | to cause the build to use your own version of | ||
372 | the file. | ||
373 | For example, an append file in your layer at | ||
374 | <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename> | ||
375 | could extend | ||
376 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> | ||
377 | using | ||
378 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> | ||
379 | as follows: | ||
380 | <literallayout class='monospaced'> | ||
381 | FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" | ||
382 | </literallayout> | ||
383 | The build for machine "one" will pick up your | ||
384 | machine-specific file as long as you have the | ||
385 | file in | ||
386 | <filename>meta-one/recipes-core/base-files/base-files/</filename>. | ||
387 | However, if you are building for a different | ||
388 | machine and the | ||
389 | <filename>bblayers.conf</filename> file includes | ||
390 | the <filename>meta-one</filename> layer and | ||
391 | the location of your machine-specific file is | ||
392 | the first location where that file is found | ||
393 | according to <filename>FILESPATH</filename>, | ||
394 | builds for all machines will also use that | ||
395 | machine-specific file.</para> | ||
396 | <para>You can make sure that a machine-specific | ||
397 | file is used for a particular machine by putting | ||
398 | the file in a subdirectory specific to the | ||
399 | machine. | ||
400 | For example, rather than placing the file in | ||
401 | <filename>meta-one/recipes-core/base-files/base-files/</filename> | ||
402 | as shown above, put it in | ||
403 | <filename>meta-one/recipes-core/base-files/base-files/one/</filename>. | ||
404 | Not only does this make sure the file is used | ||
405 | only when building for machine "one", but the | ||
406 | build process locates the file more quickly.</para> | ||
407 | <para>In summary, you need to place all files | ||
408 | referenced from <filename>SRC_URI</filename> | ||
409 | in a machine-specific subdirectory within the | ||
410 | layer in order to restrict those files to | ||
411 | machine-specific builds.</para></listitem> | ||
412 | </itemizedlist> | ||
413 | </para> | ||
414 | </section> | ||
415 | |||
416 | <section id='other-recommendations'> | ||
417 | <title>Other Recommendations</title> | ||
418 | |||
419 | <para> | ||
420 | We also recommend the following: | ||
421 | <itemizedlist> | ||
422 | <listitem><para>Store custom layers in a Git repository | ||
423 | that uses the | ||
424 | <filename>meta-<replaceable>layer_name</replaceable></filename> format. | ||
425 | </para></listitem> | ||
426 | <listitem><para>Clone the repository alongside other | ||
427 | <filename>meta</filename> directories in the | ||
428 | <link linkend='source-directory'>Source Directory</link>. | ||
429 | </para></listitem> | ||
430 | </itemizedlist> | ||
431 | Following these recommendations keeps your Source Directory and | ||
432 | its configuration entirely inside the Yocto Project's core | ||
433 | base. | ||
434 | </para> | ||
435 | </section> | ||
436 | </section> | ||
437 | |||
438 | <section id='enabling-your-layer'> | ||
439 | <title>Enabling Your Layer</title> | ||
440 | |||
441 | <para> | ||
442 | Before the OpenEmbedded build system can use your new layer, | ||
443 | you need to enable it. | ||
444 | To enable your layer, simply add your layer's path to the | ||
445 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> | ||
446 | variable in your <filename>conf/bblayers.conf</filename> file, | ||
447 | which is found in the | ||
448 | <link linkend='build-directory'>Build Directory</link>. | ||
449 | The following example shows how to enable a layer named | ||
450 | <filename>meta-mylayer</filename>: | ||
451 | <literallayout class='monospaced'> | ||
452 | LCONF_VERSION = "6" | ||
453 | |||
454 | BBPATH = "${TOPDIR}" | ||
455 | BBFILES ?= "" | ||
456 | |||
457 | BBLAYERS ?= " \ | ||
458 | $HOME/poky/meta \ | ||
459 | $HOME/poky/meta-yocto \ | ||
460 | $HOME/poky/meta-yocto-bsp \ | ||
461 | $HOME/poky/meta-mylayer \ | ||
462 | " | ||
463 | |||
464 | BBLAYERS_NON_REMOVABLE ?= " \ | ||
465 | $HOME/poky/meta \ | ||
466 | $HOME/poky/meta-yocto \ | ||
467 | " | ||
468 | </literallayout> | ||
469 | </para> | ||
470 | |||
471 | <para> | ||
472 | BitBake parses each <filename>conf/layer.conf</filename> file | ||
473 | as specified in the <filename>BBLAYERS</filename> variable | ||
474 | within the <filename>conf/bblayers.conf</filename> file. | ||
475 | During the processing of each | ||
476 | <filename>conf/layer.conf</filename> file, BitBake adds the | ||
477 | recipes, classes and configurations contained within the | ||
478 | particular layer to the source directory. | ||
479 | </para> | ||
480 | </section> | ||
481 | |||
482 | <section id='using-bbappend-files'> | ||
483 | <title>Using .bbappend Files</title> | ||
484 | |||
485 | <para> | ||
486 | Recipes used to append Metadata to other recipes are called | ||
487 | BitBake append files. | ||
488 | BitBake append files use the <filename>.bbappend</filename> file | ||
489 | type suffix, while the corresponding recipes to which Metadata | ||
490 | is being appended use the <filename>.bb</filename> file type | ||
491 | suffix. | ||
492 | </para> | ||
493 | |||
494 | <para> | ||
495 | A <filename>.bbappend</filename> file allows your layer to make | ||
496 | additions or changes to the content of another layer's recipe | ||
497 | without having to copy the other recipe into your layer. | ||
498 | Your <filename>.bbappend</filename> file resides in your layer, | ||
499 | while the main <filename>.bb</filename> recipe file to | ||
500 | which you are appending Metadata resides in a different layer. | ||
501 | </para> | ||
502 | |||
503 | <para> | ||
504 | Append files must have the same root names as their corresponding | ||
505 | recipes. | ||
506 | For example, the append file | ||
507 | <filename>someapp_&DISTRO;.bbappend</filename> must apply to | ||
508 | <filename>someapp_&DISTRO;.bb</filename>. | ||
509 | This means the original recipe and append file names are version | ||
510 | number-specific. | ||
511 | If the corresponding recipe is renamed to update to a newer | ||
512 | version, the corresponding <filename>.bbappend</filename> file must | ||
513 | be renamed (and possibly updated) as well. | ||
514 | During the build process, BitBake displays an error on starting | ||
515 | if it detects a <filename>.bbappend</filename> file that does | ||
516 | not have a corresponding recipe with a matching name. | ||
517 | See the | ||
518 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink> | ||
519 | variable for information on how to handle this error. | ||
520 | </para> | ||
521 | |||
522 | <para> | ||
523 | Being able to append information to an existing recipe not only | ||
524 | avoids duplication, but also automatically applies recipe | ||
525 | changes in a different layer to your layer. | ||
526 | If you were copying recipes, you would have to manually merge | ||
527 | changes as they occur. | ||
528 | </para> | ||
529 | |||
530 | <para> | ||
531 | As an example, consider the main formfactor recipe and a | ||
532 | corresponding formfactor append file both from the | ||
533 | <link linkend='source-directory'>Source Directory</link>. | ||
534 | Here is the main formfactor recipe, which is named | ||
535 | <filename>formfactor_0.0.bb</filename> and located in the | ||
536 | "meta" layer at | ||
537 | <filename>meta/recipes-bsp/formfactor</filename>: | ||
538 | <literallayout class='monospaced'> | ||
539 | SUMMARY = "Device formfactor information" | ||
540 | SECTION = "base" | ||
541 | LICENSE = "MIT" | ||
542 | LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ | ||
543 | file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" | ||
544 | PR = "r45" | ||
545 | |||
546 | SRC_URI = "file://config file://machconfig" | ||
547 | S = "${WORKDIR}" | ||
548 | |||
549 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
550 | INHIBIT_DEFAULT_DEPS = "1" | ||
551 | |||
552 | do_install() { | ||
553 | # Install file only if it has contents | ||
554 | install -d ${D}${sysconfdir}/formfactor/ | ||
555 | install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ | ||
556 | if [ -s "${S}/machconfig" ]; then | ||
557 | install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ | ||
558 | fi | ||
559 | } | ||
560 | </literallayout> | ||
561 | In the main recipe, note the | ||
562 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
563 | variable, which tells the OpenEmbedded build system where to | ||
564 | find files during the build. | ||
565 | </para> | ||
566 | |||
567 | <para> | ||
568 | Following is the append file, which is named | ||
569 | <filename>formfactor_0.0.bbappend</filename> and is from the | ||
570 | Crown Bay BSP Layer named | ||
571 | <filename>meta-intel/meta-crownbay</filename>. | ||
572 | The file is in <filename>recipes-bsp/formfactor</filename>: | ||
573 | <literallayout class='monospaced'> | ||
574 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
575 | </literallayout> | ||
576 | </para> | ||
577 | |||
578 | <para> | ||
579 | By default, the build system uses the | ||
580 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> | ||
581 | variable to locate files. | ||
582 | This append file extends the locations by setting the | ||
583 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> | ||
584 | variable. | ||
585 | Setting this variable in the <filename>.bbappend</filename> | ||
586 | file is the most reliable and recommended method for adding | ||
587 | directories to the search path used by the build system | ||
588 | to find files. | ||
589 | </para> | ||
590 | |||
591 | <para> | ||
592 | The statement in this example extends the directories to include | ||
593 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>, | ||
594 | which resolves to a directory named | ||
595 | <filename>formfactor</filename> in the same directory | ||
596 | in which the append file resides (i.e. | ||
597 | <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>. | ||
598 | This implies that you must have the supporting directory | ||
599 | structure set up that will contain any files or patches you | ||
600 | will be including from the layer. | ||
601 | </para> | ||
602 | |||
603 | <para> | ||
604 | Using the immediate expansion assignment operator | ||
605 | <filename>:=</filename> is important because of the reference to | ||
606 | <filename>THISDIR</filename>. | ||
607 | The trailing colon character is important as it ensures that | ||
608 | items in the list remain colon-separated. | ||
609 | <note> | ||
610 | <para> | ||
611 | BitBake automatically defines the | ||
612 | <filename>THISDIR</filename> variable. | ||
613 | You should never set this variable yourself. | ||
614 | Using "_prepend" ensures your path will | ||
615 | be searched prior to other paths in the final list. | ||
616 | </para> | ||
617 | |||
618 | <para> | ||
619 | Also, not all append files add extra files. | ||
620 | Many append files simply exist to add build options | ||
621 | (e.g. <filename>systemd</filename>). | ||
622 | For these cases, it is not necessary to use the | ||
623 | "_prepend" part of the statement. | ||
624 | </para> | ||
625 | </note> | ||
626 | </para> | ||
627 | </section> | ||
628 | |||
629 | <section id='prioritizing-your-layer'> | ||
630 | <title>Prioritizing Your Layer</title> | ||
631 | |||
632 | <para> | ||
633 | Each layer is assigned a priority value. | ||
634 | Priority values control which layer takes precedence if there | ||
635 | are recipe files with the same name in multiple layers. | ||
636 | For these cases, the recipe file from the layer with a higher | ||
637 | priority number takes precedence. | ||
638 | Priority values also affect the order in which multiple | ||
639 | <filename>.bbappend</filename> files for the same recipe are | ||
640 | applied. | ||
641 | You can either specify the priority manually, or allow the | ||
642 | build system to calculate it based on the layer's dependencies. | ||
643 | </para> | ||
644 | |||
645 | <para> | ||
646 | To specify the layer's priority manually, use the | ||
647 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> | ||
648 | variable. | ||
649 | For example: | ||
650 | <literallayout class='monospaced'> | ||
651 | BBFILE_PRIORITY_mylayer = "1" | ||
652 | </literallayout> | ||
653 | </para> | ||
654 | |||
655 | <note> | ||
656 | <para>It is possible for a recipe with a lower version number | ||
657 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> | ||
658 | in a layer that has a higher priority to take precedence.</para> | ||
659 | <para>Also, the layer priority does not currently affect the | ||
660 | precedence order of <filename>.conf</filename> | ||
661 | or <filename>.bbclass</filename> files. | ||
662 | Future versions of BitBake might address this.</para> | ||
663 | </note> | ||
664 | </section> | ||
665 | |||
666 | <section id='managing-layers'> | ||
667 | <title>Managing Layers</title> | ||
668 | |||
669 | <para> | ||
670 | You can use the BitBake layer management tool to provide a view | ||
671 | into the structure of recipes across a multi-layer project. | ||
672 | Being able to generate output that reports on configured layers | ||
673 | with their paths and priorities and on | ||
674 | <filename>.bbappend</filename> files and their applicable | ||
675 | recipes can help to reveal potential problems. | ||
676 | </para> | ||
677 | |||
678 | <para> | ||
679 | Use the following form when running the layer management tool. | ||
680 | <literallayout class='monospaced'> | ||
681 | $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>] | ||
682 | </literallayout> | ||
683 | The following list describes the available commands: | ||
684 | <itemizedlist> | ||
685 | <listitem><para><filename><emphasis>help:</emphasis></filename> | ||
686 | Displays general help or help on a specified command. | ||
687 | </para></listitem> | ||
688 | <listitem><para><filename><emphasis>show-layers:</emphasis></filename> | ||
689 | Shows the current configured layers. | ||
690 | </para></listitem> | ||
691 | <listitem><para><filename><emphasis>show-recipes:</emphasis></filename> | ||
692 | Lists available recipes and the layers that provide them. | ||
693 | </para></listitem> | ||
694 | <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename> | ||
695 | Lists overlayed recipes. | ||
696 | A recipe is overlayed when a recipe with the same name | ||
697 | exists in another layer that has a higher layer | ||
698 | priority. | ||
699 | </para></listitem> | ||
700 | <listitem><para><filename><emphasis>show-appends:</emphasis></filename> | ||
701 | Lists <filename>.bbappend</filename> files and the | ||
702 | recipe files to which they apply. | ||
703 | </para></listitem> | ||
704 | <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename> | ||
705 | Lists dependency relationships between recipes that | ||
706 | cross layer boundaries. | ||
707 | </para></listitem> | ||
708 | <listitem><para><filename><emphasis>flatten:</emphasis></filename> | ||
709 | Flattens the layer configuration into a separate output | ||
710 | directory. | ||
711 | Flattening your layer configuration builds a "flattened" | ||
712 | directory that contains the contents of all layers, | ||
713 | with any overlayed recipes removed and any | ||
714 | <filename>.bbappend</filename> files appended to the | ||
715 | corresponding recipes. | ||
716 | You might have to perform some manual cleanup of the | ||
717 | flattened layer as follows: | ||
718 | <itemizedlist> | ||
719 | <listitem><para>Non-recipe files (such as patches) | ||
720 | are overwritten. | ||
721 | The flatten command shows a warning for these | ||
722 | files. | ||
723 | </para></listitem> | ||
724 | <listitem><para>Anything beyond the normal layer | ||
725 | setup has been added to the | ||
726 | <filename>layer.conf</filename> file. | ||
727 | Only the lowest priority layer's | ||
728 | <filename>layer.conf</filename> is used. | ||
729 | </para></listitem> | ||
730 | <listitem><para>Overridden and appended items from | ||
731 | <filename>.bbappend</filename> files need to be | ||
732 | cleaned up. | ||
733 | The contents of each | ||
734 | <filename>.bbappend</filename> end up in the | ||
735 | flattened recipe. | ||
736 | However, if there are appended or changed | ||
737 | variable values, you need to tidy these up | ||
738 | yourself. | ||
739 | Consider the following example. | ||
740 | Here, the <filename>bitbake-layers</filename> | ||
741 | command adds the line | ||
742 | <filename>#### bbappended ...</filename> so that | ||
743 | you know where the following lines originate: | ||
744 | <literallayout class='monospaced'> | ||
745 | ... | ||
746 | DESCRIPTION = "A useful utility" | ||
747 | ... | ||
748 | EXTRA_OECONF = "‐‐enable-something" | ||
749 | ... | ||
750 | |||
751 | #### bbappended from meta-anotherlayer #### | ||
752 | |||
753 | DESCRIPTION = "Customized utility" | ||
754 | EXTRA_OECONF += "‐‐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 = "‐‐enable-something ‐‐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 ‐‐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 ‐‐help</filename> command within | ||
2169 | <filename>${S}</filename> or consult the software's upstream | ||
2170 | documentation. | ||
2171 | </para> | ||
2172 | </section> | ||
2173 | |||
2174 | <section id='new-recipe-compilation'> | ||
2175 | <title>Compilation</title> | ||
2176 | |||
2177 | <para> | ||
2178 | During a build, the <filename>do_compile</filename> task | ||
2179 | happens after source is fetched, unpacked, and configured. | ||
2180 | If the recipe passes through <filename>do_compile</filename> | ||
2181 | successfully, nothing needs to be done. | ||
2182 | </para> | ||
2183 | |||
2184 | <para> | ||
2185 | However, if the compile step fails, you need to diagnose the | ||
2186 | failure. | ||
2187 | Here are some common issues that cause failures: | ||
2188 | <itemizedlist> | ||
2189 | <listitem><para><emphasis>Parallel build failures:</emphasis> | ||
2190 | These failures manifest themselves as intermittent | ||
2191 | errors, or errors reporting that a file or directory | ||
2192 | that should be created by some other part of the build | ||
2193 | process could not be found. | ||
2194 | This type of failure can occur even if, upon inspection, | ||
2195 | the file or directory does exist after the build has | ||
2196 | failed, because that part of the build process happened | ||
2197 | in the wrong order.</para> | ||
2198 | <para>To fix the problem, you need to either satisfy | ||
2199 | the missing dependency in the Makefile or whatever | ||
2200 | script produced the Makefile, or (as a workaround) | ||
2201 | set | ||
2202 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> | ||
2203 | to an empty string: | ||
2204 | <literallayout class='monospaced'> | ||
2205 | PARALLEL_MAKE = "" | ||
2206 | </literallayout></para> | ||
2207 | <para> | ||
2208 | For information on parallel Makefile issues, see the | ||
2209 | "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>" | ||
2210 | section. | ||
2211 | </para></listitem> | ||
2212 | <listitem><para><emphasis>Improper host path usage:</emphasis> | ||
2213 | This failure applies to recipes building for the target | ||
2214 | or <filename>nativesdk</filename> only. | ||
2215 | The failure occurs when the compilation process uses | ||
2216 | improper headers, libraries, or other files from the | ||
2217 | host system when cross-compiling for the target. | ||
2218 | </para> | ||
2219 | <para>To fix the problem, examine the | ||
2220 | <filename>log.do_compile</filename> file to identify | ||
2221 | the host paths being used (e.g. | ||
2222 | <filename>/usr/include</filename>, | ||
2223 | <filename>/usr/lib</filename>, and so forth) and then | ||
2224 | either add configure options, apply a patch, or do both. | ||
2225 | </para></listitem> | ||
2226 | <listitem><para><emphasis>Failure to find required | ||
2227 | libraries/headers:</emphasis> | ||
2228 | If a build-time dependency is missing because it has | ||
2229 | not been declared in | ||
2230 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, | ||
2231 | or because the dependency exists but the path used by | ||
2232 | the build process to find the file is incorrect and the | ||
2233 | configure step did not detect it, the compilation | ||
2234 | process could fail. | ||
2235 | For either of these failures, the compilation process | ||
2236 | notes that files could not be found. | ||
2237 | In these cases, you need to go back and add additional | ||
2238 | options to the configure script as well as possibly | ||
2239 | add additional build-time dependencies to | ||
2240 | <filename>DEPENDS</filename>.</para> | ||
2241 | <para>Occasionally, it is necessary to apply a patch | ||
2242 | to the source to ensure the correct paths are used. | ||
2243 | If you need to specify paths to find files staged | ||
2244 | into the sysroot from other recipes, use the variables | ||
2245 | that the OpenEmbedded build system provides | ||
2246 | (e.g. | ||
2247 | <filename>STAGING_BINDIR</filename>, | ||
2248 | <filename>STAGING_INCDIR</filename>, | ||
2249 | <filename>STAGING_DATADIR</filename>, and so forth). | ||
2250 | <!-- | ||
2251 | (e.g. | ||
2252 | <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>, | ||
2253 | <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>, | ||
2254 | <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>, | ||
2255 | and so forth). | ||
2256 | --> | ||
2257 | </para></listitem> | ||
2258 | </itemizedlist> | ||
2259 | </para> | ||
2260 | </section> | ||
2261 | |||
2262 | <section id='new-recipe-installing'> | ||
2263 | <title>Installing</title> | ||
2264 | |||
2265 | <para> | ||
2266 | During <filename>do_install</filename>, the task copies the | ||
2267 | built files along with their hierarchy to locations that | ||
2268 | would mirror their locations on the target device. | ||
2269 | The installation process copies files from the | ||
2270 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, | ||
2271 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, | ||
2272 | and | ||
2273 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> | ||
2274 | directories to the | ||
2275 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> | ||
2276 | directory to create the structure as it should appear on the | ||
2277 | target system. | ||
2278 | </para> | ||
2279 | |||
2280 | <para> | ||
2281 | How your software is built affects what you must do to be | ||
2282 | sure your software is installed correctly. | ||
2283 | The following list describes what you must do for installation | ||
2284 | depending on the type of build system used by the software | ||
2285 | being built: | ||
2286 | <itemizedlist> | ||
2287 | <listitem><para><emphasis>Autotools and CMake:</emphasis> | ||
2288 | If the software your recipe is building uses Autotools | ||
2289 | or CMake, the OpenEmbedded build | ||
2290 | system understands how to install the software. | ||
2291 | Consequently, you do not have to have a | ||
2292 | <filename>do_install</filename> task as part of your | ||
2293 | recipe. | ||
2294 | You just need to make sure the install portion of the | ||
2295 | build completes with no issues. | ||
2296 | However, if you wish to install additional files not | ||
2297 | already being installed by | ||
2298 | <filename>make install</filename>, you should do this | ||
2299 | using a <filename>do_install_append</filename> function | ||
2300 | using the install command as described in | ||
2301 | the "Manual" bulleted item later in this list. | ||
2302 | </para></listitem> | ||
2303 | <listitem><para><emphasis>Other (using | ||
2304 | <filename>make install</filename>):</emphasis> | ||
2305 | You need to define a | ||
2306 | <filename>do_install</filename> function in your | ||
2307 | recipe. | ||
2308 | The function should call | ||
2309 | <filename>oe_runmake install</filename> and will likely | ||
2310 | need to pass in the destination directory as well. | ||
2311 | How you pass that path is dependent on how the | ||
2312 | <filename>Makefile</filename> being run is written | ||
2313 | (e.g. <filename>DESTDIR=${D}</filename>, | ||
2314 | <filename>PREFIX=${D}</filename>, | ||
2315 | <filename>INSTALLROOT=${D}</filename>, and so forth). | ||
2316 | </para> | ||
2317 | <para>For an example recipe using | ||
2318 | <filename>make install</filename>, see the | ||
2319 | "<link linkend='new-recipe-makefile-based-package'>Makefile-Based Package</link>" | ||
2320 | section.</para></listitem> | ||
2321 | <listitem><para><emphasis>Manual:</emphasis> | ||
2322 | You need to define a | ||
2323 | <filename>do_install</filename> function in your | ||
2324 | recipe. | ||
2325 | The function must first use | ||
2326 | <filename>install -d</filename> to create the | ||
2327 | directories under | ||
2328 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. | ||
2329 | Once the directories exist, your function can use | ||
2330 | <filename>install</filename> to manually install the | ||
2331 | built software into the directories.</para> | ||
2332 | <para>You can find more information on | ||
2333 | <filename>install</filename> at | ||
2334 | <ulink url='http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html'></ulink>. | ||
2335 | </para></listitem> | ||
2336 | </itemizedlist> | ||
2337 | </para> | ||
2338 | |||
2339 | <para> | ||
2340 | For the scenarios that do not use Autotools or | ||
2341 | CMake, you need to track the installation | ||
2342 | and diagnose and fix any issues until everything installs | ||
2343 | correctly. | ||
2344 | You need to look in the default location of | ||
2345 | <filename>${D}</filename>, which is | ||
2346 | <filename>${WORKDIR}/image</filename>, to be sure your | ||
2347 | files have been installed correctly. | ||
2348 | </para> | ||
2349 | |||
2350 | <note><title>Notes</title> | ||
2351 | <itemizedlist> | ||
2352 | <listitem><para> | ||
2353 | During the installation process, you might need to | ||
2354 | modify some of the installed files to suit the target | ||
2355 | layout. | ||
2356 | For example, you might need to replace hard-coded paths | ||
2357 | in an initscript with values of variables provided by | ||
2358 | the build system, such as replacing | ||
2359 | <filename>/usr/bin/</filename> with | ||
2360 | <filename>${bindir}</filename>. | ||
2361 | If you do perform such modifications during | ||
2362 | <filename>do_install</filename>, be sure to modify the | ||
2363 | destination file after copying rather than before | ||
2364 | copying. | ||
2365 | Modifying after copying ensures that the build system | ||
2366 | can re-execute <filename>do_install</filename> if | ||
2367 | needed. | ||
2368 | </para></listitem> | ||
2369 | <listitem><para> | ||
2370 | <filename>oe_runmake install</filename>, which can be | ||
2371 | run directly or can be run indirectly by the | ||
2372 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> | ||
2373 | and | ||
2374 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink> | ||
2375 | classes, runs <filename>make install</filename> in | ||
2376 | parallel. | ||
2377 | Sometimes, a Makefile can have missing dependencies | ||
2378 | between targets that can result in race conditions. | ||
2379 | If you experience intermittent failures during | ||
2380 | <filename>do_install</filename>, you might be able to | ||
2381 | work around them by disabling parallel Makefile | ||
2382 | installs by adding the following to the recipe: | ||
2383 | <literallayout class='monospaced'> | ||
2384 | PARALLEL_MAKEINST = "" | ||
2385 | </literallayout> | ||
2386 | See | ||
2387 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> | ||
2388 | for additional information. | ||
2389 | </para></listitem> | ||
2390 | </itemizedlist> | ||
2391 | </note> | ||
2392 | </section> | ||
2393 | |||
2394 | <section id='new-recipe-enabling-system-services'> | ||
2395 | <title>Enabling System Services</title> | ||
2396 | |||
2397 | <para> | ||
2398 | If you want to install a service, which is a process that | ||
2399 | usually starts on boot and runs in the background, then | ||
2400 | you must include some additional definitions in your recipe. | ||
2401 | </para> | ||
2402 | |||
2403 | <para> | ||
2404 | If you are adding services and the service initialization | ||
2405 | script or the service file itself is not installed, you must | ||
2406 | provide for that installation in your recipe using a | ||
2407 | <filename>do_install_append</filename> function. | ||
2408 | If your recipe already has a <filename>do_install</filename> | ||
2409 | function, update the function near its end rather than | ||
2410 | adding an additional <filename>do_install_append</filename> | ||
2411 | function. | ||
2412 | </para> | ||
2413 | |||
2414 | <para> | ||
2415 | When you create the installation for your services, you need | ||
2416 | to accomplish what is normally done by | ||
2417 | <filename>make install</filename>. | ||
2418 | In other words, make sure your installation arranges the output | ||
2419 | similar to how it is arranged on the target system. | ||
2420 | </para> | ||
2421 | |||
2422 | <para> | ||
2423 | The OpenEmbedded build system provides support for starting | ||
2424 | services two different ways: | ||
2425 | <itemizedlist> | ||
2426 | <listitem><para><emphasis>SysVinit:</emphasis> | ||
2427 | SysVinit is a system and service manager that | ||
2428 | manages the init system used to control the very basic | ||
2429 | functions of your system. | ||
2430 | The init program is the first program | ||
2431 | started by the Linux kernel when the system boots. | ||
2432 | Init then controls the startup, running and shutdown | ||
2433 | of all other programs.</para> | ||
2434 | <para>To enable a service using SysVinit, your recipe | ||
2435 | needs to inherit the | ||
2436 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-update-rc.d'><filename>update-rc.d</filename></ulink> | ||
2437 | class. | ||
2438 | The class helps facilitate safely installing the | ||
2439 | package on the target.</para> | ||
2440 | <para>You will need to set the | ||
2441 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PACKAGES'><filename>INITSCRIPT_PACKAGES</filename></ulink>, | ||
2442 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_NAME'><filename>INITSCRIPT_NAME</filename></ulink>, | ||
2443 | and | ||
2444 | <ulink url='&YOCTO_DOCS_REF_URL;#var-INITSCRIPT_PARAMS'><filename>INITSCRIPT_PARAMS</filename></ulink> | ||
2445 | variables within your recipe.</para></listitem> | ||
2446 | <listitem><para><emphasis>systemd:</emphasis> | ||
2447 | System Management Daemon (systemd) was designed to | ||
2448 | replace SysVinit and to provide | ||
2449 | enhanced management of services. | ||
2450 | For more information on systemd, see the systemd | ||
2451 | homepage at | ||
2452 | <ulink url='http://freedesktop.org/wiki/Software/systemd/'></ulink>. | ||
2453 | </para> | ||
2454 | <para>To enable a service using systemd, your recipe | ||
2455 | needs to inherit the | ||
2456 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink> | ||
2457 | class. | ||
2458 | See the <filename>systemd.bbclass</filename> file | ||
2459 | located in your | ||
2460 | <link linkend='source-directory'>Source Directory</link>. | ||
2461 | section for more information. | ||
2462 | </para></listitem> | ||
2463 | </itemizedlist> | ||
2464 | </para> | ||
2465 | </section> | ||
2466 | |||
2467 | <section id='new-recipe-packaging'> | ||
2468 | <title>Packaging</title> | ||
2469 | |||
2470 | <para> | ||
2471 | Successful packaging is a combination of automated processes | ||
2472 | performed by the OpenEmbedded build system and some | ||
2473 | specific steps you need to take. | ||
2474 | The following list describes the process: | ||
2475 | <itemizedlist> | ||
2476 | <listitem><para><emphasis>Splitting Files</emphasis>: | ||
2477 | The <filename>do_package</filename> task splits the | ||
2478 | files produced by the recipe into logical components. | ||
2479 | Even software that produces a single binary might | ||
2480 | still have debug symbols, documentation, and other | ||
2481 | logical components that should be split out. | ||
2482 | The <filename>do_package</filename> task ensures | ||
2483 | that files are split up and packaged correctly. | ||
2484 | </para></listitem> | ||
2485 | <listitem><para><emphasis>Running QA Checks</emphasis>: | ||
2486 | The | ||
2487 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink> | ||
2488 | class adds a step to | ||
2489 | the package generation process so that output quality | ||
2490 | assurance checks are generated by the OpenEmbedded | ||
2491 | build system. | ||
2492 | This step performs a range of checks to be sure the | ||
2493 | build's output is free of common problems that show | ||
2494 | up during runtime. | ||
2495 | For information on these checks, see the | ||
2496 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink> | ||
2497 | class and the | ||
2498 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>" | ||
2499 | chapter in the Yocto Project Reference Manual. | ||
2500 | </para></listitem> | ||
2501 | <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>: | ||
2502 | After you build your software, you need to be sure | ||
2503 | your packages are correct. | ||
2504 | Examine the | ||
2505 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename> | ||
2506 | directory and make sure files are where you expect | ||
2507 | them to be. | ||
2508 | If you discover problems, you can set | ||
2509 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, | ||
2510 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>, | ||
2511 | <filename>do_install(_append)</filename>, and so forth as | ||
2512 | needed. | ||
2513 | </para></listitem> | ||
2514 | <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>: | ||
2515 | If you need to split an application into several | ||
2516 | packages, see the | ||
2517 | "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>" | ||
2518 | section for an example. | ||
2519 | </para></listitem> | ||
2520 | <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>: | ||
2521 | For an example showing how to install a | ||
2522 | post-installation script, see the | ||
2523 | "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>" | ||
2524 | section. | ||
2525 | </para></listitem> | ||
2526 | <listitem><para><emphasis>Marking Package Architecture</emphasis>: | ||
2527 | Depending on what your recipe is building and how it | ||
2528 | is configured, it might be important to mark the | ||
2529 | packages produced as being specific to a particular | ||
2530 | machine, or to mark them as not being specific to | ||
2531 | a particular machine or architecture at all. | ||
2532 | By default, packages produced for the target are | ||
2533 | marked as being specific to the architecture of the | ||
2534 | target machine because that is usually the desired | ||
2535 | result. | ||
2536 | However, if the recipe configures the software to be | ||
2537 | built specific to the target machine (e.g. the | ||
2538 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
2539 | value is passed into the configure script or a patch | ||
2540 | is applied only for a particular machine), then you | ||
2541 | should mark the packages produced as being | ||
2542 | machine-specific by adding the following to the | ||
2543 | recipe: | ||
2544 | <literallayout class='monospaced'> | ||
2545 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
2546 | </literallayout> | ||
2547 | On the other hand, if the recipe produces packages | ||
2548 | that do not contain anything specific to the target | ||
2549 | machine or architecture at all (e.g. recipes | ||
2550 | that simply package script files or configuration | ||
2551 | files), you should use the | ||
2552 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> | ||
2553 | class to do this for you by adding this to your | ||
2554 | recipe: | ||
2555 | <literallayout class='monospaced'> | ||
2556 | inherit allarch | ||
2557 | </literallayout> | ||
2558 | Ensuring that the package architecture is correct is | ||
2559 | not critical while you are doing the first few builds | ||
2560 | of your recipe. | ||
2561 | However, it is important in order | ||
2562 | to ensure that your recipe rebuilds (or does not | ||
2563 | rebuild) appropriately in response to changes in | ||
2564 | configuration, and to ensure that you get the | ||
2565 | appropriate packages installed on the target machine, | ||
2566 | particularly if you run separate builds for more | ||
2567 | than one target machine. | ||
2568 | </para></listitem> | ||
2569 | </itemizedlist> | ||
2570 | </para> | ||
2571 | </section> | ||
2572 | |||
2573 | <section id='properly-versioning-pre-release-recipes'> | ||
2574 | <title>Properly Versioning Pre-Release Recipes</title> | ||
2575 | |||
2576 | <para> | ||
2577 | Sometimes the name of a recipe can lead to versioning | ||
2578 | problems when the recipe is upgraded to a final release. | ||
2579 | For example, consider the | ||
2580 | <filename>irssi_0.8.16-rc1.bb</filename> recipe file in | ||
2581 | the list of example recipes in the | ||
2582 | "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>" | ||
2583 | section. | ||
2584 | This recipe is at a release candidate stage (i.e. | ||
2585 | "rc1"). | ||
2586 | When the recipe is released, the recipe filename becomes | ||
2587 | <filename>irssi_0.8.16.bb</filename>. | ||
2588 | The version change from <filename>0.8.16-rc1</filename> | ||
2589 | to <filename>0.8.16</filename> is seen as a decrease by the | ||
2590 | build system and package managers, so the resulting packages | ||
2591 | will not correctly trigger an upgrade. | ||
2592 | </para> | ||
2593 | |||
2594 | <para> | ||
2595 | In order to ensure the versions compare properly, the | ||
2596 | recommended convention is to set | ||
2597 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> | ||
2598 | within the recipe to | ||
2599 | "<replaceable>previous_version</replaceable>+<replaceable>current_version</replaceable>". | ||
2600 | You can use an additional variable so that you can use the | ||
2601 | current version elsewhere. | ||
2602 | Here is an example: | ||
2603 | <literallayout class='monospaced'> | ||
2604 | REALPV = "0.8.16-rc1" | ||
2605 | PV = "0.8.15+${REALPV}" | ||
2606 | </literallayout> | ||
2607 | </para> | ||
2608 | </section> | ||
2609 | |||
2610 | <section id='new-recipe-post-installation-scripts'> | ||
2611 | <title>Post-Installation Scripts</title> | ||
2612 | |||
2613 | <para> | ||
2614 | Post-installation scripts run immediately after installing | ||
2615 | a package on the target or during image creation when a | ||
2616 | package is included in an image. | ||
2617 | To add a post-installation script to a package, add a | ||
2618 | <filename>pkg_postinst_PACKAGENAME()</filename> function to | ||
2619 | the recipe file (<filename>.bb</filename>) and replace | ||
2620 | <filename>PACKAGENAME</filename> with the name of the package | ||
2621 | you want to attach to the <filename>postinst</filename> | ||
2622 | script. | ||
2623 | To apply the post-installation script to the main package | ||
2624 | for the recipe, which is usually what is required, specify | ||
2625 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> | ||
2626 | in place of <filename>PACKAGENAME</filename>. | ||
2627 | </para> | ||
2628 | |||
2629 | <para> | ||
2630 | A post-installation function has the following structure: | ||
2631 | <literallayout class='monospaced'> | ||
2632 | pkg_postinst_PACKAGENAME() { | ||
2633 | #!/bin/sh -e | ||
2634 | # Commands to carry out | ||
2635 | } | ||
2636 | </literallayout> | ||
2637 | </para> | ||
2638 | |||
2639 | <para> | ||
2640 | The script defined in the post-installation function is | ||
2641 | called when the root filesystem is created. | ||
2642 | If the script succeeds, the package is marked as installed. | ||
2643 | If the script fails, the package is marked as unpacked and | ||
2644 | the script is executed when the image boots again. | ||
2645 | </para> | ||
2646 | |||
2647 | <para> | ||
2648 | Sometimes it is necessary for the execution of a | ||
2649 | post-installation script to be delayed until the first boot. | ||
2650 | For example, the script might need to be executed on the | ||
2651 | device itself. | ||
2652 | To delay script execution until boot time, use the following | ||
2653 | structure in the post-installation script: | ||
2654 | <literallayout class='monospaced'> | ||
2655 | pkg_postinst_PACKAGENAME() { | ||
2656 | #!/bin/sh -e | ||
2657 | if [ x"$D" = "x" ]; then | ||
2658 | # Actions to carry out on the device go here | ||
2659 | else | ||
2660 | exit 1 | ||
2661 | fi | ||
2662 | } | ||
2663 | </literallayout> | ||
2664 | </para> | ||
2665 | |||
2666 | <para> | ||
2667 | The previous example delays execution until the image boots | ||
2668 | again because the environment variable <filename>D</filename> | ||
2669 | points to the directory containing the image when | ||
2670 | the root filesystem is created at build time but is unset | ||
2671 | when executed on the first boot. | ||
2672 | </para> | ||
2673 | |||
2674 | <note> | ||
2675 | Equivalent support for pre-install, pre-uninstall, and | ||
2676 | post-uninstall scripts exist by way of | ||
2677 | <filename>pkg_preinst</filename>, | ||
2678 | <filename>pkg_prerm</filename>, and | ||
2679 | <filename>pkg_postrm</filename>, respectively. | ||
2680 | These scrips work in exactly the same way as does | ||
2681 | <filename>pkg_postinst</filename> with the exception that they | ||
2682 | run at different times. | ||
2683 | Also, because of when they run, they are not applicable to | ||
2684 | being run at image creation time like | ||
2685 | <filename>pkg_postinst</filename>. | ||
2686 | </note> | ||
2687 | </section> | ||
2688 | |||
2689 | <section id='new-recipe-testing'> | ||
2690 | <title>Testing</title> | ||
2691 | |||
2692 | <para> | ||
2693 | The final step for completing your recipe is to be sure that | ||
2694 | the software you built runs correctly. | ||
2695 | To accomplish runtime testing, add the build's output | ||
2696 | packages to your image and test them on the target. | ||
2697 | </para> | ||
2698 | |||
2699 | <para> | ||
2700 | For information on how to customize your image by adding | ||
2701 | specific packages, see the | ||
2702 | "<link linkend='usingpoky-extend-customimage'>Customizing Images</link>" | ||
2703 | section. | ||
2704 | </para> | ||
2705 | </section> | ||
2706 | |||
2707 | <section id='new-recipe-testing-examples'> | ||
2708 | <title>Examples</title> | ||
2709 | |||
2710 | <para> | ||
2711 | To help summarize how to write a recipe, this section provides | ||
2712 | some examples given various scenarios: | ||
2713 | <itemizedlist> | ||
2714 | <listitem><para>Recipes that use local files</para></listitem> | ||
2715 | <listitem><para>Using an Autotooled package</para></listitem> | ||
2716 | <listitem><para>Using a Makefile-based package</para></listitem> | ||
2717 | <listitem><para>Splitting an application into multiple packages</para></listitem> | ||
2718 | <listitem><para>Adding binaries to an image</para></listitem> | ||
2719 | </itemizedlist> | ||
2720 | </para> | ||
2721 | |||
2722 | <section id='new-recipe-single-c-file-package-hello-world'> | ||
2723 | <title>Single .c File Package (Hello World!)</title> | ||
2724 | |||
2725 | <para> | ||
2726 | Building an application from a single file that is stored | ||
2727 | locally (e.g. under <filename>files</filename>) requires | ||
2728 | a recipe that has the file listed in the | ||
2729 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | ||
2730 | variable. | ||
2731 | Additionally, you need to manually write the | ||
2732 | <filename>do_compile</filename> and | ||
2733 | <filename>do_install</filename> tasks. | ||
2734 | The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> | ||
2735 | variable defines the directory containing the source code, | ||
2736 | which is set to | ||
2737 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> | ||
2738 | in this case - the directory BitBake uses for the build. | ||
2739 | <literallayout class='monospaced'> | ||
2740 | SUMMARY = "Simple helloworld application" | ||
2741 | SECTION = "examples" | ||
2742 | LICENSE = "MIT" | ||
2743 | LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" | ||
2744 | |||
2745 | SRC_URI = "file://helloworld.c" | ||
2746 | |||
2747 | S = "${WORKDIR}" | ||
2748 | |||
2749 | do_compile() { | ||
2750 | ${CC} helloworld.c -o helloworld | ||
2751 | } | ||
2752 | |||
2753 | do_install() { | ||
2754 | install -d ${D}${bindir} | ||
2755 | install -m 0755 helloworld ${D}${bindir} | ||
2756 | } | ||
2757 | </literallayout> | ||
2758 | </para> | ||
2759 | |||
2760 | <para> | ||
2761 | By default, the <filename>helloworld</filename>, | ||
2762 | <filename>helloworld-dbg</filename>, and | ||
2763 | <filename>helloworld-dev</filename> packages are built. | ||
2764 | For information on how to customize the packaging process, | ||
2765 | see the | ||
2766 | "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>" | ||
2767 | section. | ||
2768 | </para> | ||
2769 | </section> | ||
2770 | |||
2771 | <section id='new-recipe-autotooled-package'> | ||
2772 | <title>Autotooled Package</title> | ||
2773 | <para> | ||
2774 | Applications that use Autotools such as <filename>autoconf</filename> and | ||
2775 | <filename>automake</filename> require a recipe that has a source archive listed in | ||
2776 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and | ||
2777 | also inherit the | ||
2778 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> | ||
2779 | class, which contains the definitions of all the steps | ||
2780 | needed to build an Autotool-based application. | ||
2781 | The result of the build is automatically packaged. | ||
2782 | And, if the application uses NLS for localization, packages with local information are | ||
2783 | generated (one package per language). | ||
2784 | Following is one example: (<filename>hello_2.3.bb</filename>) | ||
2785 | <literallayout class='monospaced'> | ||
2786 | SUMMARY = "GNU Helloworld application" | ||
2787 | SECTION = "examples" | ||
2788 | LICENSE = "GPLv2+" | ||
2789 | LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" | ||
2790 | |||
2791 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
2792 | |||
2793 | inherit autotools gettext | ||
2794 | </literallayout> | ||
2795 | </para> | ||
2796 | |||
2797 | <para> | ||
2798 | The variable | ||
2799 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> | ||
2800 | is used to track source license changes as described in the | ||
2801 | "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section. | ||
2802 | You can quickly create Autotool-based recipes in a manner similar to the previous example. | ||
2803 | </para> | ||
2804 | </section> | ||
2805 | |||
2806 | <section id='new-recipe-makefile-based-package'> | ||
2807 | <title>Makefile-Based Package</title> | ||
2808 | |||
2809 | <para> | ||
2810 | Applications that use GNU <filename>make</filename> also require a recipe that has | ||
2811 | the source archive listed in | ||
2812 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. | ||
2813 | You do not need to add a <filename>do_compile</filename> step since by default BitBake | ||
2814 | starts the <filename>make</filename> command to compile the application. | ||
2815 | If you need additional <filename>make</filename> options, you should store them in the | ||
2816 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> | ||
2817 | variable. | ||
2818 | BitBake passes these options into the GNU <filename>make</filename> invocation. | ||
2819 | Note that a <filename>do_install</filename> task is still required. | ||
2820 | Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. | ||
2821 | </para> | ||
2822 | |||
2823 | <para> | ||
2824 | Some applications might require extra parameters to be passed to the compiler. | ||
2825 | For example, the application might need an additional header path. | ||
2826 | You can accomplish this by adding to the | ||
2827 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable. | ||
2828 | The following example shows this: | ||
2829 | <literallayout class='monospaced'> | ||
2830 | CFLAGS_prepend = "-I ${S}/include " | ||
2831 | </literallayout> | ||
2832 | </para> | ||
2833 | |||
2834 | <para> | ||
2835 | In the following example, <filename>mtd-utils</filename> is a makefile-based package: | ||
2836 | <literallayout class='monospaced'> | ||
2837 | SUMMARY = "Tools for managing memory technology devices" | ||
2838 | SECTION = "base" | ||
2839 | DEPENDS = "zlib lzo e2fsprogs util-linux" | ||
2840 | HOMEPAGE = "http://www.linux-mtd.infradead.org/" | ||
2841 | LICENSE = "GPLv2+" | ||
2842 | LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ | ||
2843 | file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" | ||
2844 | |||
2845 | # Use the latest version at 26 Oct, 2013 | ||
2846 | SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b" | ||
2847 | SRC_URI = "git://git.infradead.org/mtd-utils.git \ | ||
2848 | file://add-exclusion-to-mkfs-jffs2-git-2.patch \ | ||
2849 | " | ||
2850 | |||
2851 | PV = "1.5.1+git${SRCPV}" | ||
2852 | |||
2853 | S = "${WORKDIR}/git/" | ||
2854 | |||
2855 | EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" | ||
2856 | |||
2857 | do_install () { | ||
2858 | oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir} | ||
2859 | } | ||
2860 | |||
2861 | PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc" | ||
2862 | |||
2863 | FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" | ||
2864 | FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" | ||
2865 | FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image" | ||
2866 | |||
2867 | PARALLEL_MAKE = "" | ||
2868 | |||
2869 | BBCLASSEXTEND = "native" | ||
2870 | </literallayout> | ||
2871 | </para> | ||
2872 | </section> | ||
2873 | |||
2874 | <section id='splitting-an-application-into-multiple-packages'> | ||
2875 | <title>Splitting an Application into Multiple Packages</title> | ||
2876 | |||
2877 | <para> | ||
2878 | You can use the variables | ||
2879 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and | ||
2880 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename> | ||
2881 | to split an application into multiple packages. | ||
2882 | </para> | ||
2883 | |||
2884 | <para> | ||
2885 | Following is an example that uses the <filename>libxpm</filename> recipe. | ||
2886 | By default, this recipe generates a single package that contains the library along | ||
2887 | with a few binaries. | ||
2888 | You can modify the recipe to split the binaries into separate packages: | ||
2889 | <literallayout class='monospaced'> | ||
2890 | require xorg-lib-common.inc | ||
2891 | |||
2892 | SUMMARY = "X11 Pixmap library" | ||
2893 | LICENSE = "X-BSD" | ||
2894 | LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" | ||
2895 | DEPENDS += "libxext libsm libxt" | ||
2896 | PR = "r3" | ||
2897 | PE = "1" | ||
2898 | |||
2899 | XORG_PN = "libXpm" | ||
2900 | |||
2901 | PACKAGES =+ "sxpm cxpm" | ||
2902 | FILES_cxpm = "${bindir}/cxpm" | ||
2903 | FILES_sxpm = "${bindir}/sxpm" | ||
2904 | </literallayout> | ||
2905 | </para> | ||
2906 | |||
2907 | <para> | ||
2908 | In the previous example, we want to ship the <filename>sxpm</filename> | ||
2909 | and <filename>cxpm</filename> binaries in separate packages. | ||
2910 | Since <filename>bindir</filename> would be packaged into the main | ||
2911 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> | ||
2912 | package by default, we prepend the <filename>PACKAGES</filename> | ||
2913 | variable so additional package names are added to the start of list. | ||
2914 | This results in the extra <filename>FILES_*</filename> | ||
2915 | variables then containing information that define which files and | ||
2916 | directories go into which packages. | ||
2917 | Files included by earlier packages are skipped by latter packages. | ||
2918 | Thus, the main <filename>PN</filename> package | ||
2919 | does not include the above listed files. | ||
2920 | </para> | ||
2921 | </section> | ||
2922 | |||
2923 | <section id='packaging-externally-produced-binaries'> | ||
2924 | <title>Packaging Externally Produced Binaries</title> | ||
2925 | |||
2926 | <para> | ||
2927 | Sometimes, you need to add pre-compiled binaries to an | ||
2928 | image. | ||
2929 | For example, suppose that binaries for proprietary code | ||
2930 | exist, which are created by a particular division of a | ||
2931 | company. | ||
2932 | Your part of the company needs to use those binaries as | ||
2933 | part of an image that you are building using the | ||
2934 | OpenEmbedded build system. | ||
2935 | Since you only have the binaries and not the source code, | ||
2936 | you cannot use a typical recipe that expects to fetch the | ||
2937 | source specified in | ||
2938 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
2939 | and then compile it. | ||
2940 | </para> | ||
2941 | |||
2942 | <para> | ||
2943 | One method is to package the binaries and then install them | ||
2944 | as part of the image. | ||
2945 | Generally, it is not a good idea to package binaries | ||
2946 | since, among other things, it can hinder the ability to | ||
2947 | reproduce builds and could lead to compatibility problems | ||
2948 | with ABI in the future. | ||
2949 | However, sometimes you have no choice. | ||
2950 | </para> | ||
2951 | |||
2952 | <para> | ||
2953 | The easiest solution is to create a recipe that uses | ||
2954 | the | ||
2955 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-bin-package'><filename>bin_package</filename></ulink> | ||
2956 | class and to be sure that you are using default locations | ||
2957 | for build artifacts. | ||
2958 | In most cases, the <filename>bin_package</filename> class | ||
2959 | handles "skipping" the configure and compile steps as well | ||
2960 | as sets things up to grab packages from the appropriate | ||
2961 | area. | ||
2962 | In particular, this class sets <filename>noexec</filename> | ||
2963 | on both the | ||
2964 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink> | ||
2965 | and | ||
2966 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> | ||
2967 | tasks, sets | ||
2968 | <filename>FILES_${PN}</filename> to "/" so that it picks | ||
2969 | up all files, and sets up a | ||
2970 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
2971 | task, which effectively copies all files from | ||
2972 | <filename>${S}</filename> to <filename>${D}</filename>. | ||
2973 | The <filename>bin_package</filename> class works well when | ||
2974 | the files extracted into <filename>${S}</filename> are | ||
2975 | already laid out in the way they should be laid out | ||
2976 | on the target. | ||
2977 | For more information on these variables, see the | ||
2978 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>, | ||
2979 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>, | ||
2980 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>, | ||
2981 | and | ||
2982 | <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> | ||
2983 | variables in the Yocto Project Reference Manual's variable | ||
2984 | glossary. | ||
2985 | </para> | ||
2986 | |||
2987 | <para> | ||
2988 | If you can't use the <filename>bin_package</filename> | ||
2989 | class, you need to be sure you are doing the following: | ||
2990 | <itemizedlist> | ||
2991 | <listitem><para>Create a recipe where the | ||
2992 | <filename>do_configure</filename> and | ||
2993 | <filename>do_compile</filename> tasks do nothing: | ||
2994 | <literallayout class='monospaced'> | ||
2995 | do_configure[noexec] = "1" | ||
2996 | do_compile[noexec] = "1" | ||
2997 | </literallayout> | ||
2998 | Alternatively, you can make these tasks an empty | ||
2999 | function. | ||
3000 | </para></listitem> | ||
3001 | <listitem><para>Make sure your | ||
3002 | <filename>do_install</filename> task installs the | ||
3003 | binaries appropriately. | ||
3004 | </para></listitem> | ||
3005 | <listitem><para>Ensure that you set up | ||
3006 | <filename>FILES</filename> (usually | ||
3007 | <filename>FILES_${PN}</filename>) to point to the | ||
3008 | files you have installed, which of course depends | ||
3009 | on where you have installed them and whether | ||
3010 | those files are in different locations than the | ||
3011 | defaults. | ||
3012 | </para></listitem> | ||
3013 | </itemizedlist> | ||
3014 | </para> | ||
3015 | </section> | ||
3016 | </section> | ||
3017 | </section> | ||
3018 | |||
3019 | <section id="platdev-newmachine"> | ||
3020 | <title>Adding a New Machine</title> | ||
3021 | |||
3022 | <para> | ||
3023 | Adding a new machine to the Yocto Project is a straightforward | ||
3024 | process. | ||
3025 | This section describes how to add machines that are similar | ||
3026 | to those that the Yocto Project already supports. | ||
3027 | <note> | ||
3028 | Although well within the capabilities of the Yocto Project, | ||
3029 | adding a totally new architecture might require | ||
3030 | changes to <filename>gcc/glibc</filename> and to the site | ||
3031 | information, which is beyond the scope of this manual. | ||
3032 | </note> | ||
3033 | </para> | ||
3034 | |||
3035 | <para> | ||
3036 | For a complete example that shows how to add a new machine, | ||
3037 | see the | ||
3038 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | ||
3039 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | ||
3040 | </para> | ||
3041 | |||
3042 | <section id="platdev-newmachine-conffile"> | ||
3043 | <title>Adding the Machine Configuration File</title> | ||
3044 | |||
3045 | <para> | ||
3046 | To add a new machine, you need to add a new machine | ||
3047 | configuration file to the layer's | ||
3048 | <filename>conf/machine</filename> directory. | ||
3049 | This configuration file provides details about the device | ||
3050 | you are adding. | ||
3051 | </para> | ||
3052 | |||
3053 | <para> | ||
3054 | The OpenEmbedded build system uses the root name of the | ||
3055 | machine configuration file to reference the new machine. | ||
3056 | For example, given a machine configuration file named | ||
3057 | <filename>crownbay.conf</filename>, the build system | ||
3058 | recognizes the machine as "crownbay". | ||
3059 | </para> | ||
3060 | |||
3061 | <para> | ||
3062 | The most important variables you must set in your machine | ||
3063 | configuration file or include from a lower-level configuration | ||
3064 | file are as follows: | ||
3065 | <itemizedlist> | ||
3066 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename> | ||
3067 | (e.g. "arm")</para></listitem> | ||
3068 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename> | ||
3069 | </para></listitem> | ||
3070 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename> | ||
3071 | (e.g. "apm screen wifi")</para></listitem> | ||
3072 | </itemizedlist> | ||
3073 | </para> | ||
3074 | |||
3075 | <para> | ||
3076 | You might also need these variables: | ||
3077 | <itemizedlist> | ||
3078 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename> | ||
3079 | (e.g. "115200;ttyS0 115200;ttyS1")</para></listitem> | ||
3080 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename> | ||
3081 | (e.g. "zImage")</para></listitem> | ||
3082 | <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename> | ||
3083 | (e.g. "tar.gz jffs2")</para></listitem> | ||
3084 | </itemizedlist> | ||
3085 | </para> | ||
3086 | |||
3087 | <para> | ||
3088 | You can find full details on these variables in the reference | ||
3089 | section. | ||
3090 | You can leverage existing machine <filename>.conf</filename> | ||
3091 | files from <filename>meta-yocto-bsp/conf/machine/</filename>. | ||
3092 | </para> | ||
3093 | </section> | ||
3094 | |||
3095 | <section id="platdev-newmachine-kernel"> | ||
3096 | <title>Adding a Kernel for the Machine</title> | ||
3097 | |||
3098 | <para> | ||
3099 | The OpenEmbedded build system needs to be able to build a kernel | ||
3100 | for the machine. | ||
3101 | You need to either create a new kernel recipe for this machine, | ||
3102 | or extend an existing kernel recipe. | ||
3103 | You can find several kernel recipe examples in the | ||
3104 | Source Directory at | ||
3105 | <filename>meta/recipes-kernel/linux</filename> | ||
3106 | that you can use as references. | ||
3107 | </para> | ||
3108 | |||
3109 | <para> | ||
3110 | If you are creating a new kernel recipe, normal recipe-writing | ||
3111 | rules apply for setting up a | ||
3112 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. | ||
3113 | Thus, you need to specify any necessary patches and set | ||
3114 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> | ||
3115 | to point at the source code. | ||
3116 | You need to create a <filename>do_configure</filename> task that | ||
3117 | configures the unpacked kernel with a | ||
3118 | <filename>defconfig</filename> file. | ||
3119 | You can do this by using a <filename>make defconfig</filename> | ||
3120 | command or, more commonly, by copying in a suitable | ||
3121 | <filename>defconfig</filename> file and then running | ||
3122 | <filename>make oldconfig</filename>. | ||
3123 | By making use of <filename>inherit kernel</filename> and | ||
3124 | potentially some of the <filename>linux-*.inc</filename> files, | ||
3125 | most other functionality is centralized and the defaults of the | ||
3126 | class normally work well. | ||
3127 | </para> | ||
3128 | |||
3129 | <para> | ||
3130 | If you are extending an existing kernel recipe, it is usually | ||
3131 | a matter of adding a suitable <filename>defconfig</filename> | ||
3132 | file. | ||
3133 | The file needs to be added into a location similar to | ||
3134 | <filename>defconfig</filename> files used for other machines | ||
3135 | in a given kernel recipe. | ||
3136 | A possible way to do this is by listing the file in the | ||
3137 | <filename>SRC_URI</filename> and adding the machine to the | ||
3138 | expression in | ||
3139 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>: | ||
3140 | <literallayout class='monospaced'> | ||
3141 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | ||
3142 | </literallayout> | ||
3143 | </para> | ||
3144 | </section> | ||
3145 | |||
3146 | <section id="platdev-newmachine-formfactor"> | ||
3147 | <title>Adding a Formfactor Configuration File</title> | ||
3148 | |||
3149 | <para> | ||
3150 | A formfactor configuration file provides information about the | ||
3151 | target hardware for which the image is being built and information that | ||
3152 | the build system cannot obtain from other sources such as the kernel. | ||
3153 | Some examples of information contained in a formfactor configuration file include | ||
3154 | framebuffer orientation, whether or not the system has a keyboard, | ||
3155 | the positioning of the keyboard in relation to the screen, and | ||
3156 | the screen resolution. | ||
3157 | </para> | ||
3158 | |||
3159 | <para> | ||
3160 | The build system uses reasonable defaults in most cases. | ||
3161 | However, if customization is | ||
3162 | necessary, you need to create a <filename>machconfig</filename> file | ||
3163 | in the <filename>meta/recipes-bsp/formfactor/files</filename> | ||
3164 | directory. | ||
3165 | This directory contains directories for specific machines such as | ||
3166 | <filename>qemuarm</filename> and <filename>qemux86</filename>. | ||
3167 | For information about the settings available and the defaults, see the | ||
3168 | <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the | ||
3169 | same area. | ||
3170 | </para> | ||
3171 | |||
3172 | <para> | ||
3173 | Following is an example for "qemuarm" machine: | ||
3174 | <literallayout class='monospaced'> | ||
3175 | HAVE_TOUCHSCREEN=1 | ||
3176 | HAVE_KEYBOARD=1 | ||
3177 | |||
3178 | DISPLAY_CAN_ROTATE=0 | ||
3179 | DISPLAY_ORIENTATION=0 | ||
3180 | #DISPLAY_WIDTH_PIXELS=640 | ||
3181 | #DISPLAY_HEIGHT_PIXELS=480 | ||
3182 | #DISPLAY_BPP=16 | ||
3183 | DISPLAY_DPI=150 | ||
3184 | DISPLAY_SUBPIXEL_ORDER=vrgb | ||
3185 | </literallayout> | ||
3186 | </para> | ||
3187 | </section> | ||
3188 | </section> | ||
3189 | |||
3190 | <section id="platdev-working-with-libraries"> | ||
3191 | <title>Working With Libraries</title> | ||
3192 | |||
3193 | <para> | ||
3194 | Libraries are an integral part of your system. | ||
3195 | This section describes some common practices you might find | ||
3196 | helpful when working with libraries to build your system: | ||
3197 | <itemizedlist> | ||
3198 | <listitem><para><link linkend='including-static-library-files'>How to include static library files</link> | ||
3199 | </para></listitem> | ||
3200 | <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link> | ||
3201 | </para></listitem> | ||
3202 | <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link> | ||
3203 | </para></listitem> | ||
3204 | </itemizedlist> | ||
3205 | </para> | ||
3206 | |||
3207 | <section id='including-static-library-files'> | ||
3208 | <title>Including Static Library Files</title> | ||
3209 | |||
3210 | <para> | ||
3211 | If you are building a library and the library offers static linking, you can control | ||
3212 | which static library files (<filename>*.a</filename> files) get included in the | ||
3213 | built library. | ||
3214 | </para> | ||
3215 | |||
3216 | <para> | ||
3217 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> | ||
3218 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink> | ||
3219 | variables in the | ||
3220 | <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed | ||
3221 | by the <filename>do_install</filename> task are packaged. | ||
3222 | By default, the <filename>PACKAGES</filename> variable includes | ||
3223 | <filename>${PN}-staticdev</filename>, which represents all static library files. | ||
3224 | <note> | ||
3225 | Some previously released versions of the Yocto Project | ||
3226 | defined the static library files through | ||
3227 | <filename>${PN}-dev</filename>. | ||
3228 | </note> | ||
3229 | Following is part of the BitBake configuration file, where | ||
3230 | you can see how the static library files are defined: | ||
3231 | <literallayout class='monospaced'> | ||
3232 | PACKAGE_BEFORE_PN ?= "" | ||
3233 | PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" | ||
3234 | PACKAGES_DYNAMIC = "^${PN}-locale-.*" | ||
3235 | FILES = "" | ||
3236 | |||
3237 | FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ | ||
3238 | ${sysconfdir} ${sharedstatedir} ${localstatedir} \ | ||
3239 | ${base_bindir}/* ${base_sbindir}/* \ | ||
3240 | ${base_libdir}/*${SOLIBS} \ | ||
3241 | ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \ | ||
3242 | ${datadir}/${BPN} ${libdir}/${BPN}/* \ | ||
3243 | ${datadir}/pixmaps ${datadir}/applications \ | ||
3244 | ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ | ||
3245 | ${libdir}/bonobo/servers" | ||
3246 | |||
3247 | FILES_${PN}-bin = "${bindir}/* ${sbindir}/*" | ||
3248 | |||
3249 | FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ | ||
3250 | ${datadir}/gnome/help" | ||
3251 | SECTION_${PN}-doc = "doc" | ||
3252 | |||
3253 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | ||
3254 | FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ | ||
3255 | ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ | ||
3256 | ${datadir}/aclocal ${base_libdir}/*.o \ | ||
3257 | ${libdir}/${BPN}/*.la ${base_libdir}/*.la" | ||
3258 | SECTION_${PN}-dev = "devel" | ||
3259 | ALLOW_EMPTY_${PN}-dev = "1" | ||
3260 | RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" | ||
3261 | |||
3262 | FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a" | ||
3263 | SECTION_${PN}-staticdev = "devel" | ||
3264 | RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" | ||
3265 | </literallayout> | ||
3266 | </para> | ||
3267 | </section> | ||
3268 | |||
3269 | <section id="combining-multiple-versions-library-files-into-one-image"> | ||
3270 | <title>Combining Multiple Versions of Library Files into One Image</title> | ||
3271 | |||
3272 | <para> | ||
3273 | The build system offers the ability to build libraries with different | ||
3274 | target optimizations or architecture formats and combine these together | ||
3275 | into one system image. | ||
3276 | You can link different binaries in the image | ||
3277 | against the different libraries as needed for specific use cases. | ||
3278 | This feature is called "Multilib." | ||
3279 | </para> | ||
3280 | |||
3281 | <para> | ||
3282 | An example would be where you have most of a system compiled in 32-bit | ||
3283 | mode using 32-bit libraries, but you have something large, like a database | ||
3284 | engine, that needs to be a 64-bit application and uses 64-bit libraries. | ||
3285 | Multilib allows you to get the best of both 32-bit and 64-bit libraries. | ||
3286 | </para> | ||
3287 | |||
3288 | <para> | ||
3289 | While the Multilib feature is most commonly used for 32 and 64-bit differences, | ||
3290 | the approach the build system uses facilitates different target optimizations. | ||
3291 | You could compile some binaries to use one set of libraries and other binaries | ||
3292 | to use a different set of libraries. | ||
3293 | The libraries could differ in architecture, compiler options, or other | ||
3294 | optimizations. | ||
3295 | </para> | ||
3296 | |||
3297 | <para> | ||
3298 | This section overviews the Multilib process only. | ||
3299 | For more details on how to implement Multilib, see the | ||
3300 | <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki | ||
3301 | page. | ||
3302 | </para> | ||
3303 | |||
3304 | <para> | ||
3305 | Aside from this wiki page, several examples exist in the | ||
3306 | <filename>meta-skeleton</filename> layer found in the | ||
3307 | <link linkend='source-directory'>Source Directory</link>: | ||
3308 | <itemizedlist> | ||
3309 | <listitem><para><filename>conf/multilib-example.conf</filename> | ||
3310 | configuration file</para></listitem> | ||
3311 | <listitem><para><filename>conf/multilib-example2.conf</filename> | ||
3312 | configuration file</para></listitem> | ||
3313 | <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename> | ||
3314 | recipe</para></listitem> | ||
3315 | </itemizedlist> | ||
3316 | </para> | ||
3317 | |||
3318 | <section id='preparing-to-use-multilib'> | ||
3319 | <title>Preparing to Use Multilib</title> | ||
3320 | |||
3321 | <para> | ||
3322 | User-specific requirements drive the Multilib feature. | ||
3323 | Consequently, there is no one "out-of-the-box" configuration that likely | ||
3324 | exists to meet your needs. | ||
3325 | </para> | ||
3326 | |||
3327 | <para> | ||
3328 | In order to enable Multilib, you first need to ensure your recipe is | ||
3329 | extended to support multiple libraries. | ||
3330 | Many standard recipes are already extended and support multiple libraries. | ||
3331 | You can check in the <filename>meta/conf/multilib.conf</filename> | ||
3332 | configuration file in the | ||
3333 | <link linkend='source-directory'>Source Directory</link> to see how this is | ||
3334 | done using the | ||
3335 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink> | ||
3336 | variable. | ||
3337 | Eventually, all recipes will be covered and this list will | ||
3338 | not be needed. | ||
3339 | </para> | ||
3340 | |||
3341 | <para> | ||
3342 | For the most part, the Multilib class extension works automatically to | ||
3343 | extend the package name from <filename>${PN}</filename> to | ||
3344 | <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename> | ||
3345 | is the particular multilib (e.g. "lib32-" or "lib64-"). | ||
3346 | Standard variables such as | ||
3347 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, | ||
3348 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, | ||
3349 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>, | ||
3350 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, | ||
3351 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, and | ||
3352 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> | ||
3353 | are automatically extended by the system. | ||
3354 | If you are extending any manual code in the recipe, you can use the | ||
3355 | <filename>${MLPREFIX}</filename> variable to ensure those names are extended | ||
3356 | correctly. | ||
3357 | This automatic extension code resides in <filename>multilib.bbclass</filename>. | ||
3358 | </para> | ||
3359 | </section> | ||
3360 | |||
3361 | <section id='using-multilib'> | ||
3362 | <title>Using Multilib</title> | ||
3363 | |||
3364 | <para> | ||
3365 | After you have set up the recipes, you need to define the actual | ||
3366 | combination of multiple libraries you want to build. | ||
3367 | You accomplish this through your <filename>local.conf</filename> | ||
3368 | configuration file in the | ||
3369 | <link linkend='build-directory'>Build Directory</link>. | ||
3370 | An example configuration would be as follows: | ||
3371 | <literallayout class='monospaced'> | ||
3372 | MACHINE = "qemux86-64" | ||
3373 | require conf/multilib.conf | ||
3374 | MULTILIBS = "multilib:lib32" | ||
3375 | DEFAULTTUNE_virtclass-multilib-lib32 = "x86" | ||
3376 | IMAGE_INSTALL = "lib32-connman" | ||
3377 | </literallayout> | ||
3378 | This example enables an | ||
3379 | additional library named <filename>lib32</filename> alongside the | ||
3380 | normal target packages. | ||
3381 | When combining these "lib32" alternatives, the example uses "x86" for tuning. | ||
3382 | For information on this particular tuning, see | ||
3383 | <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>. | ||
3384 | </para> | ||
3385 | |||
3386 | <para> | ||
3387 | The example then includes <filename>lib32-connman</filename> | ||
3388 | in all the images, which illustrates one method of including a | ||
3389 | multiple library dependency. | ||
3390 | You can use a normal image build to include this dependency, | ||
3391 | for example: | ||
3392 | <literallayout class='monospaced'> | ||
3393 | $ bitbake core-image-sato | ||
3394 | </literallayout> | ||
3395 | You can also build Multilib packages specifically with a command like this: | ||
3396 | <literallayout class='monospaced'> | ||
3397 | $ bitbake lib32-connman | ||
3398 | </literallayout> | ||
3399 | </para> | ||
3400 | </section> | ||
3401 | |||
3402 | <section id='additional-implementation-details'> | ||
3403 | <title>Additional Implementation Details</title> | ||
3404 | |||
3405 | <para> | ||
3406 | Different packaging systems have different levels of native Multilib | ||
3407 | support. | ||
3408 | For the RPM Package Management System, the following implementation details | ||
3409 | exist: | ||
3410 | <itemizedlist> | ||
3411 | <listitem><para>A unique architecture is defined for the Multilib packages, | ||
3412 | along with creating a unique deploy folder under | ||
3413 | <filename>tmp/deploy/rpm</filename> in the | ||
3414 | <link linkend='build-directory'>Build Directory</link>. | ||
3415 | For example, consider <filename>lib32</filename> in a | ||
3416 | <filename>qemux86-64</filename> image. | ||
3417 | The possible architectures in the system are "all", "qemux86_64", | ||
3418 | "lib32_qemux86_64", and "lib32_x86".</para></listitem> | ||
3419 | <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from | ||
3420 | <filename>${PN}</filename> during RPM packaging. | ||
3421 | The naming for a normal RPM package and a Multilib RPM package in a | ||
3422 | <filename>qemux86-64</filename> system resolves to something similar to | ||
3423 | <filename>bash-4.1-r2.x86_64.rpm</filename> and | ||
3424 | <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively. | ||
3425 | </para></listitem> | ||
3426 | <listitem><para>When installing a Multilib image, the RPM backend first | ||
3427 | installs the base image and then installs the Multilib libraries. | ||
3428 | </para></listitem> | ||
3429 | <listitem><para>The build system relies on RPM to resolve the identical files in the | ||
3430 | two (or more) Multilib packages.</para></listitem> | ||
3431 | </itemizedlist> | ||
3432 | </para> | ||
3433 | |||
3434 | <para> | ||
3435 | For the IPK Package Management System, the following implementation details exist: | ||
3436 | <itemizedlist> | ||
3437 | <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from | ||
3438 | <filename>${PN}</filename> during IPK packaging. | ||
3439 | The naming for a normal RPM package and a Multilib IPK package in a | ||
3440 | <filename>qemux86-64</filename> system resolves to something like | ||
3441 | <filename>bash_4.1-r2.x86_64.ipk</filename> and | ||
3442 | <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively. | ||
3443 | </para></listitem> | ||
3444 | <listitem><para>The IPK deploy folder is not modified with | ||
3445 | <filename>${MLPREFIX}</filename> because packages with and without | ||
3446 | the Multilib feature can exist in the same folder due to the | ||
3447 | <filename>${PN}</filename> differences.</para></listitem> | ||
3448 | <listitem><para>IPK defines a sanity check for Multilib installation | ||
3449 | using certain rules for file comparison, overridden, etc. | ||
3450 | </para></listitem> | ||
3451 | </itemizedlist> | ||
3452 | </para> | ||
3453 | </section> | ||
3454 | </section> | ||
3455 | |||
3456 | <section id='installing-multiple-versions-of-the-same-library'> | ||
3457 | <title>Installing Multiple Versions of the Same Library</title> | ||
3458 | |||
3459 | <para> | ||
3460 | Situations can exist where you need to install and use | ||
3461 | multiple versions of the same library on the same system | ||
3462 | at the same time. | ||
3463 | These situations almost always exist when a library API | ||
3464 | changes and you have multiple pieces of software that | ||
3465 | depend on the separate versions of the library. | ||
3466 | To accommodate these situations, you can install multiple | ||
3467 | versions of the same library in parallel on the same system. | ||
3468 | </para> | ||
3469 | |||
3470 | <para> | ||
3471 | The process is straightforward as long as the libraries use | ||
3472 | proper versioning. | ||
3473 | With properly versioned libraries, all you need to do to | ||
3474 | individually specify the libraries is create separate, | ||
3475 | appropriately named recipes where the | ||
3476 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the | ||
3477 | name includes a portion that differentiates each library version | ||
3478 | (e.g.the major part of the version number). | ||
3479 | Thus, instead of having a single recipe that loads one version | ||
3480 | of a library (e.g. <filename>clutter</filename>), you provide | ||
3481 | multiple recipes that result in different versions | ||
3482 | of the libraries you want. | ||
3483 | As an example, the following two recipes would allow the | ||
3484 | two separate versions of the <filename>clutter</filename> | ||
3485 | library to co-exist on the same system: | ||
3486 | <literallayout class='monospaced'> | ||
3487 | clutter-1.6_1.6.20.bb | ||
3488 | clutter-1.8_1.8.4.bb | ||
3489 | </literallayout> | ||
3490 | Additionally, if you have other recipes that depend on a given | ||
3491 | library, you need to use the | ||
3492 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
3493 | variable to create the dependency. | ||
3494 | Continuing with the same example, if you want to have a recipe | ||
3495 | depend on the 1.8 version of the <filename>clutter</filename> | ||
3496 | library, use the following in your recipe: | ||
3497 | <literallayout class='monospaced'> | ||
3498 | DEPENDS = "clutter-1.8" | ||
3499 | </literallayout> | ||
3500 | </para> | ||
3501 | </section> | ||
3502 | </section> | ||
3503 | |||
3504 | <section id='creating-partitioned-images'> | ||
3505 | <title>Creating Partitioned Images</title> | ||
3506 | |||
3507 | <para> | ||
3508 | Creating an image for a particular hardware target using the | ||
3509 | OpenEmbedded build system does not necessarily mean you can boot | ||
3510 | that image as is on your device. | ||
3511 | Physical devices accept and boot images in various ways depending | ||
3512 | on the specifics of the device. | ||
3513 | Usually, information about the hardware can tell you what image | ||
3514 | format the device requires. | ||
3515 | Should your device require multiple partitions on an SD card, flash, | ||
3516 | or an HDD, you can use the OpenEmbedded Image Creator, | ||
3517 | <filename>wic</filename>, to create the properly partitioned image. | ||
3518 | </para> | ||
3519 | |||
3520 | <para> | ||
3521 | The <filename>wic</filename> command generates partitioned images | ||
3522 | from existing OpenEmbedded build artifacts. | ||
3523 | Image generation is driven by partitioning commands contained | ||
3524 | in an Openembedded kickstart file (<filename>.wks</filename>) | ||
3525 | specified either directly on the command line or as one of a | ||
3526 | selection of canned <filename>.wks</filename> files as shown | ||
3527 | with the <filename>wic list images</filename> command in the | ||
3528 | "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>" | ||
3529 | section. | ||
3530 | When applied to a given set of build artifacts, the result is an | ||
3531 | image or set of images that can be directly written onto media and | ||
3532 | used on a particular system. | ||
3533 | </para> | ||
3534 | |||
3535 | <para> | ||
3536 | The <filename>wic</filename> command and the infrastructure | ||
3537 | it is based on is by definition incomplete. | ||
3538 | Its purpose is to allow the generation of customized images, | ||
3539 | and as such was designed to be completely extensible through a | ||
3540 | plugin interface. | ||
3541 | See the | ||
3542 | "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" | ||
3543 | section for information on these plugins. | ||
3544 | </para> | ||
3545 | |||
3546 | <para> | ||
3547 | This section provides some background information on | ||
3548 | <filename>wic</filename>, describes what you need to have in | ||
3549 | place to run the tool, provides instruction on how to use | ||
3550 | <filename>wic</filename>, and provides several examples. | ||
3551 | </para> | ||
3552 | |||
3553 | <section id='wic-background'> | ||
3554 | <title>Background</title> | ||
3555 | |||
3556 | <para> | ||
3557 | This section provides some background on the | ||
3558 | <filename>wic</filename> utility. | ||
3559 | While none of this information is required to use | ||
3560 | <filename>wic</filename>, you might find it interesting. | ||
3561 | <itemizedlist> | ||
3562 | <listitem><para> | ||
3563 | The name "wic" is derived from OpenEmbedded | ||
3564 | Image Creator (oeic). | ||
3565 | The "oe" diphthong in "oeic" was promoted to the | ||
3566 | letter "w", because "oeic" is both difficult to remember and | ||
3567 | pronounce.</para></listitem> | ||
3568 | <listitem><para> | ||
3569 | <filename>wic</filename> is loosely based on the | ||
3570 | Meego Image Creator (<filename>mic</filename>) | ||
3571 | framework. | ||
3572 | The <filename>wic</filename> implementation has been | ||
3573 | heavily modified to make direct use of OpenEmbedded | ||
3574 | build artifacts instead of package installation and | ||
3575 | configuration, which are already incorporated within | ||
3576 | the OpenEmbedded artifacts.</para></listitem> | ||
3577 | <listitem><para> | ||
3578 | <filename>wic</filename> is a completely independent | ||
3579 | standalone utility that initially provides | ||
3580 | easier-to-use and more flexible replacements for a | ||
3581 | couple bits of existing functionality in OE Core's | ||
3582 | <filename>boot-directdisk.bbclass</filename> and | ||
3583 | <filename>mkefidisk.sh</filename> scripts. | ||
3584 | The difference between | ||
3585 | <filename>wic</filename> and those examples is | ||
3586 | that with <filename>wic</filename> the | ||
3587 | functionality of those scripts is implemented | ||
3588 | by a general-purpose partitioning language, which is | ||
3589 | based on Redhat kickstart syntax.</para></listitem> | ||
3590 | </itemizedlist> | ||
3591 | </para> | ||
3592 | </section> | ||
3593 | |||
3594 | <section id='wic-requirements'> | ||
3595 | <title>Requirements</title> | ||
3596 | |||
3597 | <para> | ||
3598 | In order to use the <filename>wic</filename> utility | ||
3599 | with the OpenEmbedded Build system, your system needs | ||
3600 | to meet the following requirements: | ||
3601 | <itemizedlist> | ||
3602 | <listitem><para>The Linux distribution on your | ||
3603 | development host must support the Yocto Project. | ||
3604 | See the | ||
3605 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" | ||
3606 | section in the Yocto Project Reference Manual for this | ||
3607 | list of distributions.</para></listitem> | ||
3608 | <listitem><para> | ||
3609 | The standard system utilities, such as | ||
3610 | <filename>cp</filename>, must be installed on your | ||
3611 | development host system. | ||
3612 | </para></listitem> | ||
3613 | <listitem><para> | ||
3614 | The | ||
3615 | <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink> | ||
3616 | package must be installed on your development host | ||
3617 | system. | ||
3618 | </para></listitem> | ||
3619 | <listitem><para> | ||
3620 | You need to have the build artifacts already | ||
3621 | available, which typically means that you must | ||
3622 | have already created an image using the | ||
3623 | Openembedded build system (e.g. | ||
3624 | <filename>core-image-minimal</filename>). | ||
3625 | While it might seem redundant to generate an image in | ||
3626 | order to create an image using | ||
3627 | <filename>wic</filename>, the current version of | ||
3628 | <filename>wic</filename> requires the artifacts | ||
3629 | in the form generated by the build system. | ||
3630 | </para></listitem> | ||
3631 | <listitem><para> | ||
3632 | You must have sourced one of the build environment | ||
3633 | setup scripts (i.e. | ||
3634 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
3635 | or | ||
3636 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) | ||
3637 | found in the | ||
3638 | <link linkend='build-directory'>Build Directory</link>. | ||
3639 | </para></listitem> | ||
3640 | </itemizedlist> | ||
3641 | </para> | ||
3642 | </section> | ||
3643 | |||
3644 | <section id='wic-getting-help'> | ||
3645 | <title>Getting Help</title> | ||
3646 | |||
3647 | <para> | ||
3648 | You can get general help for the <filename>wic</filename> | ||
3649 | by entering the <filename>wic</filename> command by itself | ||
3650 | or by entering the command with a help argument as follows: | ||
3651 | <literallayout class='monospaced'> | ||
3652 | $ wic -h | ||
3653 | $ wic ‐‐help | ||
3654 | </literallayout> | ||
3655 | </para> | ||
3656 | |||
3657 | <para> | ||
3658 | Currently, <filename>wic</filename> supports two commands: | ||
3659 | <filename>create</filename> and <filename>list</filename>. | ||
3660 | You can get help for these commands as follows: | ||
3661 | <literallayout class='monospaced'> | ||
3662 | $ wic help <replaceable>command</replaceable> | ||
3663 | </literallayout> | ||
3664 | </para> | ||
3665 | |||
3666 | <para> | ||
3667 | You can also get detailed help on a number of topics | ||
3668 | from the help system. | ||
3669 | The output of <filename>wic ‐‐help</filename> | ||
3670 | displays a list of available help | ||
3671 | topics under a "Help topics" heading. | ||
3672 | You can have the help system display the help text for | ||
3673 | a given topic by prefacing the topic with | ||
3674 | <filename>wic help</filename>: | ||
3675 | <literallayout class='monospaced'> | ||
3676 | $ wic help <replaceable>help_topic</replaceable> | ||
3677 | </literallayout> | ||
3678 | </para> | ||
3679 | |||
3680 | <para> | ||
3681 | You can find out more about the images | ||
3682 | <filename>wic</filename> creates using the existing | ||
3683 | kickstart files with the following form of the command: | ||
3684 | <literallayout class='monospaced'> | ||
3685 | $ wic list <replaceable>image</replaceable> help | ||
3686 | </literallayout> | ||
3687 | where <filename><replaceable>image</replaceable></filename> is either | ||
3688 | <filename>directdisk</filename> or | ||
3689 | <filename>mkefidisk</filename>. | ||
3690 | </para> | ||
3691 | </section> | ||
3692 | |||
3693 | <section id='operational-modes'> | ||
3694 | <title>Operational Modes</title> | ||
3695 | |||
3696 | <para> | ||
3697 | You can use <filename>wic</filename> in two different | ||
3698 | modes, depending on how much control you need for | ||
3699 | specifying the Openembedded build artifacts that are | ||
3700 | used for creating the image: Raw and Cooked: | ||
3701 | <itemizedlist> | ||
3702 | <listitem><para><emphasis>Raw Mode:</emphasis> | ||
3703 | You explicitly specify build artifacts through | ||
3704 | command-line arguments.</para></listitem> | ||
3705 | <listitem><para><emphasis>Cooked Mode:</emphasis> | ||
3706 | The current | ||
3707 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
3708 | setting and image name are used to automatically locate | ||
3709 | and provide the build artifacts.</para></listitem> | ||
3710 | </itemizedlist> | ||
3711 | </para> | ||
3712 | |||
3713 | <para> | ||
3714 | Regardless of the mode you use, you need to have the build | ||
3715 | artifacts ready and available. | ||
3716 | Additionally, the environment must be set up using the | ||
3717 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
3718 | or | ||
3719 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> | ||
3720 | script found in the | ||
3721 | <link linkend='build-directory'>Build Directory</link>. | ||
3722 | </para> | ||
3723 | |||
3724 | <section id='raw-mode'> | ||
3725 | <title>Raw Mode</title> | ||
3726 | |||
3727 | <para> | ||
3728 | The general form of the 'wic' command in raw mode is: | ||
3729 | <literallayout class='monospaced'> | ||
3730 | $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] | ||
3731 | |||
3732 | Where: | ||
3733 | |||
3734 | <replaceable>image_name</replaceable>.wks | ||
3735 | An OpenEmbedded kickstart file. You can provide | ||
3736 | your own custom file or use a file from a set of | ||
3737 | existing files as described by further options. | ||
3738 | |||
3739 | -o <replaceable>OUTDIR</replaceable>, ‐‐outdir=<replaceable>OUTDIR</replaceable> | ||
3740 | The name of a directory in which to create image. | ||
3741 | |||
3742 | -i <replaceable>PROPERTIES_FILE</replaceable>, ‐‐infile=<replaceable>PROPERTIES_FILE</replaceable> | ||
3743 | The name of a file containing the values for image | ||
3744 | properties as a JSON file. | ||
3745 | |||
3746 | -e <replaceable>IMAGE_NAME</replaceable>, ‐‐image-name=<replaceable>IMAGE_NAME</replaceable> | ||
3747 | The name of the image from which to use the artifacts | ||
3748 | (e.g. <filename>core-image-sato</filename>). | ||
3749 | |||
3750 | -r <replaceable>ROOTFS_DIR</replaceable>, ‐‐rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> | ||
3751 | The path to the <filename>/rootfs</filename> directory to use as the | ||
3752 | <filename>.wks</filename> rootfs source. | ||
3753 | |||
3754 | -b <replaceable>BOOTIMG_DIR</replaceable>, ‐‐bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> | ||
3755 | The path to the directory containing the boot artifacts | ||
3756 | (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg | ||
3757 | source. | ||
3758 | |||
3759 | -k <replaceable>KERNEL_DIR</replaceable>, ‐‐kernel-dir=<replaceable>KERNEL_DIR</replaceable> | ||
3760 | The path to the directory containing the kernel to use | ||
3761 | in the <filename>.wks</filename> boot image. | ||
3762 | |||
3763 | -n <replaceable>NATIVE_SYSROOT</replaceable>, ‐‐native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> | ||
3764 | The path to the native sysroot containing the tools to use | ||
3765 | to build the image. | ||
3766 | |||
3767 | -s, ‐‐skip-build-check | ||
3768 | Skips the build check. | ||
3769 | |||
3770 | -D, ‐‐debug | ||
3771 | Output debug information. | ||
3772 | </literallayout> | ||
3773 | <note> | ||
3774 | You do not need root privileges to run | ||
3775 | <filename>wic</filename>. | ||
3776 | In fact, you should not run as root when using the | ||
3777 | utility. | ||
3778 | </note> | ||
3779 | </para> | ||
3780 | </section> | ||
3781 | |||
3782 | <section id='cooked-mode'> | ||
3783 | <title>Cooked Mode</title> | ||
3784 | |||
3785 | <para> | ||
3786 | The general form of the <filename>wic</filename> command | ||
3787 | using Cooked Mode is: | ||
3788 | <literallayout class='monospaced'> | ||
3789 | $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> | ||
3790 | |||
3791 | Where: | ||
3792 | |||
3793 | <replaceable>kickstart_file</replaceable> | ||
3794 | An OpenEmbedded kickstart file. You can provide your own | ||
3795 | custom file or supplied file. | ||
3796 | |||
3797 | <replaceable>image_name</replaceable> | ||
3798 | Specifies the image built using the OpenEmbedded build | ||
3799 | system. | ||
3800 | </literallayout> | ||
3801 | This form is the simplest and most user-friendly, as it | ||
3802 | does not require specifying all individual parameters. | ||
3803 | All you need to provide is your own | ||
3804 | <filename>.wks</filename> file or one provided with the | ||
3805 | release. | ||
3806 | </para> | ||
3807 | </section> | ||
3808 | </section> | ||
3809 | |||
3810 | <section id='using-a-provided-kickstart_file'> | ||
3811 | <title>Using an Existing Kickstart File</title> | ||
3812 | |||
3813 | <para> | ||
3814 | If you do not want to create your own | ||
3815 | <filename>.wks</filename> file, you can use an existing | ||
3816 | file provided by the <filename>wic</filename> installation. | ||
3817 | Use the following command to list the available files: | ||
3818 | <literallayout class='monospaced'> | ||
3819 | $ wic list images | ||
3820 | directdisk Create a 'pcbios' direct disk image | ||
3821 | mkefidisk Create an EFI disk image | ||
3822 | </literallayout> | ||
3823 | When you use an existing file, you do not have to use the | ||
3824 | <filename>.wks</filename> extension. | ||
3825 | Here is an example in Raw Mode that uses the | ||
3826 | <filename>directdisk</filename> file: | ||
3827 | <literallayout class='monospaced'> | ||
3828 | $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ | ||
3829 | -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> | ||
3830 | </literallayout> | ||
3831 | </para> | ||
3832 | |||
3833 | <para> | ||
3834 | Here are the actual partition language commands | ||
3835 | used in the <filename>mkefidisk.wks</filename> file to generate | ||
3836 | an image: | ||
3837 | <literallayout class='monospaced'> | ||
3838 | # short-description: Create an EFI disk image | ||
3839 | # long-description: Creates a partitioned EFI disk image that the user | ||
3840 | # can directly dd to boot media. | ||
3841 | |||
3842 | part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024 | ||
3843 | |||
3844 | part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 | ||
3845 | |||
3846 | part swap --ondisk sda --size 44 --label swap1 --fstype=swap | ||
3847 | |||
3848 | bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" | ||
3849 | </literallayout> | ||
3850 | </para> | ||
3851 | </section> | ||
3852 | |||
3853 | <section id='wic-usage-examples'> | ||
3854 | <title>Examples</title> | ||
3855 | |||
3856 | <para> | ||
3857 | This section provides several examples that show how to use | ||
3858 | the <filename>wic</filename> utility. | ||
3859 | All the examples assume the list of requirements in the | ||
3860 | "<link linkend='wic-requirements'>Requirements</link>" section | ||
3861 | have been met. | ||
3862 | The examples assume the previously generated image is | ||
3863 | <filename>core-image-minimal</filename>. | ||
3864 | </para> | ||
3865 | |||
3866 | <section id='generate-an-image-using-a-provided-kickstart-file'> | ||
3867 | <title>Generate an Image using an Existing Kickstart File</title> | ||
3868 | |||
3869 | <para> | ||
3870 | This example runs in Cooked Mode and uses the | ||
3871 | <filename>mkefidisk</filename> kickstart file: | ||
3872 | <literallayout class='monospaced'> | ||
3873 | $ wic create mkefidisk -e core-image-minimal | ||
3874 | Checking basic build environment... | ||
3875 | Done. | ||
3876 | |||
3877 | Creating image(s)... | ||
3878 | |||
3879 | Info: The new image(s) can be found here: | ||
3880 | /var/tmp/wic/build/mkefidisk-201310230946-sda.direct | ||
3881 | |||
3882 | The following build artifacts were used to create the image(s): | ||
3883 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
3884 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg | ||
3885 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel | ||
3886 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
3887 | |||
3888 | |||
3889 | The image(s) were created using OE kickstart file: | ||
3890 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks | ||
3891 | </literallayout> | ||
3892 | This example shows the easiest way to create an image | ||
3893 | by running in Cooked Mode and using the | ||
3894 | <filename>-e</filename> option with an existing kickstart | ||
3895 | file. | ||
3896 | All that is necessary is to specify the image used to | ||
3897 | generate the artifacts. | ||
3898 | Your <filename>local.conf</filename> needs to have the | ||
3899 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
3900 | variable set to the machine you are using, which is | ||
3901 | "minnow" in this example. | ||
3902 | </para> | ||
3903 | |||
3904 | <para> | ||
3905 | The output specifies the exact created as well as where | ||
3906 | it was created. | ||
3907 | The output also names the artifacts used and the exact | ||
3908 | <filename>.wks</filename> script that was used to generate | ||
3909 | the image. | ||
3910 | <note> | ||
3911 | You should always verify the details provided in the | ||
3912 | output to make sure that the image was indeed created | ||
3913 | exactly as expected. | ||
3914 | </note> | ||
3915 | </para> | ||
3916 | |||
3917 | <para> | ||
3918 | Continuing with the example, you can now directly | ||
3919 | <filename>dd</filename> the image to a USB stick, or | ||
3920 | whatever media for which you built your image, | ||
3921 | and boot the resulting media: | ||
3922 | <literallayout class='monospaced'> | ||
3923 | $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb | ||
3924 | [sudo] password for trz: | ||
3925 | 182274+0 records in | ||
3926 | 182274+0 records out | ||
3927 | 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s | ||
3928 | [trz@empanada ~]$ sudo eject /dev/sdb | ||
3929 | </literallayout> | ||
3930 | </para> | ||
3931 | </section> | ||
3932 | |||
3933 | <section id='using-a-modified-kickstart-file'> | ||
3934 | <title>Using a Modified Kickstart File</title> | ||
3935 | |||
3936 | <para> | ||
3937 | Because <filename>wic</filename> image creation is driven | ||
3938 | by the kickstart file, it is easy to affect image creation | ||
3939 | by changing the parameters in the file. | ||
3940 | This next example demonstrates that through modification | ||
3941 | of the <filename>directdisk</filename> kickstart file. | ||
3942 | </para> | ||
3943 | |||
3944 | <para> | ||
3945 | As mentioned earlier, you can use the command | ||
3946 | <filename>wic list images</filename> to show the list | ||
3947 | of existing kickstart files. | ||
3948 | The directory in which these files reside is | ||
3949 | <filename>scripts/lib/image/canned-wks/</filename> | ||
3950 | located in the | ||
3951 | <link linkend='source-directory'>Source Directory</link>. | ||
3952 | Because the available files reside in this directory, you | ||
3953 | can create and add your own custom files to the directory. | ||
3954 | Subsequent use of the <filename>wic list images</filename> | ||
3955 | command would then include your kickstart files. | ||
3956 | </para> | ||
3957 | |||
3958 | <para> | ||
3959 | In this example, the existing | ||
3960 | <filename>directdisk</filename> file already does most | ||
3961 | of what is needed. | ||
3962 | However, for the hardware in this example, the image will | ||
3963 | need to boot from <filename>sdb</filename> instead of | ||
3964 | <filename>sda</filename>, which is what the | ||
3965 | <filename>directdisk</filename> kickstart file uses. | ||
3966 | </para> | ||
3967 | |||
3968 | <para> | ||
3969 | The example begins by making a copy of the | ||
3970 | <filename>directdisk.wks</filename> file in the | ||
3971 | <filename>scripts/lib/image/canned-wks</filename> | ||
3972 | directory and then changing the lines that specify the | ||
3973 | target disk from which to boot. | ||
3974 | <literallayout class='monospaced'> | ||
3975 | $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ | ||
3976 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks | ||
3977 | </literallayout> | ||
3978 | Next, the example modifies the | ||
3979 | <filename>directdisksdb.wks</filename> file and changes all | ||
3980 | instances of "<filename>‐‐ondisk sda</filename>" | ||
3981 | to "<filename>‐‐ondisk sdb</filename>". | ||
3982 | The example changes the following two lines and leaves the | ||
3983 | remaining lines untouched: | ||
3984 | <literallayout class='monospaced'> | ||
3985 | part /boot ‐‐source bootimg-pcbios ‐‐ondisk sdb ‐‐label boot ‐‐active ‐‐align 1024 | ||
3986 | part / ‐‐source rootfs ‐‐ondisk sdb ‐‐fstype=ext3 ‐‐label platform ‐‐align 1024 | ||
3987 | </literallayout> | ||
3988 | Once the lines are changed, the example generates the | ||
3989 | <filename>directdisksdb</filename> image. | ||
3990 | The command points the process at the | ||
3991 | <filename>core-image-minimal</filename> artifacts for the | ||
3992 | Next Unit of Computing (nuc) | ||
3993 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
3994 | the <filename>local.conf</filename>. | ||
3995 | <literallayout class='monospaced'> | ||
3996 | $ wic create directdisksdb -e core-image-minimal | ||
3997 | Checking basic build environment... | ||
3998 | Done. | ||
3999 | |||
4000 | Creating image(s)... | ||
4001 | |||
4002 | Info: The new image(s) can be found here: | ||
4003 | /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct | ||
4004 | |||
4005 | The following build artifacts were used to create the image(s): | ||
4006 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
4007 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share | ||
4008 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel | ||
4009 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
4010 | |||
4011 | |||
4012 | The image(s) were created using OE kickstart file: | ||
4013 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks | ||
4014 | </literallayout> | ||
4015 | Continuing with the example, you can now directly | ||
4016 | <filename>dd</filename> the image to a USB stick, or | ||
4017 | whatever media for which you built your image, | ||
4018 | and boot the resulting media: | ||
4019 | <literallayout class='monospaced'> | ||
4020 | $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb | ||
4021 | 86018+0 records in | ||
4022 | 86018+0 records out | ||
4023 | 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s | ||
4024 | [trz@empanada tmp]$ sudo eject /dev/sdb | ||
4025 | </literallayout> | ||
4026 | </para> | ||
4027 | </section> | ||
4028 | |||
4029 | <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> | ||
4030 | <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> | ||
4031 | |||
4032 | <para> | ||
4033 | This example creates an image based on | ||
4034 | <filename>core-image-minimal</filename> and a | ||
4035 | <filename>crownbay-noemgd</filename> | ||
4036 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
4037 | that works right out of the box. | ||
4038 | <literallayout class='monospaced'> | ||
4039 | $ wic create directdisk -e core-image-minimal | ||
4040 | |||
4041 | Checking basic build environment... | ||
4042 | Done. | ||
4043 | |||
4044 | Creating image(s)... | ||
4045 | |||
4046 | Info: The new image(s) can be found here: | ||
4047 | /var/tmp/wic/build/directdisk-201309252350-sda.direct | ||
4048 | |||
4049 | The following build artifacts were used to create the image(s): | ||
4050 | |||
4051 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
4052 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share | ||
4053 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
4054 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
4055 | |||
4056 | The image(s) were created using OE kickstart file: | ||
4057 | /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks | ||
4058 | </literallayout> | ||
4059 | </para> | ||
4060 | </section> | ||
4061 | |||
4062 | <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> | ||
4063 | <title>Using a Modified Kickstart File and Running in Raw Mode</title> | ||
4064 | |||
4065 | <para> | ||
4066 | This next example manually specifies each build artifact | ||
4067 | (runs in Raw Mode) and uses a modified kickstart file. | ||
4068 | The example also uses the <filename>-o</filename> option | ||
4069 | to cause <filename>wic</filename> to create the output | ||
4070 | somewhere other than the default | ||
4071 | <filename>/var/tmp/wic</filename> directory: | ||
4072 | <literallayout class='monospaced'> | ||
4073 | $ wic create ~/test.wks -o /home/trz/testwic ‐‐rootfs-dir \ | ||
4074 | /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ | ||
4075 | ‐‐bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ | ||
4076 | ‐‐kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ | ||
4077 | ‐‐native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux | ||
4078 | |||
4079 | Creating image(s)... | ||
4080 | |||
4081 | Info: The new image(s) can be found here: | ||
4082 | /home/trz/testwic/build/test-201309260032-sda.direct | ||
4083 | |||
4084 | The following build artifacts were used to create the image(s): | ||
4085 | |||
4086 | ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs | ||
4087 | BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share | ||
4088 | KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
4089 | NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel | ||
4090 | |||
4091 | The image(s) were created using OE kickstart file: | ||
4092 | /home/trz/test.wks | ||
4093 | </literallayout> | ||
4094 | For this example, | ||
4095 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
4096 | did not have to be specified in the | ||
4097 | <filename>local.conf</filename> file since the artifact is | ||
4098 | manually specified. | ||
4099 | </para> | ||
4100 | </section> | ||
4101 | </section> | ||
4102 | |||
4103 | <section id='openembedded-kickstart-plugins'> | ||
4104 | <title>Plugins</title> | ||
4105 | |||
4106 | <para> | ||
4107 | Plugins allow <filename>wic</filename> functionality to | ||
4108 | be extended and specialized by users. | ||
4109 | This section documents the plugin interface, which is | ||
4110 | currently restricted to source plugins. | ||
4111 | </para> | ||
4112 | |||
4113 | <para> | ||
4114 | Source plugins provide a mechanism to customize | ||
4115 | various aspects of the image generation process in | ||
4116 | <filename>wic</filename>, mainly the contents of | ||
4117 | partitions. | ||
4118 | The plugins provide a mechanism for mapping values | ||
4119 | specified in <filename>.wks</filename> files using the | ||
4120 | <filename>‐‐source</filename> keyword to a | ||
4121 | particular plugin implementation that populates a | ||
4122 | corresponding partition. | ||
4123 | </para> | ||
4124 | |||
4125 | <para> | ||
4126 | A source plugin is created as a subclass of | ||
4127 | <filename>SourcePlugin</filename>. | ||
4128 | The plugin file containing it is added to | ||
4129 | <filename>scripts/lib/mic/plugins/source/</filename> to | ||
4130 | make the plugin implementation available to the | ||
4131 | <filename>wic</filename> implementation. | ||
4132 | For more information, see | ||
4133 | <filename>scripts/lib/mic/pluginbase.py</filename>. | ||
4134 | </para> | ||
4135 | |||
4136 | <para> | ||
4137 | Source plugins can also be implemented and added by | ||
4138 | external layers. | ||
4139 | As such, any plugins found in a | ||
4140 | <filename>scripts/lib/mic/plugins/source/</filename> | ||
4141 | directory in an external layer are also made | ||
4142 | available. | ||
4143 | </para> | ||
4144 | |||
4145 | <para> | ||
4146 | When the <filename>wic</filename> implementation needs | ||
4147 | to invoke a partition-specific implementation, it looks | ||
4148 | for the plugin that has the same name as the | ||
4149 | <filename>‐‐source</filename> parameter given to | ||
4150 | that partition. | ||
4151 | For example, if the partition is set up as follows: | ||
4152 | <literallayout class='monospaced'> | ||
4153 | part /boot ‐‐source bootimg-pcbios ... | ||
4154 | </literallayout> | ||
4155 | The methods defined as class members of the plugin | ||
4156 | having the matching <filename>bootimg-pcbios.name</filename> | ||
4157 | class member are used. | ||
4158 | </para> | ||
4159 | |||
4160 | <para> | ||
4161 | To be more concrete, here is the plugin definition that | ||
4162 | matches a | ||
4163 | <filename>‐‐source bootimg-pcbios</filename> usage, | ||
4164 | along with an example | ||
4165 | method called by the <filename>wic</filename> implementation | ||
4166 | when it needs to invoke an implementation-specific | ||
4167 | partition-preparation function: | ||
4168 | <literallayout class='monospaced'> | ||
4169 | class BootimgPcbiosPlugin(SourcePlugin): | ||
4170 | name = 'bootimg-pcbios' | ||
4171 | |||
4172 | @classmethod | ||
4173 | def do_prepare_partition(self, part, ...) | ||
4174 | </literallayout> | ||
4175 | If the subclass itself does not implement a function, a | ||
4176 | default version in a superclass is located and | ||
4177 | used, which is why all plugins must be derived from | ||
4178 | <filename>SourcePlugin</filename>. | ||
4179 | </para> | ||
4180 | |||
4181 | <para> | ||
4182 | The <filename>SourcePlugin</filename> class defines the | ||
4183 | following methods, which is the current set of methods | ||
4184 | that can be implemented or overridden by | ||
4185 | <filename>‐‐source</filename> plugins. | ||
4186 | Any methods not implemented by a | ||
4187 | <filename>SourcePlugin</filename> subclass inherit the | ||
4188 | implementations present in the | ||
4189 | <filename>SourcePlugin</filename> class. | ||
4190 | For more information, see the | ||
4191 | <filename>SourcePlugin</filename> source for details: | ||
4192 | </para> | ||
4193 | |||
4194 | <para> | ||
4195 | <itemizedlist> | ||
4196 | <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis> | ||
4197 | Called to do the actual content population for a | ||
4198 | partition. | ||
4199 | In other words, the method prepares the final | ||
4200 | partition image that is incorporated into the | ||
4201 | disk image. | ||
4202 | </para></listitem> | ||
4203 | <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis> | ||
4204 | Called before | ||
4205 | <filename>do_prepare_partition()</filename>. | ||
4206 | This method is typically used to create custom | ||
4207 | configuration files for a partition (e.g. syslinux or | ||
4208 | grub configuration files). | ||
4209 | </para></listitem> | ||
4210 | <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis> | ||
4211 | Called after all partitions have been prepared and | ||
4212 | assembled into a disk image. | ||
4213 | This method provides a hook to allow finalization of a | ||
4214 | disk image, (e.g. writing an MBR). | ||
4215 | </para></listitem> | ||
4216 | <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis> | ||
4217 | Special content-staging hook called before | ||
4218 | <filename>do_prepare_partition()</filename>. | ||
4219 | This method is normally empty.</para> | ||
4220 | <para>Typically, a partition just uses the passed-in | ||
4221 | parameters (e.g. the unmodified value of | ||
4222 | <filename>bootimg_dir</filename>). | ||
4223 | However, in some cases things might need to be | ||
4224 | more tailored. | ||
4225 | As an example, certain files might additionally | ||
4226 | need to be taken from | ||
4227 | <filename>bootimg_dir + /boot</filename>. | ||
4228 | This hook allows those files to be staged in a | ||
4229 | customized fashion. | ||
4230 | <note> | ||
4231 | <filename>get_bitbake_var()</filename> | ||
4232 | allows you to access non-standard variables | ||
4233 | that you might want to use for this. | ||
4234 | </note> | ||
4235 | </para></listitem> | ||
4236 | </itemizedlist> | ||
4237 | </para> | ||
4238 | |||
4239 | <para> | ||
4240 | This scheme is extensible. | ||
4241 | Adding more hooks is a simple matter of adding more | ||
4242 | plugin methods to <filename>SourcePlugin</filename> and | ||
4243 | derived classes. | ||
4244 | The code that then needs to call the plugin methods uses | ||
4245 | <filename>plugin.get_source_plugin_methods()</filename> | ||
4246 | to find the method or methods needed by the call. | ||
4247 | Retrieval of those methods is accomplished | ||
4248 | by filling up a dict with keys | ||
4249 | containing the method names of interest. | ||
4250 | On success, these will be filled in with the actual | ||
4251 | methods. | ||
4252 | Please see the <filename>wic</filename> | ||
4253 | implementation for examples and details. | ||
4254 | </para> | ||
4255 | </section> | ||
4256 | |||
4257 | <section id='openembedded-kickstart-wks-reference'> | ||
4258 | <title>OpenEmbedded Kickstart (.wks) Reference</title> | ||
4259 | |||
4260 | <para> | ||
4261 | The current <filename>wic</filename> implementation supports | ||
4262 | only the basic kickstart partitioning commands: | ||
4263 | <filename>partition</filename> (or <filename>part</filename> | ||
4264 | for short) and <filename>bootloader</filename>. | ||
4265 | <note> | ||
4266 | Future updates will implement more commands and options. | ||
4267 | If you use anything that is not specifically | ||
4268 | supported, results can be unpredictable. | ||
4269 | </note> | ||
4270 | </para> | ||
4271 | |||
4272 | <para> | ||
4273 | The following is a list of the commands, their syntax, | ||
4274 | and meanings. | ||
4275 | The commands are based on the Fedora | ||
4276 | kickstart versions but with modifications to | ||
4277 | reflect <filename>wic</filename> capabilities. | ||
4278 | You can see the original documentation for those commands | ||
4279 | at the following links: | ||
4280 | <itemizedlist> | ||
4281 | <listitem><para> | ||
4282 | <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink> | ||
4283 | </para></listitem> | ||
4284 | <listitem><para> | ||
4285 | <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink> | ||
4286 | </para></listitem> | ||
4287 | </itemizedlist> | ||
4288 | </para> | ||
4289 | |||
4290 | <section id='command-part-or-partition'> | ||
4291 | <title>Command: part or partition</title> | ||
4292 | |||
4293 | <para> | ||
4294 | This command creates a partition on the system and uses the | ||
4295 | following syntax: | ||
4296 | <literallayout class='monospaced'> | ||
4297 | part <replaceable>mntpoint</replaceable> | ||
4298 | </literallayout> | ||
4299 | The <filename><replaceable>mntpoint</replaceable></filename> | ||
4300 | is where the | ||
4301 | partition will be mounted and must be of one of the | ||
4302 | following forms: | ||
4303 | <itemizedlist> | ||
4304 | <listitem><para><filename>/<replaceable>path</replaceable></filename>: | ||
4305 | For example, <filename>/</filename>, | ||
4306 | <filename>/usr</filename>, and | ||
4307 | <filename>/home</filename></para></listitem> | ||
4308 | <listitem><para><filename>swap</filename>: | ||
4309 | The partition will be used as swap space. | ||
4310 | </para></listitem> | ||
4311 | </itemizedlist> | ||
4312 | </para> | ||
4313 | |||
4314 | <para> | ||
4315 | Following are the supported options: | ||
4316 | <itemizedlist> | ||
4317 | <listitem><para><emphasis><filename>‐‐size</filename>:</emphasis> | ||
4318 | The minimum partition size in MBytes. | ||
4319 | Specify an integer value such as 500. | ||
4320 | Do not append the number with "MB". | ||
4321 | You do not need this option if you use | ||
4322 | <filename>‐‐source</filename>.</para></listitem> | ||
4323 | <listitem><para><emphasis><filename>‐‐source</filename>:</emphasis> | ||
4324 | This option is a | ||
4325 | <filename>wic</filename>-specific option that | ||
4326 | names the source of the data that populates | ||
4327 | the partition. | ||
4328 | The most common value for this option is | ||
4329 | "rootfs", but you can use any value that maps to | ||
4330 | a valid source plugin. | ||
4331 | For information on the source plugins, see the | ||
4332 | "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" | ||
4333 | section.</para> | ||
4334 | <para>If you use | ||
4335 | <filename>‐‐source rootfs</filename>, | ||
4336 | <filename>wic</filename> creates a partition as | ||
4337 | large as needed and to fill it with the contents of | ||
4338 | the root filesystem pointed to by the | ||
4339 | <filename>-r</filename> command-line option | ||
4340 | or the equivalent rootfs derived from the | ||
4341 | <filename>-e</filename> command-line | ||
4342 | option. | ||
4343 | The filesystem type used to create the | ||
4344 | partition is driven by the value of the | ||
4345 | <filename>‐‐fstype</filename> option | ||
4346 | specified for the partition. | ||
4347 | See the entry on | ||
4348 | <filename>‐‐fstype</filename> that | ||
4349 | follows for more information. | ||
4350 | </para> | ||
4351 | <para>If you use | ||
4352 | <filename>‐‐source <replaceable>plugin-name</replaceable></filename>, | ||
4353 | <filename>wic</filename> creates a partition as | ||
4354 | large as needed and fills it with the contents of | ||
4355 | the partition that is generated by the | ||
4356 | specified plugin name using the data pointed | ||
4357 | to by the <filename>-r</filename> command-line | ||
4358 | option or the equivalent rootfs derived from the | ||
4359 | <filename>-e</filename> command-line | ||
4360 | option. | ||
4361 | Exactly what those contents and | ||
4362 | filesystem type end up being are dependent | ||
4363 | on the given plugin implementation. | ||
4364 | </para></listitem> | ||
4365 | <listitem><para><emphasis><filename>‐‐ondisk</filename> or <filename>‐‐ondrive</filename>:</emphasis> | ||
4366 | Forces the partition to be created on a particular | ||
4367 | disk.</para></listitem> | ||
4368 | <listitem><para><emphasis><filename>‐‐fstype</filename>:</emphasis> | ||
4369 | Sets the file system type for the partition. | ||
4370 | Valid values are: | ||
4371 | <itemizedlist> | ||
4372 | <listitem><para><filename>ext4</filename> | ||
4373 | </para></listitem> | ||
4374 | <listitem><para><filename>ext3</filename> | ||
4375 | </para></listitem> | ||
4376 | <listitem><para><filename>ext2</filename> | ||
4377 | </para></listitem> | ||
4378 | <listitem><para><filename>btrfs</filename> | ||
4379 | </para></listitem> | ||
4380 | <listitem><para><filename>squashfs</filename> | ||
4381 | </para></listitem> | ||
4382 | <listitem><para><filename>swap</filename> | ||
4383 | </para></listitem> | ||
4384 | </itemizedlist></para></listitem> | ||
4385 | <listitem><para><emphasis><filename>‐‐fsoptions</filename>:</emphasis> | ||
4386 | Specifies a free-form string of options to be | ||
4387 | used when mounting the filesystem. | ||
4388 | This string will be copied into the | ||
4389 | <filename>/etc/fstab</filename> file of the | ||
4390 | installed system and should be enclosed in | ||
4391 | quotes. | ||
4392 | If not specified, the default string | ||
4393 | is "defaults". | ||
4394 | </para></listitem> | ||
4395 | <listitem><para><emphasis><filename>‐‐label label</filename>:</emphasis> | ||
4396 | Specifies the label to give to the filesystem to | ||
4397 | be made on the partition. | ||
4398 | If the given label is already in use by another | ||
4399 | filesystem, a new label is created for the | ||
4400 | partition.</para></listitem> | ||
4401 | <listitem><para><emphasis><filename>‐‐active</filename>:</emphasis> | ||
4402 | Marks the partition as active.</para></listitem> | ||
4403 | <listitem><para><emphasis><filename>‐‐align (in KBytes)</filename>:</emphasis> | ||
4404 | This option is a <filename>wic</filename>-specific | ||
4405 | option that says to start a partition on an | ||
4406 | x KBytes boundary.</para></listitem> | ||
4407 | </itemizedlist> | ||
4408 | </para> | ||
4409 | </section> | ||
4410 | |||
4411 | <section id='command-bootloader'> | ||
4412 | <title>Command: bootloader</title> | ||
4413 | |||
4414 | <para> | ||
4415 | This command specifies how the boot loader should be | ||
4416 | configured and supports the following options: | ||
4417 | <note> | ||
4418 | Bootloader functionality and boot partitions are | ||
4419 | implemented by the various | ||
4420 | <filename>‐‐source</filename> | ||
4421 | plugins that implement bootloader functionality. | ||
4422 | The bootloader command essentially provides a means of | ||
4423 | modifying bootloader configuration. | ||
4424 | </note> | ||
4425 | <itemizedlist> | ||
4426 | <listitem><para><emphasis><filename>‐‐timeout</filename>:</emphasis> | ||
4427 | Specifies the number of seconds before the | ||
4428 | bootloader times out and boots the default option. | ||
4429 | </para></listitem> | ||
4430 | <listitem><para><emphasis><filename>‐‐append</filename>:</emphasis> | ||
4431 | Specifies kernel parameters. | ||
4432 | These parameters will be added to the syslinux | ||
4433 | <filename>APPEND</filename> or | ||
4434 | <filename>grub</filename> kernel command line. | ||
4435 | </para></listitem> | ||
4436 | </itemizedlist> | ||
4437 | </para> | ||
4438 | </section> | ||
4439 | </section> | ||
4440 | </section> | ||
4441 | |||
4442 | <section id='configuring-the-kernel'> | ||
4443 | <title>Configuring the Kernel</title> | ||
4444 | |||
4445 | <para> | ||
4446 | Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename> | ||
4447 | file has all the right information in it for the image you are building. | ||
4448 | You can use the <filename>menuconfig</filename> tool and configuration fragments to | ||
4449 | make sure your <filename>.config</filename> file is just how you need it. | ||
4450 | This section describes how to use <filename>menuconfig</filename>, create and use | ||
4451 | configuration fragments, and how to interactively modify your <filename>.config</filename> | ||
4452 | file to create the leanest kernel configuration file possible. | ||
4453 | </para> | ||
4454 | |||
4455 | <para> | ||
4456 | For more information on kernel configuration, see the | ||
4457 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>" | ||
4458 | section in the Yocto Project Linux Kernel Development Manual. | ||
4459 | </para> | ||
4460 | |||
4461 | <section id='using-menuconfig'> | ||
4462 | <title>Using <filename>menuconfig</filename></title> | ||
4463 | |||
4464 | <para> | ||
4465 | The easiest way to define kernel configurations is to set them through the | ||
4466 | <filename>menuconfig</filename> tool. | ||
4467 | This tool provides an interactive method with which | ||
4468 | to set kernel configurations. | ||
4469 | For general information on <filename>menuconfig</filename>, see | ||
4470 | <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. | ||
4471 | </para> | ||
4472 | |||
4473 | <para> | ||
4474 | To use the <filename>menuconfig</filename> tool in the Yocto Project development | ||
4475 | environment, you must launch it using BitBake. | ||
4476 | Thus, the environment must be set up using the | ||
4477 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
4478 | or | ||
4479 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> | ||
4480 | script found in the | ||
4481 | <link linkend='build-directory'>Build Directory</link>. | ||
4482 | The following commands run <filename>menuconfig</filename> assuming the | ||
4483 | <link linkend='source-directory'>Source Directory</link> | ||
4484 | top-level folder is <filename>~/poky</filename>: | ||
4485 | <literallayout class='monospaced'> | ||
4486 | $ cd poky | ||
4487 | $ source oe-init-build-env | ||
4488 | $ bitbake linux-yocto -c menuconfig | ||
4489 | </literallayout> | ||
4490 | Once <filename>menuconfig</filename> comes up, its standard interface allows you to | ||
4491 | interactively examine and configure all the kernel configuration parameters. | ||
4492 | After making your changes, simply exit the tool and save your changes to | ||
4493 | create an updated version of the <filename>.config</filename> configuration file. | ||
4494 | </para> | ||
4495 | |||
4496 | <para> | ||
4497 | Consider an example that configures the <filename>linux-yocto-3.14</filename> | ||
4498 | kernel. | ||
4499 | The OpenEmbedded build system recognizes this kernel as | ||
4500 | <filename>linux-yocto</filename>. | ||
4501 | Thus, the following commands from the shell in which you previously sourced the | ||
4502 | environment initialization script cleans the shared state cache and the | ||
4503 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> | ||
4504 | directory and then runs <filename>menuconfig</filename>: | ||
4505 | <literallayout class='monospaced'> | ||
4506 | $ bitbake linux-yocto -c menuconfig | ||
4507 | </literallayout> | ||
4508 | </para> | ||
4509 | |||
4510 | <para> | ||
4511 | Once <filename>menuconfig</filename> launches, use the interface | ||
4512 | to navigate through the selections to find the configuration settings in | ||
4513 | which you are interested. | ||
4514 | For example, consider the <filename>CONFIG_SMP</filename> configuration setting. | ||
4515 | You can find it at <filename>Processor Type and Features</filename> under | ||
4516 | the configuration selection <filename>Symmetric Multi-processing Support</filename>. | ||
4517 | After highlighting the selection, use the arrow keys to select or deselect | ||
4518 | the setting. | ||
4519 | When you are finished with all your selections, exit out and save them. | ||
4520 | </para> | ||
4521 | |||
4522 | <para> | ||
4523 | Saving the selections updates the <filename>.config</filename> configuration file. | ||
4524 | This is the file that the OpenEmbedded build system uses to configure the | ||
4525 | kernel during the build. | ||
4526 | You can find and examine this file in the Build Directory in | ||
4527 | <filename>tmp/work/</filename>. | ||
4528 | The actual <filename>.config</filename> is located in the area where the | ||
4529 | specific kernel is built. | ||
4530 | For example, if you were building a Linux Yocto kernel based on the | ||
4531 | Linux 3.14 kernel and you were building a QEMU image targeted for | ||
4532 | <filename>x86</filename> architecture, the | ||
4533 | <filename>.config</filename> file would be located here: | ||
4534 | <literallayout class='monospaced'> | ||
4535 | poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... | ||
4536 | ...656ed30-r1/linux-qemux86-standard-build | ||
4537 | </literallayout> | ||
4538 | <note> | ||
4539 | The previous example directory is artificially split and many of the characters | ||
4540 | in the actual filename are omitted in order to make it more readable. | ||
4541 | Also, depending on the kernel you are using, the exact pathname | ||
4542 | for <filename>linux-yocto-3.14...</filename> might differ. | ||
4543 | </note> | ||
4544 | </para> | ||
4545 | |||
4546 | <para> | ||
4547 | Within the <filename>.config</filename> file, you can see the kernel settings. | ||
4548 | For example, the following entry shows that symmetric multi-processor support | ||
4549 | is not set: | ||
4550 | <literallayout class='monospaced'> | ||
4551 | # CONFIG_SMP is not set | ||
4552 | </literallayout> | ||
4553 | </para> | ||
4554 | |||
4555 | <para> | ||
4556 | A good method to isolate changed configurations is to use a combination of the | ||
4557 | <filename>menuconfig</filename> tool and simple shell commands. | ||
4558 | Before changing configurations with <filename>menuconfig</filename>, copy the | ||
4559 | existing <filename>.config</filename> and rename it to something else, | ||
4560 | use <filename>menuconfig</filename> to make | ||
4561 | as many changes as you want and save them, then compare the renamed configuration | ||
4562 | file against the newly created file. | ||
4563 | You can use the resulting differences as your base to create configuration fragments | ||
4564 | to permanently save in your kernel layer. | ||
4565 | <note> | ||
4566 | Be sure to make a copy of the <filename>.config</filename> and don't just | ||
4567 | rename it. | ||
4568 | The build system needs an existing <filename>.config</filename> | ||
4569 | from which to work. | ||
4570 | </note> | ||
4571 | </para> | ||
4572 | </section> | ||
4573 | |||
4574 | <section id='creating-config-fragments'> | ||
4575 | <title>Creating Configuration Fragments</title> | ||
4576 | |||
4577 | <para> | ||
4578 | Configuration fragments are simply kernel options that appear in a file | ||
4579 | placed where the OpenEmbedded build system can find and apply them. | ||
4580 | Syntactically, the configuration statement is identical to what would appear | ||
4581 | in the <filename>.config</filename> file, which is in the | ||
4582 | <link linkend='build-directory'>Build Directory</link> in | ||
4583 | <filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>. | ||
4584 | </para> | ||
4585 | |||
4586 | <para> | ||
4587 | It is simple to create a configuration fragment. | ||
4588 | For example, issuing the following from the shell creates a configuration fragment | ||
4589 | file named <filename>my_smp.cfg</filename> that enables multi-processor support | ||
4590 | within the kernel: | ||
4591 | <literallayout class='monospaced'> | ||
4592 | $ echo "CONFIG_SMP=y" >> my_smp.cfg | ||
4593 | </literallayout> | ||
4594 | <note> | ||
4595 | All configuration files must use the <filename>.cfg</filename> extension in order | ||
4596 | for the OpenEmbedded build system to recognize them as a configuration fragment. | ||
4597 | </note> | ||
4598 | </para> | ||
4599 | |||
4600 | <para> | ||
4601 | Where do you put your configuration files? | ||
4602 | You can place these configuration files in the same area pointed to by | ||
4603 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. | ||
4604 | The OpenEmbedded build system will pick up the configuration and add it to the | ||
4605 | kernel's configuration. | ||
4606 | For example, suppose you had a set of configuration options in a file called | ||
4607 | <filename>myconfig.cfg</filename>. | ||
4608 | If you put that file inside a directory named <filename>linux-yocto</filename> | ||
4609 | that resides in the same directory as the kernel's append file and then add | ||
4610 | a <filename>SRC_URI</filename> statement such as the following to the kernel's append file, | ||
4611 | those configuration options will be picked up and applied when the kernel is built. | ||
4612 | <literallayout class='monospaced'> | ||
4613 | SRC_URI += "file://myconfig.cfg" | ||
4614 | </literallayout> | ||
4615 | </para> | ||
4616 | |||
4617 | <para> | ||
4618 | As mentioned earlier, you can group related configurations into multiple files and | ||
4619 | name them all in the <filename>SRC_URI</filename> statement as well. | ||
4620 | For example, you could group separate configurations specifically for Ethernet and graphics | ||
4621 | into their own files and add those by using a <filename>SRC_URI</filename> statement like the | ||
4622 | following in your append file: | ||
4623 | <literallayout class='monospaced'> | ||
4624 | SRC_URI += "file://myconfig.cfg \ | ||
4625 | file://eth.cfg \ | ||
4626 | file://gfx.cfg" | ||
4627 | </literallayout> | ||
4628 | </para> | ||
4629 | </section> | ||
4630 | |||
4631 | <section id='fine-tuning-the-kernel-configuration-file'> | ||
4632 | <title>Fine-Tuning the Kernel Configuration File</title> | ||
4633 | |||
4634 | <para> | ||
4635 | You can make sure the <filename>.config</filename> file is as lean or efficient as | ||
4636 | possible by reading the output of the kernel configuration fragment audit, | ||
4637 | noting any issues, making changes to correct the issues, and then repeating. | ||
4638 | </para> | ||
4639 | |||
4640 | <para> | ||
4641 | As part of the kernel build process, the | ||
4642 | <filename>do_kernel_configcheck</filename> task runs. | ||
4643 | This task validates the kernel configuration by checking the final | ||
4644 | <filename>.config</filename> file against the input files. | ||
4645 | During the check, the task produces warning messages for the following | ||
4646 | issues: | ||
4647 | <itemizedlist> | ||
4648 | <listitem><para>Requested options that did not make the final | ||
4649 | <filename>.config</filename> file.</para></listitem> | ||
4650 | <listitem><para>Configuration items that appear twice in the same | ||
4651 | configuration fragment.</para></listitem> | ||
4652 | <listitem><para>Configuration items tagged as "required" that were overridden. | ||
4653 | </para></listitem> | ||
4654 | <listitem><para>A board overrides a non-board specific option.</para></listitem> | ||
4655 | <listitem><para>Listed options not valid for the kernel being processed. | ||
4656 | In other words, the option does not appear anywhere.</para></listitem> | ||
4657 | </itemizedlist> | ||
4658 | <note> | ||
4659 | The <filename>do_kernel_configcheck</filename> task can | ||
4660 | also optionally report if an option is overridden during | ||
4661 | processing. | ||
4662 | </note> | ||
4663 | </para> | ||
4664 | |||
4665 | <para> | ||
4666 | For each output warning, a message points to the file | ||
4667 | that contains a list of the options and a pointer to the config | ||
4668 | fragment that defines them. | ||
4669 | Collectively, the files are the key to streamlining the configuration. | ||
4670 | </para> | ||
4671 | |||
4672 | <para> | ||
4673 | To streamline the configuration, do the following: | ||
4674 | <orderedlist> | ||
4675 | <listitem><para>Start with a full configuration that you | ||
4676 | know works - it builds and boots successfully. | ||
4677 | This configuration file will be your baseline. | ||
4678 | </para></listitem> | ||
4679 | <listitem><para>Separately run the | ||
4680 | <filename>do_configme</filename> and | ||
4681 | <filename>do_kernel_configcheck</filename> tasks. | ||
4682 | </para></listitem> | ||
4683 | <listitem><para>Take the resulting list of files from the | ||
4684 | <filename>do_kernel_configcheck</filename> task | ||
4685 | warnings and do the following: | ||
4686 | <itemizedlist> | ||
4687 | <listitem><para> | ||
4688 | Drop values that are redefined in the fragment | ||
4689 | but do not change the final | ||
4690 | <filename>.config</filename> file. | ||
4691 | </para></listitem> | ||
4692 | <listitem><para> | ||
4693 | Analyze and potentially drop values from the | ||
4694 | <filename>.config</filename> file that override | ||
4695 | required configurations. | ||
4696 | </para></listitem> | ||
4697 | <listitem><para> | ||
4698 | Analyze and potentially remove non-board | ||
4699 | specific options. | ||
4700 | </para></listitem> | ||
4701 | <listitem><para> | ||
4702 | Remove repeated and invalid options. | ||
4703 | </para></listitem> | ||
4704 | </itemizedlist></para></listitem> | ||
4705 | <listitem><para> | ||
4706 | After you have worked through the output of the kernel | ||
4707 | configuration audit, you can re-run the | ||
4708 | <filename>do_configme</filename> and | ||
4709 | <filename>do_kernel_configcheck</filename> tasks to | ||
4710 | see the results of your changes. | ||
4711 | If you have more issues, you can deal with them as | ||
4712 | described in the previous step. | ||
4713 | </para></listitem> | ||
4714 | </orderedlist> | ||
4715 | </para> | ||
4716 | |||
4717 | <para> | ||
4718 | Iteratively working through steps two through four eventually yields | ||
4719 | a minimal, streamlined configuration file. | ||
4720 | Once you have the best <filename>.config</filename>, you can build the Linux | ||
4721 | Yocto kernel. | ||
4722 | </para> | ||
4723 | </section> | ||
4724 | </section> | ||
4725 | |||
4726 | <section id="patching-the-kernel"> | ||
4727 | <title>Patching the Kernel</title> | ||
4728 | |||
4729 | <para> | ||
4730 | Patching the kernel involves changing or adding configurations to an existing kernel, | ||
4731 | changing or adding recipes to the kernel that are needed to support specific hardware features, | ||
4732 | or even altering the source code itself. | ||
4733 | <note> | ||
4734 | You can use the <filename>yocto-kernel</filename> script | ||
4735 | found in the <link linkend='source-directory'>Source Directory</link> | ||
4736 | under <filename>scripts</filename> to manage kernel patches and configuration. | ||
4737 | See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>" | ||
4738 | section in the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
4739 | more information.</note> | ||
4740 | </para> | ||
4741 | |||
4742 | <para> | ||
4743 | This example creates a simple patch by adding some QEMU emulator console | ||
4744 | output at boot time through <filename>printk</filename> statements in the kernel's | ||
4745 | <filename>calibrate.c</filename> source code file. | ||
4746 | Applying the patch and booting the modified image causes the added | ||
4747 | messages to appear on the emulator's console. | ||
4748 | </para> | ||
4749 | |||
4750 | <para> | ||
4751 | The example assumes a clean build exists for the <filename>qemux86</filename> | ||
4752 | machine in a | ||
4753 | <link linkend='source-directory'>Source Directory</link> | ||
4754 | named <filename>poky</filename>. | ||
4755 | Furthermore, the <link linkend='build-directory'>Build Directory</link> is | ||
4756 | <filename>build</filename> and is located in <filename>poky</filename> and | ||
4757 | the kernel is based on the Linux 3.4 kernel. | ||
4758 | For general information on how to configure the most efficient build, see the | ||
4759 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | ||
4760 | in the Yocto Project Quick Start. | ||
4761 | </para> | ||
4762 | |||
4763 | <para> | ||
4764 | Also, for more information on patching the kernel, see the | ||
4765 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>" | ||
4766 | section in the Yocto Project Linux Kernel Development Manual. | ||
4767 | </para> | ||
4768 | |||
4769 | <section id='create-a-layer-for-your-changes'> | ||
4770 | <title>Create a Layer for your Changes</title> | ||
4771 | |||
4772 | <para> | ||
4773 | The first step is to create a layer so you can isolate your | ||
4774 | changes. | ||
4775 | Rather than use the <filename>yocto-layer</filename> script | ||
4776 | to create the layer, this example steps through the process | ||
4777 | by hand. | ||
4778 | If you want information on the script that creates a general | ||
4779 | layer, see the | ||
4780 | "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" | ||
4781 | section. | ||
4782 | </para> | ||
4783 | |||
4784 | <para> | ||
4785 | These two commands create a directory you can use for your | ||
4786 | layer: | ||
4787 | <literallayout class='monospaced'> | ||
4788 | $ cd ~/poky | ||
4789 | $ mkdir meta-mylayer | ||
4790 | </literallayout> | ||
4791 | Creating a directory that follows the Yocto Project layer naming | ||
4792 | conventions sets up the layer for your changes. | ||
4793 | The layer is where you place your configuration files, append | ||
4794 | files, and patch files. | ||
4795 | To learn more about creating a layer and filling it with the | ||
4796 | files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding | ||
4797 | and Creating Layers</link>" section. | ||
4798 | </para> | ||
4799 | </section> | ||
4800 | |||
4801 | <section id='finding-the-kernel-source-code'> | ||
4802 | <title>Finding the Kernel Source Code</title> | ||
4803 | |||
4804 | <para> | ||
4805 | Each time you build a kernel image, the kernel source code is fetched | ||
4806 | and unpacked into the following directory: | ||
4807 | <literallayout class='monospaced'> | ||
4808 | ${S}/linux | ||
4809 | </literallayout> | ||
4810 | See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | ||
4811 | section and the | ||
4812 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable | ||
4813 | for more information about where source is kept during a build. | ||
4814 | </para> | ||
4815 | |||
4816 | <para> | ||
4817 | For this example, we are going to patch the | ||
4818 | <filename>init/calibrate.c</filename> file | ||
4819 | by adding some simple console <filename>printk</filename> statements that we can | ||
4820 | see when we boot the image using QEMU. | ||
4821 | </para> | ||
4822 | </section> | ||
4823 | |||
4824 | <section id='creating-the-patch'> | ||
4825 | <title>Creating the Patch</title> | ||
4826 | |||
4827 | <para> | ||
4828 | Two methods exist by which you can create the patch: | ||
4829 | <link linkend='using-a-git-workflow'>Git workflow</link> and | ||
4830 | <link linkend='using-a-quilt-workflow'>Quilt workflow</link>. | ||
4831 | For kernel patches, the Git workflow is more appropriate. | ||
4832 | This section assumes the Git workflow and shows the steps specific to | ||
4833 | this example. | ||
4834 | <orderedlist> | ||
4835 | <listitem><para><emphasis>Change the working directory</emphasis>: | ||
4836 | Change to where the kernel source code is before making | ||
4837 | your edits to the <filename>calibrate.c</filename> file: | ||
4838 | <literallayout class='monospaced'> | ||
4839 | $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux | ||
4840 | </literallayout> | ||
4841 | Because you are working in an established Git repository, | ||
4842 | you must be in this directory in order to commit your changes | ||
4843 | and create the patch file. | ||
4844 | <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and | ||
4845 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables | ||
4846 | represent the version and revision for the | ||
4847 | <filename>linux-yocto</filename> recipe. | ||
4848 | The <filename>PV</filename> variable includes the Git meta and machine | ||
4849 | hashes, which make the directory name longer than you might | ||
4850 | expect. | ||
4851 | </note></para></listitem> | ||
4852 | <listitem><para><emphasis>Edit the source file</emphasis>: | ||
4853 | Edit the <filename>init/calibrate.c</filename> file to have the | ||
4854 | following changes: | ||
4855 | <literallayout class='monospaced'> | ||
4856 | void calibrate_delay(void) | ||
4857 | { | ||
4858 | unsigned long lpj; | ||
4859 | static bool printed; | ||
4860 | int this_cpu = smp_processor_id(); | ||
4861 | |||
4862 | printk("*************************************\n"); | ||
4863 | printk("* *\n"); | ||
4864 | printk("* HELLO YOCTO KERNEL *\n"); | ||
4865 | printk("* *\n"); | ||
4866 | printk("*************************************\n"); | ||
4867 | |||
4868 | if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { | ||
4869 | . | ||
4870 | . | ||
4871 | . | ||
4872 | </literallayout></para></listitem> | ||
4873 | <listitem><para><emphasis>Stage and commit your changes</emphasis>: | ||
4874 | These Git commands display the modified file, stage it, and then | ||
4875 | commit the file: | ||
4876 | <literallayout class='monospaced'> | ||
4877 | $ git status | ||
4878 | $ git add init/calibrate.c | ||
4879 | $ git commit -m "calibrate: Add printk example" | ||
4880 | </literallayout></para></listitem> | ||
4881 | <listitem><para><emphasis>Generate the patch file</emphasis>: | ||
4882 | This Git command creates the a patch file named | ||
4883 | <filename>0001-calibrate-Add-printk-example.patch</filename> | ||
4884 | in the current directory. | ||
4885 | <literallayout class='monospaced'> | ||
4886 | $ git format-patch -1 | ||
4887 | </literallayout> | ||
4888 | </para></listitem> | ||
4889 | </orderedlist> | ||
4890 | </para> | ||
4891 | </section> | ||
4892 | |||
4893 | <section id='set-up-your-layer-for-the-build'> | ||
4894 | <title>Set Up Your Layer for the Build</title> | ||
4895 | |||
4896 | <para>These steps get your layer set up for the build: | ||
4897 | <orderedlist> | ||
4898 | <listitem><para><emphasis>Create additional structure</emphasis>: | ||
4899 | Create the additional layer structure: | ||
4900 | <literallayout class='monospaced'> | ||
4901 | $ cd ~/poky/meta-mylayer | ||
4902 | $ mkdir conf | ||
4903 | $ mkdir recipes-kernel | ||
4904 | $ mkdir recipes-kernel/linux | ||
4905 | $ mkdir recipes-kernel/linux/linux-yocto | ||
4906 | </literallayout> | ||
4907 | The <filename>conf</filename> directory holds your configuration files, while the | ||
4908 | <filename>recipes-kernel</filename> directory holds your append file and | ||
4909 | your patch file.</para></listitem> | ||
4910 | <listitem><para><emphasis>Create the layer configuration file</emphasis>: | ||
4911 | Move to the <filename>meta-mylayer/conf</filename> directory and create | ||
4912 | the <filename>layer.conf</filename> file as follows: | ||
4913 | <literallayout class='monospaced'> | ||
4914 | # We have a conf and classes directory, add to BBPATH | ||
4915 | BBPATH .= ":${LAYERDIR}" | ||
4916 | |||
4917 | # We have recipes-* directories, add to BBFILES | ||
4918 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ | ||
4919 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
4920 | |||
4921 | BBFILE_COLLECTIONS += "mylayer" | ||
4922 | BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" | ||
4923 | BBFILE_PRIORITY_mylayer = "5" | ||
4924 | </literallayout> | ||
4925 | Notice <filename>mylayer</filename> as part of the last three | ||
4926 | statements.</para></listitem> | ||
4927 | <listitem><para><emphasis>Create the kernel recipe append file</emphasis>: | ||
4928 | Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create | ||
4929 | the <filename>linux-yocto_3.4.bbappend</filename> file as follows: | ||
4930 | <literallayout class='monospaced'> | ||
4931 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
4932 | |||
4933 | SRC_URI += "file://0001-calibrate-Add-printk-example.patch" | ||
4934 | </literallayout> | ||
4935 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> | ||
4936 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
4937 | statements enable the OpenEmbedded build system to find the patch file. | ||
4938 | For more information on using append files, see the | ||
4939 | "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" | ||
4940 | section. | ||
4941 | </para></listitem> | ||
4942 | <listitem><para><emphasis>Put the patch file in your layer</emphasis>: | ||
4943 | Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to | ||
4944 | the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> | ||
4945 | directory.</para></listitem> | ||
4946 | </orderedlist> | ||
4947 | </para> | ||
4948 | </section> | ||
4949 | |||
4950 | <section id='set-up-for-the-build'> | ||
4951 | <title>Set Up for the Build</title> | ||
4952 | |||
4953 | <para> | ||
4954 | Do the following to make sure the build parameters are set up for the example. | ||
4955 | Once you set up these build parameters, they do not have to change unless you | ||
4956 | change the target architecture of the machine you are building: | ||
4957 | <itemizedlist> | ||
4958 | <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your | ||
4959 | selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
4960 | definition within the <filename>local.conf</filename> file in the | ||
4961 | <link linkend='build-directory'>Build Directory</link> | ||
4962 | specifies the target architecture used when building the Linux kernel. | ||
4963 | By default, <filename>MACHINE</filename> is set to | ||
4964 | <filename>qemux86</filename>, which specifies a 32-bit | ||
4965 | <trademark class='registered'>Intel</trademark> Architecture | ||
4966 | target machine suitable for the QEMU emulator.</para></listitem> | ||
4967 | <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename> | ||
4968 | layer:</emphasis> The | ||
4969 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> | ||
4970 | variable in the | ||
4971 | <filename>bblayers.conf</filename> file found in the | ||
4972 | <filename>poky/build/conf</filename> directory needs to have the path to your local | ||
4973 | <filename>meta-mylayer</filename> layer. | ||
4974 | By default, the <filename>BBLAYERS</filename> variable contains paths to | ||
4975 | <filename>meta</filename>, <filename>meta-yocto</filename>, and | ||
4976 | <filename>meta-yocto-bsp</filename> in the | ||
4977 | <filename>poky</filename> Git repository. | ||
4978 | Add the path to your <filename>meta-mylayer</filename> location: | ||
4979 | <literallayout class='monospaced'> | ||
4980 | BBLAYERS ?= " \ | ||
4981 | $HOME/poky/meta \ | ||
4982 | $HOME/poky/meta-yocto \ | ||
4983 | $HOME/poky/meta-yocto-bsp \ | ||
4984 | $HOME/poky/meta-mylayer \ | ||
4985 | " | ||
4986 | |||
4987 | BBLAYERS_NON_REMOVABLE ?= " \ | ||
4988 | $HOME/poky/meta \ | ||
4989 | $HOME/poky/meta-yocto \ | ||
4990 | " | ||
4991 | </literallayout></para></listitem> | ||
4992 | </itemizedlist> | ||
4993 | </para> | ||
4994 | </section> | ||
4995 | |||
4996 | <section id='build-the-modified-qemu-kernel-image'> | ||
4997 | <title>Build the Modified QEMU Kernel Image</title> | ||
4998 | |||
4999 | <para> | ||
5000 | The following steps build your modified kernel image: | ||
5001 | <orderedlist> | ||
5002 | <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>: | ||
5003 | Your environment should be set up since you previously sourced | ||
5004 | the | ||
5005 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
5006 | script. | ||
5007 | If it is not, source the script again from <filename>poky</filename>. | ||
5008 | <literallayout class='monospaced'> | ||
5009 | $ cd ~/poky | ||
5010 | $ source &OE_INIT_FILE; | ||
5011 | </literallayout> | ||
5012 | </para></listitem> | ||
5013 | <listitem><para><emphasis>Clean up</emphasis>: | ||
5014 | Be sure to clean the shared state out by using BitBake | ||
5015 | to run from within the Build Directory the | ||
5016 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink> | ||
5017 | task as follows: | ||
5018 | <literallayout class='monospaced'> | ||
5019 | $ bitbake -c cleansstate linux-yocto | ||
5020 | </literallayout></para> | ||
5021 | <para> | ||
5022 | <note> | ||
5023 | Never remove any files by hand from the | ||
5024 | <filename>tmp/deploy</filename> | ||
5025 | directory inside the | ||
5026 | <link linkend='build-directory'>Build Directory</link>. | ||
5027 | Always use the various BitBake clean tasks to | ||
5028 | clear out previous build artifacts. | ||
5029 | For information on the clean tasks, see the | ||
5030 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>", | ||
5031 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>", | ||
5032 | and | ||
5033 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>do_cleansstate</filename></ulink>" | ||
5034 | sections all in the Yocto Project Reference | ||
5035 | Manual. | ||
5036 | </note> | ||
5037 | </para></listitem> | ||
5038 | <listitem><para><emphasis>Build the image</emphasis>: | ||
5039 | Next, build the kernel image using this command: | ||
5040 | <literallayout class='monospaced'> | ||
5041 | $ bitbake -k linux-yocto | ||
5042 | </literallayout></para></listitem> | ||
5043 | </orderedlist> | ||
5044 | </para> | ||
5045 | </section> | ||
5046 | |||
5047 | <section id='boot-the-image-and-verify-your-changes'> | ||
5048 | <title>Boot the Image and Verify Your Changes</title> | ||
5049 | |||
5050 | <para> | ||
5051 | These steps boot the image and allow you to see the changes | ||
5052 | <orderedlist> | ||
5053 | <listitem><para><emphasis>Boot the image</emphasis>: | ||
5054 | Boot the modified image in the QEMU emulator | ||
5055 | using this command: | ||
5056 | <literallayout class='monospaced'> | ||
5057 | $ runqemu qemux86 | ||
5058 | </literallayout></para></listitem> | ||
5059 | <listitem><para><emphasis>Verify the changes</emphasis>: | ||
5060 | Log into the machine using <filename>root</filename> with no password and then | ||
5061 | use the following shell command to scroll through the console's boot output. | ||
5062 | <literallayout class='monospaced'> | ||
5063 | # dmesg | less | ||
5064 | </literallayout> | ||
5065 | You should see the results of your <filename>printk</filename> statements | ||
5066 | as part of the output.</para></listitem> | ||
5067 | </orderedlist> | ||
5068 | </para> | ||
5069 | </section> | ||
5070 | </section> | ||
5071 | |||
5072 | <section id='making-images-more-secure'> | ||
5073 | <title>Making Images More Secure</title> | ||
5074 | |||
5075 | <para> | ||
5076 | Security is of increasing concern for embedded devices. | ||
5077 | Consider the issues and problems discussed in just this | ||
5078 | sampling of work found across the Internet: | ||
5079 | <itemizedlist> | ||
5080 | <listitem><para><emphasis> | ||
5081 | "<ulink url='https://www.schneier.com/blog/archives/2014/01/security_risks_9.html'>Security Risks of Embedded Systems</ulink>"</emphasis> | ||
5082 | by Bruce Schneier | ||
5083 | </para></listitem> | ||
5084 | <listitem><para><emphasis> | ||
5085 | "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis> | ||
5086 | by Carna Botnet</para></listitem> | ||
5087 | <listitem><para><emphasis> | ||
5088 | "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis> | ||
5089 | by Jake Edge | ||
5090 | </para></listitem> | ||
5091 | <listitem><para><emphasis> | ||
5092 | "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security | ||
5093 | Gateways via their Web Interfaces</ulink>"</emphasis> | ||
5094 | by Ben Williams | ||
5095 | </para></listitem> | ||
5096 | </itemizedlist> | ||
5097 | </para> | ||
5098 | |||
5099 | <para> | ||
5100 | When securing your image is of concern, there are steps, tools, | ||
5101 | and variables that you can consider to help you reach the | ||
5102 | security goals you need for your particular device. | ||
5103 | Not all situations are identical when it comes to making an | ||
5104 | image secure. | ||
5105 | Consequently, this section provides some guidance and suggestions | ||
5106 | for consideration when you want to make your image more secure. | ||
5107 | <note> | ||
5108 | Because the security requirements and risks are | ||
5109 | different for every type of device, this section cannot | ||
5110 | provide a complete reference on securing your custom OS. | ||
5111 | It is strongly recommended that you also consult other sources | ||
5112 | of information on embedded Linux system hardening and on | ||
5113 | security. | ||
5114 | </note> | ||
5115 | </para> | ||
5116 | |||
5117 | <section id='general-considerations'> | ||
5118 | <title>General Considerations</title> | ||
5119 | |||
5120 | <para> | ||
5121 | General considerations exist that help you create more | ||
5122 | secure images. | ||
5123 | You should consider the following suggestions to help | ||
5124 | make your device more secure: | ||
5125 | <itemizedlist> | ||
5126 | <listitem><para> | ||
5127 | Scan additional code you are adding to the system | ||
5128 | (e.g. application code) by using static analysis | ||
5129 | tools. | ||
5130 | Look for buffer overflows and other potential | ||
5131 | security problems. | ||
5132 | </para></listitem> | ||
5133 | <listitem><para> | ||
5134 | Pay particular attention to the security for | ||
5135 | any web-based administration interface. | ||
5136 | </para> | ||
5137 | <para>Web interfaces typically need to perform | ||
5138 | administrative functions and tend to need to run with | ||
5139 | elevated privileges. | ||
5140 | Thus, the consequences resulting from the interface's | ||
5141 | security becoming compromised can be serious. | ||
5142 | Look for common web vulnerabilities such as | ||
5143 | cross-site-scripting (XSS), unvalidated inputs, | ||
5144 | and so forth.</para> | ||
5145 | <para>As with system passwords, the default credentials | ||
5146 | for accessing a web-based interface should not be the | ||
5147 | same across all devices. | ||
5148 | This is particularly true if the interface is enabled | ||
5149 | by default as it can be assumed that many end-users | ||
5150 | will not change the credentials. | ||
5151 | </para></listitem> | ||
5152 | <listitem><para> | ||
5153 | Ensure you can update the software on the device to | ||
5154 | mitigate vulnerabilities discovered in the future. | ||
5155 | This consideration especially applies when your | ||
5156 | device is network-enabled. | ||
5157 | </para></listitem> | ||
5158 | <listitem><para> | ||
5159 | Ensure you remove or disable debugging functionality | ||
5160 | before producing the final image. | ||
5161 | For information on how to do this, see the | ||
5162 | "<link linkend='considerations-specific-to-the-openembedded-build-system'>Considerations Specific to the OpenEmbedded Build System</link>" | ||
5163 | section. | ||
5164 | </para></listitem> | ||
5165 | <listitem><para> | ||
5166 | Ensure you have no network services listening that | ||
5167 | are not needed. | ||
5168 | </para></listitem> | ||
5169 | <listitem><para> | ||
5170 | Remove any software from the image that is not needed. | ||
5171 | </para></listitem> | ||
5172 | <listitem><para> | ||
5173 | Enable hardware support for secure boot functionality | ||
5174 | when your device supports this functionality. | ||
5175 | </para></listitem> | ||
5176 | </itemizedlist> | ||
5177 | </para> | ||
5178 | </section> | ||
5179 | |||
5180 | <section id='security-flags'> | ||
5181 | <title>Security Flags</title> | ||
5182 | |||
5183 | <para> | ||
5184 | The Yocto Project has security flags that you can enable that | ||
5185 | help make your build output more secure. | ||
5186 | The security flags are in the | ||
5187 | <filename>meta/conf/distro/include/security_flags.inc</filename> | ||
5188 | file in your | ||
5189 | <link linkend='source-directory'>Source Directory</link> | ||
5190 | (e.g. <filename>poky</filename>). | ||
5191 | <note> | ||
5192 | Depending on the recipe, certain security flags are enabled | ||
5193 | and disabled by default. | ||
5194 | </note> | ||
5195 | </para> | ||
5196 | |||
5197 | <para> | ||
5198 | <!-- | ||
5199 | The GCC/LD flags in <filename>security_flags.inc</filename> | ||
5200 | enable more secure code generation. | ||
5201 | By including the <filename>security_flags.inc</filename> | ||
5202 | file, you enable flags to the compiler and linker that cause | ||
5203 | them to generate more secure code. | ||
5204 | <note> | ||
5205 | The GCC/LD flags are enabled by default in the | ||
5206 | <filename>poky-lsb</filename> distribution. | ||
5207 | </note> | ||
5208 | --> | ||
5209 | Use the following line in your | ||
5210 | <filename>local.conf</filename> file or in your custom | ||
5211 | distribution configuration file to enable the security | ||
5212 | compiler and linker flags for your build: | ||
5213 | <literallayout class='monospaced'> | ||
5214 | require conf/distro/include/security_flags.inc | ||
5215 | </literallayout> | ||
5216 | </para> | ||
5217 | </section> | ||
5218 | |||
5219 | <section id='considerations-specific-to-the-openembedded-build-system'> | ||
5220 | <title>Considerations Specific to the OpenEmbedded Build System</title> | ||
5221 | |||
5222 | <para> | ||
5223 | You can take some steps that are specific to the | ||
5224 | OpenEmbedded build system to make your images more secure: | ||
5225 | <itemizedlist> | ||
5226 | <listitem><para> | ||
5227 | Ensure "debug-tweaks" is not one of your selected | ||
5228 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>. | ||
5229 | When creating a new project, the default is to provide you | ||
5230 | with an initial <filename>local.conf</filename> file that | ||
5231 | enables this feature using the | ||
5232 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> variable with the line: | ||
5233 | <literallayout class='monospaced'> | ||
5234 | EXTRA_IMAGE_FEATURES = "debug-tweaks" | ||
5235 | </literallayout> | ||
5236 | To disable that feature, simply comment out that line in your | ||
5237 | <filename>local.conf</filename> file, or | ||
5238 | make sure <filename>IMAGE_FEATURES</filename> does not contain | ||
5239 | "debug-tweaks" before producing your final image. | ||
5240 | Among other things, leaving this in place sets the | ||
5241 | root password as blank, which makes logging in for | ||
5242 | debugging or inspection easy during | ||
5243 | development but also means anyone can easily log in | ||
5244 | during production. | ||
5245 | </para></listitem> | ||
5246 | <listitem><para> | ||
5247 | It is possible to set a root password for the image | ||
5248 | and also to set passwords for any extra users you might | ||
5249 | add (e.g. administrative or service type users). | ||
5250 | When you set up passwords for multiple images or | ||
5251 | users, you should not duplicate passwords. | ||
5252 | </para> | ||
5253 | <para> | ||
5254 | To set up passwords, use the | ||
5255 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers</filename></ulink> | ||
5256 | class, which is the preferred method. | ||
5257 | For an example on how to set up both root and user | ||
5258 | passwords, see the | ||
5259 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>" | ||
5260 | section. | ||
5261 | <note> | ||
5262 | When adding extra user accounts or setting a | ||
5263 | root password, be cautious about setting the | ||
5264 | same password on every device. | ||
5265 | If you do this, and the password you have set | ||
5266 | is exposed, then every device is now potentially | ||
5267 | compromised. | ||
5268 | If you need this access but want to ensure | ||
5269 | security, consider setting a different, | ||
5270 | random password for each device. | ||
5271 | Typically, you do this as a separate step after | ||
5272 | you deploy the image onto the device. | ||
5273 | </note> | ||
5274 | </para></listitem> | ||
5275 | <listitem><para> | ||
5276 | Consider enabling a Mandatory Access Control (MAC) | ||
5277 | framework such as SMACK or SELinux and tuning it | ||
5278 | appropriately for your device's usage. | ||
5279 | You can find more information in the | ||
5280 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/'><filename>meta-selinux</filename></ulink> | ||
5281 | layer. | ||
5282 | </para></listitem> | ||
5283 | </itemizedlist> | ||
5284 | </para> | ||
5285 | |||
5286 | <para> | ||
5287 | </para> | ||
5288 | </section> | ||
5289 | |||
5290 | <section id='tools-for-hardening-your-image'> | ||
5291 | <title>Tools for Hardening Your Image</title> | ||
5292 | |||
5293 | <para> | ||
5294 | The Yocto Project provides tools for making your image | ||
5295 | more secure. | ||
5296 | You can find these tools in the | ||
5297 | <filename>meta-security</filename> layer of the | ||
5298 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. | ||
5299 | </para> | ||
5300 | </section> | ||
5301 | </section> | ||
5302 | |||
5303 | <section id='creating-your-own-distribution'> | ||
5304 | <title>Creating Your Own Distribution</title> | ||
5305 | |||
5306 | <para> | ||
5307 | When you build an image using the Yocto Project and | ||
5308 | do not alter any distribution | ||
5309 | <link linkend='metadata'>Metadata</link>, you are creating a | ||
5310 | Poky distribution. | ||
5311 | If you wish to gain more control over package alternative | ||
5312 | selections, compile-time options, and other low-level | ||
5313 | configurations, you can create your own distribution. | ||
5314 | </para> | ||
5315 | |||
5316 | <para> | ||
5317 | To create your own distribution, the basic steps consist of | ||
5318 | creating your own distribution layer, creating your own | ||
5319 | distribution configuration file, and then adding any needed | ||
5320 | code and Metadata to the layer. | ||
5321 | The following steps provide some more detail: | ||
5322 | <itemizedlist> | ||
5323 | <listitem><para><emphasis>Create a layer for your new distro:</emphasis> | ||
5324 | Create your distribution layer so that you can keep your | ||
5325 | Metadata and code for the distribution separate. | ||
5326 | It is strongly recommended that you create and use your own | ||
5327 | layer for configuration and code. | ||
5328 | Using your own layer as compared to just placing | ||
5329 | configurations in a <filename>local.conf</filename> | ||
5330 | configuration file makes it easier to reproduce the same | ||
5331 | build configuration when using multiple build machines. | ||
5332 | See the | ||
5333 | "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>" | ||
5334 | section for information on how to quickly set up a layer. | ||
5335 | </para></listitem> | ||
5336 | <listitem><para><emphasis>Create the distribution configuration file:</emphasis> | ||
5337 | The distribution configuration file needs to be created in | ||
5338 | the <filename>conf/distro</filename> directory of your | ||
5339 | layer. | ||
5340 | You need to name it using your distribution name | ||
5341 | (e.g. <filename>mydistro.conf</filename>). | ||
5342 | <note> | ||
5343 | The | ||
5344 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> | ||
5345 | variable in your | ||
5346 | <filename>local.conf</filename> file determines the | ||
5347 | name of your distribution. | ||
5348 | </note></para> | ||
5349 | <para>You can split out parts of your configuration file | ||
5350 | into include files and then "require" them from within | ||
5351 | your distribution configuration file. | ||
5352 | Be sure to place the include files in the | ||
5353 | <filename>conf/distro/include</filename> directory of | ||
5354 | your layer. | ||
5355 | A common example usage of include files would be to | ||
5356 | separate out the selection of desired version and revisions | ||
5357 | for individual recipes. | ||
5358 | </para> | ||
5359 | <para>Your configuration file needs to set the following | ||
5360 | required variables: | ||
5361 | <literallayout class='monospaced'> | ||
5362 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> | ||
5363 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink> | ||
5364 | </literallayout> | ||
5365 | These following variables are optional and you typically | ||
5366 | set them from the distribution configuration file: | ||
5367 | <literallayout class='monospaced'> | ||
5368 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> | ||
5369 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink> | ||
5370 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink> | ||
5371 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink> | ||
5372 | </literallayout> | ||
5373 | <tip> | ||
5374 | If you want to base your distribution configuration file | ||
5375 | on the very basic configuration from OE-Core, you | ||
5376 | can use | ||
5377 | <filename>conf/distro/defaultsetup.conf</filename> as | ||
5378 | a reference and just include variables that differ | ||
5379 | as compared to <filename>defaultsetup.conf</filename>. | ||
5380 | Alternatively, you can create a distribution | ||
5381 | configuration file from scratch using the | ||
5382 | <filename>defaultsetup.conf</filename> file | ||
5383 | or configuration files from other distributions | ||
5384 | such as Poky or Angstrom as references. | ||
5385 | </tip></para></listitem> | ||
5386 | <listitem><para><emphasis>Provide miscellaneous variables:</emphasis> | ||
5387 | Be sure to define any other variables for which you want to | ||
5388 | create a default or enforce as part of the distribution | ||
5389 | configuration. | ||
5390 | You can include nearly any variable from the | ||
5391 | <filename>local.conf</filename> file. | ||
5392 | The variables you use are not limited to the list in the | ||
5393 | previous bulleted item.</para></listitem> | ||
5394 | <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis> | ||
5395 | In your <filename>local.conf</filename> file in the | ||
5396 | <link linkend='build-directory'>Build Directory</link>, | ||
5397 | set your | ||
5398 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> | ||
5399 | variable to point to your distribution's configuration file. | ||
5400 | For example, if your distribution's configuration file is | ||
5401 | named <filename>mydistro.conf</filename>, then you point | ||
5402 | to it as follows: | ||
5403 | <literallayout class='monospaced'> | ||
5404 | DISTRO = "mydistro" | ||
5405 | </literallayout></para></listitem> | ||
5406 | <listitem><para><emphasis>Add more to the layer if necessary:</emphasis> | ||
5407 | Use your layer to hold other information needed for the | ||
5408 | distribution: | ||
5409 | <itemizedlist> | ||
5410 | <listitem><para>Add recipes for installing | ||
5411 | distro-specific configuration files that are not | ||
5412 | already installed by another recipe. | ||
5413 | If you have distro-specific configuration files | ||
5414 | that are included by an existing recipe, you should | ||
5415 | add an append file (<filename>.bbappend</filename>) | ||
5416 | for those. | ||
5417 | For general information and recommendations | ||
5418 | on how to add recipes to your layer, see the | ||
5419 | "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" | ||
5420 | and | ||
5421 | "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>" | ||
5422 | sections.</para></listitem> | ||
5423 | <listitem><para>Add any image recipes that are specific | ||
5424 | to your distribution.</para></listitem> | ||
5425 | <listitem><para>Add a <filename>psplash</filename> | ||
5426 | append file for a branded splash screen. | ||
5427 | For information on append files, see the | ||
5428 | "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" | ||
5429 | section.</para></listitem> | ||
5430 | <listitem><para>Add any other append files to make | ||
5431 | custom changes that are specific to individual | ||
5432 | recipes.</para></listitem> | ||
5433 | </itemizedlist></para></listitem> | ||
5434 | </itemizedlist> | ||
5435 | </para> | ||
5436 | </section> | ||
5437 | |||
5438 | <section id='creating-a-custom-template-configuration-directory'> | ||
5439 | <title>Creating a Custom Template Configuration Directory</title> | ||
5440 | |||
5441 | <para> | ||
5442 | If you are producing your own customized version | ||
5443 | of the build system for use by other users, you might | ||
5444 | want to customize the message shown by the setup script or | ||
5445 | you might want to change the template configuration files (i.e. | ||
5446 | <filename>local.conf</filename> and | ||
5447 | <filename>bblayers.conf</filename>) that are created in | ||
5448 | a new build directory. | ||
5449 | </para> | ||
5450 | |||
5451 | <para> | ||
5452 | The OpenEmbedded build system uses the environment variable | ||
5453 | <filename>TEMPLATECONF</filename> to locate the directory | ||
5454 | from which it gathers configuration information that ultimately | ||
5455 | ends up in the | ||
5456 | <link linkend='build-directory'>Build Directory's</link> | ||
5457 | <filename>conf</filename> directory. | ||
5458 | By default, <filename>TEMPLATECONF</filename> is set as | ||
5459 | follows in the <filename>poky</filename> repository: | ||
5460 | <literallayout class='monospaced'> | ||
5461 | TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf} | ||
5462 | </literallayout> | ||
5463 | This is the directory used by the build system to find templates | ||
5464 | from which to build some key configuration files. | ||
5465 | If you look at this directory, you will see the | ||
5466 | <filename>bblayers.conf.sample</filename>, | ||
5467 | <filename>local.conf.sample</filename>, and | ||
5468 | <filename>conf-notes.txt</filename> files. | ||
5469 | The build system uses these files to form the respective | ||
5470 | <filename>bblayers.conf</filename> file, | ||
5471 | <filename>local.conf</filename> file, and display the list of | ||
5472 | BitBake targets when running the setup script. | ||
5473 | </para> | ||
5474 | |||
5475 | <para> | ||
5476 | To override these default configuration files with | ||
5477 | configurations you want used within every new | ||
5478 | Build Directory, simply set the | ||
5479 | <filename>TEMPLATECONF</filename> variable to your directory. | ||
5480 | The <filename>TEMPLATECONF</filename> variable is set in the | ||
5481 | <filename>.templateconf</filename> file, which is in the | ||
5482 | top-level | ||
5483 | <link linkend='source-directory'>Source Directory</link> | ||
5484 | folder (e.g. <filename>poky</filename>). | ||
5485 | Edit the <filename>.templateconf</filename> so that it can locate | ||
5486 | your directory. | ||
5487 | </para> | ||
5488 | |||
5489 | <para> | ||
5490 | Best practices dictate that you should keep your | ||
5491 | template configuration directory in your custom distribution layer. | ||
5492 | For example, suppose you have a layer named | ||
5493 | <filename>meta-mylayer</filename> located in your home directory | ||
5494 | and you want your template configuration directory named | ||
5495 | <filename>myconf</filename>. | ||
5496 | Changing the <filename>.templateconf</filename> as follows | ||
5497 | causes the OpenEmbedded build system to look in your directory | ||
5498 | and base its configuration files on the | ||
5499 | <filename>*.sample</filename> configuration files it finds. | ||
5500 | The final configuration files (i.e. | ||
5501 | <filename>local.conf</filename> and | ||
5502 | <filename>bblayers.conf</filename> ultimately still end up in | ||
5503 | your Build Directory, but they are based on your | ||
5504 | <filename>*.sample</filename> files. | ||
5505 | <literallayout class='monospaced'> | ||
5506 | TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} | ||
5507 | </literallayout> | ||
5508 | </para> | ||
5509 | |||
5510 | <para> | ||
5511 | Aside from the <filename>*.sample</filename> configuration files, | ||
5512 | the <filename>conf-notes.txt</filename> also resides in the | ||
5513 | default <filename>meta-yocto/conf</filename> directory. | ||
5514 | The scripts that set up the build environment | ||
5515 | (i.e. | ||
5516 | <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> | ||
5517 | and | ||
5518 | <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>) | ||
5519 | use this file to display BitBake targets as part of the script | ||
5520 | output. | ||
5521 | Customizing this <filename>conf-notes.txt</filename> file is a | ||
5522 | good way to make sure your list of custom targets appears | ||
5523 | as part of the script's output. | ||
5524 | </para> | ||
5525 | |||
5526 | <para> | ||
5527 | Here is the default list of targets displayed as a result of | ||
5528 | running either of the setup scripts: | ||
5529 | <literallayout class='monospaced'> | ||
5530 | You can now run 'bitbake <target>' | ||
5531 | |||
5532 | Common targets are: | ||
5533 | core-image-minimal | ||
5534 | core-image-sato | ||
5535 | meta-toolchain | ||
5536 | adt-installer | ||
5537 | meta-ide-support | ||
5538 | </literallayout> | ||
5539 | </para> | ||
5540 | |||
5541 | <para> | ||
5542 | Changing the listed common targets is as easy as editing your | ||
5543 | version of <filename>conf-notes.txt</filename> in your | ||
5544 | custom template configuration directory and making sure you | ||
5545 | have <filename>TEMPLATECONF</filename> set to your directory. | ||
5546 | </para> | ||
5547 | </section> | ||
5548 | |||
5549 | <section id='building-a-tiny-system'> | ||
5550 | <title>Building a Tiny System</title> | ||
5551 | |||
5552 | <para> | ||
5553 | Very small distributions have some significant advantages such | ||
5554 | as requiring less on-die or in-package memory (cheaper), better | ||
5555 | performance through efficient cache usage, lower power requirements | ||
5556 | due to less memory, faster boot times, and reduced development | ||
5557 | overhead. | ||
5558 | Some real-world examples where a very small distribution gives | ||
5559 | you distinct advantages are digital cameras, medical devices, | ||
5560 | and small headless systems. | ||
5561 | </para> | ||
5562 | |||
5563 | <para> | ||
5564 | This section presents information that shows you how you can | ||
5565 | trim your distribution to even smaller sizes than the | ||
5566 | <filename>poky-tiny</filename> distribution, which is around | ||
5567 | 5 Mbytes, that can be built out-of-the-box using the Yocto Project. | ||
5568 | </para> | ||
5569 | |||
5570 | <section id='tiny-system-overview'> | ||
5571 | <title>Overview</title> | ||
5572 | |||
5573 | <para> | ||
5574 | The following list presents the overall steps you need to | ||
5575 | consider and perform to create distributions with smaller | ||
5576 | root filesystems, achieve faster boot times, maintain your critical | ||
5577 | functionality, and avoid initial RAM disks: | ||
5578 | <itemizedlist> | ||
5579 | <listitem><para> | ||
5580 | <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link> | ||
5581 | </para></listitem> | ||
5582 | <listitem><para> | ||
5583 | <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link> | ||
5584 | </para></listitem> | ||
5585 | <listitem><para> | ||
5586 | <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link> | ||
5587 | </para></listitem> | ||
5588 | <listitem><para> | ||
5589 | <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link> | ||
5590 | </para></listitem> | ||
5591 | <listitem><para> | ||
5592 | <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link> | ||
5593 | </para></listitem> | ||
5594 | <listitem><para> | ||
5595 | <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link> | ||
5596 | </para></listitem> | ||
5597 | <listitem><para> | ||
5598 | <link linkend='iterate-on-the-process'>Iterate on the process.</link> | ||
5599 | </para></listitem> | ||
5600 | </itemizedlist> | ||
5601 | </para> | ||
5602 | </section> | ||
5603 | |||
5604 | <section id='goals-and-guiding-principles'> | ||
5605 | <title>Goals and Guiding Principles</title> | ||
5606 | |||
5607 | <para> | ||
5608 | Before you can reach your destination, you need to know | ||
5609 | where you are going. | ||
5610 | Here is an example list that you can use as a guide when | ||
5611 | creating very small distributions: | ||
5612 | <itemizedlist> | ||
5613 | <listitem><para>Determine how much space you need | ||
5614 | (e.g. a kernel that is 1 Mbyte or less and | ||
5615 | a root filesystem that is 3 Mbytes or less). | ||
5616 | </para></listitem> | ||
5617 | <listitem><para>Find the areas that are currently | ||
5618 | taking 90% of the space and concentrate on reducing | ||
5619 | those areas. | ||
5620 | </para></listitem> | ||
5621 | <listitem><para>Do not create any difficult "hacks" | ||
5622 | to achieve your goals.</para></listitem> | ||
5623 | <listitem><para>Leverage the device-specific | ||
5624 | options.</para></listitem> | ||
5625 | <listitem><para>Work in a separate layer so that you | ||
5626 | keep changes isolated. | ||
5627 | For information on how to create layers, see | ||
5628 | the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section. | ||
5629 | </para></listitem> | ||
5630 | </itemizedlist> | ||
5631 | </para> | ||
5632 | </section> | ||
5633 | |||
5634 | <section id='understand-what-gives-your-image-size'> | ||
5635 | <title>Understand What Contributes to Your Image Size</title> | ||
5636 | |||
5637 | <para> | ||
5638 | It is easiest to have something to start with when creating | ||
5639 | your own distribution. | ||
5640 | You can use the Yocto Project out-of-the-box to create the | ||
5641 | <filename>poky-tiny</filename> distribution. | ||
5642 | Ultimately, you will want to make changes in your own | ||
5643 | distribution that are likely modeled after | ||
5644 | <filename>poky-tiny</filename>. | ||
5645 | <note> | ||
5646 | To use <filename>poky-tiny</filename> in your build, | ||
5647 | set the | ||
5648 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> | ||
5649 | variable in your | ||
5650 | <filename>local.conf</filename> file to "poky-tiny" | ||
5651 | as described in the | ||
5652 | "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" | ||
5653 | section. | ||
5654 | </note> | ||
5655 | </para> | ||
5656 | |||
5657 | <para> | ||
5658 | Understanding some memory concepts will help you reduce the | ||
5659 | system size. | ||
5660 | Memory consists of static, dynamic, and temporary memory. | ||
5661 | Static memory is the TEXT (code), DATA (initialized data | ||
5662 | in the code), and BSS (uninitialized data) sections. | ||
5663 | Dynamic memory represents memory that is allocated at runtime: | ||
5664 | stacks, hash tables, and so forth. | ||
5665 | Temporary memory is recovered after the boot process. | ||
5666 | This memory consists of memory used for decompressing | ||
5667 | the kernel and for the <filename>__init__</filename> | ||
5668 | functions. | ||
5669 | </para> | ||
5670 | |||
5671 | <para> | ||
5672 | To help you see where you currently are with kernel and root | ||
5673 | filesystem sizes, you can use two tools found in the | ||
5674 | <link linkend='source-directory'>Source Directory</link> in | ||
5675 | the <filename>scripts/tiny/</filename> directory: | ||
5676 | <itemizedlist> | ||
5677 | <listitem><para><filename>ksize.py</filename>: Reports | ||
5678 | component sizes for the kernel build objects. | ||
5679 | </para></listitem> | ||
5680 | <listitem><para><filename>dirsize.py</filename>: Reports | ||
5681 | component sizes for the root filesystem.</para></listitem> | ||
5682 | </itemizedlist> | ||
5683 | This next tool and command help you organize configuration | ||
5684 | fragments and view file dependencies in a human-readable form: | ||
5685 | <itemizedlist> | ||
5686 | <listitem><para><filename>merge_config.sh</filename>: | ||
5687 | Helps you manage configuration files and fragments | ||
5688 | within the kernel. | ||
5689 | With this tool, you can merge individual configuration | ||
5690 | fragments together. | ||
5691 | The tool allows you to make overrides and warns you | ||
5692 | of any missing configuration options. | ||
5693 | The tool is ideal for allowing you to iterate on | ||
5694 | configurations, create minimal configurations, and | ||
5695 | create configuration files for different machines | ||
5696 | without having to duplicate your process.</para> | ||
5697 | <para>The <filename>merge_config.sh</filename> script is | ||
5698 | part of the Linux Yocto kernel Git repositories | ||
5699 | (i.e. <filename>linux-yocto-3.14</filename>, | ||
5700 | <filename>linux-yocto-3.10</filename>, | ||
5701 | <filename>linux-yocto-3.8</filename>, and so forth) | ||
5702 | in the | ||
5703 | <filename>scripts/kconfig</filename> directory.</para> | ||
5704 | <para>For more information on configuration fragments, | ||
5705 | see the | ||
5706 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" | ||
5707 | section of the Yocto Project Linux Kernel Development | ||
5708 | Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" | ||
5709 | section, which is in this manual.</para></listitem> | ||
5710 | <listitem><para><filename>bitbake -u depexp -g <replaceable>bitbake_target</replaceable></filename>: | ||
5711 | Using the BitBake command with these options brings up | ||
5712 | a Dependency Explorer from which you can view file | ||
5713 | dependencies. | ||
5714 | Understanding these dependencies allows you to make | ||
5715 | informed decisions when cutting out various pieces of the | ||
5716 | kernel and root filesystem.</para></listitem> | ||
5717 | </itemizedlist> | ||
5718 | </para> | ||
5719 | </section> | ||
5720 | |||
5721 | <section id='trim-the-root-filesystem'> | ||
5722 | <title>Trim the Root Filesystem</title> | ||
5723 | |||
5724 | <para> | ||
5725 | The root filesystem is made up of packages for booting, | ||
5726 | libraries, and applications. | ||
5727 | To change things, you can configure how the packaging happens, | ||
5728 | which changes the way you build them. | ||
5729 | You can also modify the filesystem itself or select a different | ||
5730 | filesystem. | ||
5731 | </para> | ||
5732 | |||
5733 | <para> | ||
5734 | First, find out what is hogging your root filesystem by running the | ||
5735 | <filename>dirsize.py</filename> script from your root directory: | ||
5736 | <literallayout class='monospaced'> | ||
5737 | $ cd <replaceable>root-directory-of-image</replaceable> | ||
5738 | $ dirsize.py 100000 > dirsize-100k.log | ||
5739 | $ cat dirsize-100k.log | ||
5740 | </literallayout> | ||
5741 | You can apply a filter to the script to ignore files under | ||
5742 | a certain size. | ||
5743 | The previous example filters out any files below 100 Kbytes. | ||
5744 | The sizes reported by the tool are uncompressed, and thus | ||
5745 | will be smaller by a relatively constant factor in a | ||
5746 | compressed root filesystem. | ||
5747 | When you examine your log file, you can focus on areas of the | ||
5748 | root filesystem that take up large amounts of memory. | ||
5749 | </para> | ||
5750 | |||
5751 | <para> | ||
5752 | You need to be sure that what you eliminate does not cripple | ||
5753 | the functionality you need. | ||
5754 | One way to see how packages relate to each other is by using | ||
5755 | the Dependency Explorer UI with the BitBake command: | ||
5756 | <literallayout class='monospaced'> | ||
5757 | $ cd <replaceable>image-directory</replaceable> | ||
5758 | $ bitbake -u depexp -g <replaceable>image</replaceable> | ||
5759 | </literallayout> | ||
5760 | Use the interface to select potential packages you wish to | ||
5761 | eliminate and see their dependency relationships. | ||
5762 | </para> | ||
5763 | |||
5764 | <para> | ||
5765 | When deciding how to reduce the size, get rid of packages that | ||
5766 | result in minimal impact on the feature set. | ||
5767 | For example, you might not need a VGA display. | ||
5768 | Or, you might be able to get by with <filename>devtmpfs</filename> | ||
5769 | and <filename>mdev</filename> instead of | ||
5770 | <filename>udev</filename>. | ||
5771 | </para> | ||
5772 | |||
5773 | <para> | ||
5774 | Use your <filename>local.conf</filename> file to make changes. | ||
5775 | For example, to eliminate <filename>udev</filename> and | ||
5776 | <filename>glib</filename>, set the following in the | ||
5777 | local configuration file: | ||
5778 | <literallayout class='monospaced'> | ||
5779 | VIRTUAL-RUNTIME_dev_manager = "" | ||
5780 | </literallayout> | ||
5781 | </para> | ||
5782 | |||
5783 | <para> | ||
5784 | Finally, you should consider exactly the type of root | ||
5785 | filesystem you need to meet your needs while also reducing | ||
5786 | its size. | ||
5787 | For example, consider <filename>cramfs</filename>, | ||
5788 | <filename>squashfs</filename>, <filename>ubifs</filename>, | ||
5789 | <filename>ext2</filename>, or an <filename>initramfs</filename> | ||
5790 | using <filename>initramfs</filename>. | ||
5791 | Be aware that <filename>ext3</filename> requires a 1 Mbyte | ||
5792 | journal. | ||
5793 | If you are okay with running read-only, you do not need this | ||
5794 | journal. | ||
5795 | </para> | ||
5796 | |||
5797 | <note> | ||
5798 | After each round of elimination, you need to rebuild your | ||
5799 | system and then use the tools to see the effects of your | ||
5800 | reductions. | ||
5801 | </note> | ||
5802 | |||
5803 | |||
5804 | </section> | ||
5805 | |||
5806 | <section id='trim-the-kernel'> | ||
5807 | <title>Trim the Kernel</title> | ||
5808 | |||
5809 | <para> | ||
5810 | The kernel is built by including policies for hardware-independent | ||
5811 | aspects. | ||
5812 | What subsystems do you enable? | ||
5813 | For what architecture are you building? | ||
5814 | Which drivers do you build by default? | ||
5815 | <note>You can modify the kernel source if you want to help | ||
5816 | with boot time. | ||
5817 | </note> | ||
5818 | </para> | ||
5819 | |||
5820 | <para> | ||
5821 | Run the <filename>ksize.py</filename> script from the top-level | ||
5822 | Linux build directory to get an idea of what is making up | ||
5823 | the kernel: | ||
5824 | <literallayout class='monospaced'> | ||
5825 | $ cd <replaceable>top-level-linux-build-directory</replaceable> | ||
5826 | $ ksize.py > ksize.log | ||
5827 | $ cat ksize.log | ||
5828 | </literallayout> | ||
5829 | When you examine the log, you will see how much space is | ||
5830 | taken up with the built-in <filename>.o</filename> files for | ||
5831 | drivers, networking, core kernel files, filesystem, sound, | ||
5832 | and so forth. | ||
5833 | The sizes reported by the tool are uncompressed, and thus | ||
5834 | will be smaller by a relatively constant factor in a compressed | ||
5835 | kernel image. | ||
5836 | Look to reduce the areas that are large and taking up around | ||
5837 | the "90% rule." | ||
5838 | </para> | ||
5839 | |||
5840 | <para> | ||
5841 | To examine, or drill down, into any particular area, use the | ||
5842 | <filename>-d</filename> option with the script: | ||
5843 | <literallayout class='monospaced'> | ||
5844 | $ ksize.py -d > ksize.log | ||
5845 | </literallayout> | ||
5846 | Using this option breaks out the individual file information | ||
5847 | for each area of the kernel (e.g. drivers, networking, and | ||
5848 | so forth). | ||
5849 | </para> | ||
5850 | |||
5851 | <para> | ||
5852 | Use your log file to see what you can eliminate from the kernel | ||
5853 | based on features you can let go. | ||
5854 | For example, if you are not going to need sound, you do not | ||
5855 | need any drivers that support sound. | ||
5856 | </para> | ||
5857 | |||
5858 | <para> | ||
5859 | After figuring out what to eliminate, you need to reconfigure | ||
5860 | the kernel to reflect those changes during the next build. | ||
5861 | You could run <filename>menuconfig</filename> and make all your | ||
5862 | changes at once. | ||
5863 | However, that makes it difficult to see the effects of your | ||
5864 | individual eliminations and also makes it difficult to replicate | ||
5865 | the changes for perhaps another target device. | ||
5866 | A better method is to start with no configurations using | ||
5867 | <filename>allnoconfig</filename>, create configuration | ||
5868 | fragments for individual changes, and then manage the | ||
5869 | fragments into a single configuration file using | ||
5870 | <filename>merge_config.sh</filename>. | ||
5871 | The tool makes it easy for you to iterate using the | ||
5872 | configuration change and build cycle. | ||
5873 | </para> | ||
5874 | |||
5875 | <para> | ||
5876 | Each time you make configuration changes, you need to rebuild | ||
5877 | the kernel and check to see what impact your changes had on | ||
5878 | the overall size. | ||
5879 | </para> | ||
5880 | </section> | ||
5881 | |||
5882 | <section id='remove-package-management-requirements'> | ||
5883 | <title>Remove Package Management Requirements</title> | ||
5884 | |||
5885 | <para> | ||
5886 | Packaging requirements add size to the image. | ||
5887 | One way to reduce the size of the image is to remove all the | ||
5888 | packaging requirements from the image. | ||
5889 | This reduction includes both removing the package manager | ||
5890 | and its unique dependencies as well as removing the package | ||
5891 | management data itself. | ||
5892 | </para> | ||
5893 | |||
5894 | <para> | ||
5895 | To eliminate all the packaging requirements for an image, | ||
5896 | be sure that "package-management" is not part of your | ||
5897 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> | ||
5898 | statement for the image. | ||
5899 | When you remove this feature, you are removing the package | ||
5900 | manager as well as its dependencies from the root filesystem. | ||
5901 | </para> | ||
5902 | </section> | ||
5903 | |||
5904 | <section id='look-for-other-ways-to-minimize-size'> | ||
5905 | <title>Look for Other Ways to Minimize Size</title> | ||
5906 | |||
5907 | <para> | ||
5908 | Depending on your particular circumstances, other areas that you | ||
5909 | can trim likely exist. | ||
5910 | The key to finding these areas is through tools and methods | ||
5911 | described here combined with experimentation and iteration. | ||
5912 | Here are a couple of areas to experiment with: | ||
5913 | <itemizedlist> | ||
5914 | <listitem><para><filename>glibc</filename>: | ||
5915 | In general, follow this process: | ||
5916 | <orderedlist> | ||
5917 | <listitem><para>Remove <filename>glibc</filename> | ||
5918 | features from | ||
5919 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> | ||
5920 | that you think you do not need.</para></listitem> | ||
5921 | <listitem><para>Build your distribution. | ||
5922 | </para></listitem> | ||
5923 | <listitem><para>If the build fails due to missing | ||
5924 | symbols in a package, determine if you can | ||
5925 | reconfigure the package to not need those | ||
5926 | features. | ||
5927 | For example, change the configuration to not | ||
5928 | support wide character support as is done for | ||
5929 | <filename>ncurses</filename>. | ||
5930 | Or, if support for those characters is needed, | ||
5931 | determine what <filename>glibc</filename> | ||
5932 | features provide the support and restore the | ||
5933 | configuration. | ||
5934 | </para></listitem> | ||
5935 | <listitem><para>Rebuild and repeat the process. | ||
5936 | </para></listitem> | ||
5937 | </orderedlist></para></listitem> | ||
5938 | <listitem><para><filename>busybox</filename>: | ||
5939 | For BusyBox, use a process similar as described for | ||
5940 | <filename>glibc</filename>. | ||
5941 | A difference is you will need to boot the resulting | ||
5942 | system to see if you are able to do everything you | ||
5943 | expect from the running system. | ||
5944 | You need to be sure to integrate configuration fragments | ||
5945 | into Busybox because BusyBox handles its own core | ||
5946 | features and then allows you to add configuration | ||
5947 | fragments on top. | ||
5948 | </para></listitem> | ||
5949 | </itemizedlist> | ||
5950 | </para> | ||
5951 | </section> | ||
5952 | |||
5953 | <section id='iterate-on-the-process'> | ||
5954 | <title>Iterate on the Process</title> | ||
5955 | |||
5956 | <para> | ||
5957 | If you have not reached your goals on system size, you need | ||
5958 | to iterate on the process. | ||
5959 | The process is the same. | ||
5960 | Use the tools and see just what is taking up 90% of the root | ||
5961 | filesystem and the kernel. | ||
5962 | Decide what you can eliminate without limiting your device | ||
5963 | beyond what you need. | ||
5964 | </para> | ||
5965 | |||
5966 | <para> | ||
5967 | Depending on your system, a good place to look might be | ||
5968 | Busybox, which provides a stripped down | ||
5969 | version of Unix tools in a single, executable file. | ||
5970 | You might be able to drop virtual terminal services or perhaps | ||
5971 | ipv6. | ||
5972 | </para> | ||
5973 | </section> | ||
5974 | </section> | ||
5975 | |||
5976 | <section id='working-with-packages'> | ||
5977 | <title>Working with Packages</title> | ||
5978 | |||
5979 | <para> | ||
5980 | This section describes a few tasks that involve packages: | ||
5981 | <itemizedlist> | ||
5982 | <listitem><para> | ||
5983 | <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link> | ||
5984 | </para></listitem> | ||
5985 | <listitem><para> | ||
5986 | <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link> | ||
5987 | </para></listitem> | ||
5988 | <listitem><para> | ||
5989 | <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link> | ||
5990 | </para></listitem> | ||
5991 | <listitem><para> | ||
5992 | <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> | ||
5993 | </para></listitem> | ||
5994 | <listitem><para> | ||
5995 | <link linkend='using-runtime-package-management'>Using Runtime Package Management</link> | ||
5996 | </para></listitem> | ||
5997 | <listitem><para> | ||
5998 | <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link> | ||
5999 | </para></listitem> | ||
6000 | </itemizedlist> | ||
6001 | </para> | ||
6002 | |||
6003 | <section id='excluding-packages-from-an-image'> | ||
6004 | <title>Excluding Packages from an Image</title> | ||
6005 | |||
6006 | <para> | ||
6007 | You might find it necessary to prevent specific packages | ||
6008 | from being installed into an image. | ||
6009 | If so, you can use several variables to direct the build | ||
6010 | system to essentially ignore installing recommended packages | ||
6011 | or to not install a package at all. | ||
6012 | </para> | ||
6013 | |||
6014 | <para> | ||
6015 | The following list introduces variables you can use to | ||
6016 | prevent packages from being installed into your image. | ||
6017 | Each of these variables only works with IPK and RPM | ||
6018 | package types. | ||
6019 | Support for Debian packages does not exist. | ||
6020 | Also, you can use these variables from your | ||
6021 | <filename>local.conf</filename> file or attach them to a | ||
6022 | specific image recipe by using a recipe name override. | ||
6023 | For more detail on the variables, see the descriptions in the | ||
6024 | Yocto Project Reference Manual's glossary chapter. | ||
6025 | <itemizedlist> | ||
6026 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>: | ||
6027 | Use this variable to specify "recommended-only" | ||
6028 | packages that you do not want installed. | ||
6029 | </para></listitem> | ||
6030 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>: | ||
6031 | Use this variable to prevent all "recommended-only" | ||
6032 | packages from being installed. | ||
6033 | </para></listitem> | ||
6034 | <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>: | ||
6035 | Use this variable to prevent specific packages from | ||
6036 | being installed regardless of whether they are | ||
6037 | "recommended-only" or not. | ||
6038 | You need to realize that the build process could | ||
6039 | fail with an error when you | ||
6040 | prevent the installation of a package whose presence | ||
6041 | is required by an installed package. | ||
6042 | </para></listitem> | ||
6043 | </itemizedlist> | ||
6044 | </para> | ||
6045 | </section> | ||
6046 | |||
6047 | <section id='incrementing-a-package-revision-number'> | ||
6048 | <title>Incrementing a Package Revision Number</title> | ||
6049 | |||
6050 | <para> | ||
6051 | If a committed change results in changing the package output, | ||
6052 | then the value of the | ||
6053 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
6054 | variable needs to be increased (or "bumped"). | ||
6055 | Increasing <filename>PR</filename> occurs one of two ways: | ||
6056 | <itemizedlist> | ||
6057 | <listitem><para>Automatically using a Package Revision | ||
6058 | Service (PR Service).</para></listitem> | ||
6059 | <listitem><para>Manually incrementing the | ||
6060 | <filename>PR</filename> variable.</para></listitem> | ||
6061 | </itemizedlist> | ||
6062 | </para> | ||
6063 | |||
6064 | <para> | ||
6065 | Given that one of the challenges any build system and its | ||
6066 | users face is how to maintain a package feed that is compatible | ||
6067 | with existing package manager applications such as | ||
6068 | RPM, APT, and OPKG, using an automated system is much | ||
6069 | preferred over a manual system. | ||
6070 | In either system, the main requirement is that version | ||
6071 | numbering increases in a linear fashion and that a number of | ||
6072 | version components exist that support that linear progression. | ||
6073 | </para> | ||
6074 | |||
6075 | <para> | ||
6076 | The following two sections provide information on the PR Service | ||
6077 | and on manual <filename>PR</filename> bumping. | ||
6078 | </para> | ||
6079 | |||
6080 | <section id='working-with-a-pr-service'> | ||
6081 | <title>Working With a PR Service</title> | ||
6082 | |||
6083 | <para> | ||
6084 | As mentioned, attempting to maintain revision numbers in the | ||
6085 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | ||
6086 | is error prone, inaccurate, and causes problems for people | ||
6087 | submitting recipes. | ||
6088 | Conversely, the PR Service automatically generates | ||
6089 | increasing numbers, particularly the revision field, | ||
6090 | which removes the human element. | ||
6091 | <note> | ||
6092 | For additional information on using a PR Service, you | ||
6093 | can see the | ||
6094 | <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink> | ||
6095 | wiki page. | ||
6096 | </note> | ||
6097 | </para> | ||
6098 | |||
6099 | <para> | ||
6100 | The Yocto Project uses variables in order of | ||
6101 | decreasing priority to facilitate revision numbering (i.e. | ||
6102 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>, | ||
6103 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and | ||
6104 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
6105 | for epoch, version, and revision, respectively). | ||
6106 | The values are highly dependent on the policies and | ||
6107 | procedures of a given distribution and package feed. | ||
6108 | </para> | ||
6109 | |||
6110 | <para> | ||
6111 | Because the OpenEmbedded build system uses | ||
6112 | "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>", | ||
6113 | which are unique to a given build, the build system | ||
6114 | knows when to rebuild packages. | ||
6115 | All the inputs into a given task are represented by a | ||
6116 | signature, which can trigger a rebuild when different. | ||
6117 | Thus, the build system itself does not rely on the | ||
6118 | <filename>PR</filename> numbers to trigger a rebuild. | ||
6119 | The signatures, however, can be used to generate | ||
6120 | <filename>PR</filename> values. | ||
6121 | </para> | ||
6122 | |||
6123 | <para> | ||
6124 | The PR Service works with both | ||
6125 | <filename>OEBasic</filename> and | ||
6126 | <filename>OEBasicHash</filename> generators. | ||
6127 | The value of <filename>PR</filename> bumps when the | ||
6128 | checksum changes and the different generator mechanisms | ||
6129 | change signatures under different circumstances. | ||
6130 | </para> | ||
6131 | |||
6132 | <para> | ||
6133 | As implemented, the build system includes values from | ||
6134 | the PR Service into the <filename>PR</filename> field as | ||
6135 | an addition using the form "<filename>.x</filename>" so | ||
6136 | <filename>r0</filename> becomes <filename>r0.1</filename>, | ||
6137 | <filename>r0.2</filename> and so forth. | ||
6138 | This scheme allows existing <filename>PR</filename> values | ||
6139 | to be used for whatever reasons, which include manual | ||
6140 | <filename>PR</filename> bumps, should it be necessary. | ||
6141 | </para> | ||
6142 | |||
6143 | <para> | ||
6144 | By default, the PR Service is not enabled or running. | ||
6145 | Thus, the packages generated are just "self consistent". | ||
6146 | The build system adds and removes packages and | ||
6147 | there are no guarantees about upgrade paths but images | ||
6148 | will be consistent and correct with the latest changes. | ||
6149 | </para> | ||
6150 | |||
6151 | <para> | ||
6152 | The simplest form for a PR Service is for it to exist | ||
6153 | for a single host development system that builds the | ||
6154 | package feed (building system). | ||
6155 | For this scenario, you can enable a local PR Service by | ||
6156 | setting | ||
6157 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink> | ||
6158 | in your <filename>local.conf</filename> file in the | ||
6159 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
6160 | <literallayout class='monospaced'> | ||
6161 | PRSERV_HOST = "localhost:0" | ||
6162 | </literallayout> | ||
6163 | Once the service is started, packages will automatically | ||
6164 | get increasing <filename>PR</filename> values and | ||
6165 | BitBake will take care of starting and stopping the server. | ||
6166 | </para> | ||
6167 | |||
6168 | <para> | ||
6169 | If you have a more complex setup where multiple host | ||
6170 | development systems work against a common, shared package | ||
6171 | feed, you have a single PR Service running and it is | ||
6172 | connected to each building system. | ||
6173 | For this scenario, you need to start the PR Service using | ||
6174 | the <filename>bitbake-prserv</filename> command: | ||
6175 | <literallayout class='monospaced'> | ||
6176 | bitbake-prserv ‐‐host <replaceable>ip</replaceable> ‐‐port <replaceable>port</replaceable> ‐‐start | ||
6177 | </literallayout> | ||
6178 | In addition to hand-starting the service, you need to | ||
6179 | update the <filename>local.conf</filename> file of each | ||
6180 | building system as described earlier so each system | ||
6181 | points to the server and port. | ||
6182 | </para> | ||
6183 | |||
6184 | <para> | ||
6185 | It is also recommended you use build history, which adds | ||
6186 | some sanity checks to package versions, in conjunction with | ||
6187 | the server that is running the PR Service. | ||
6188 | To enable build history, add the following to each building | ||
6189 | system's <filename>local.conf</filename> file: | ||
6190 | <literallayout class='monospaced'> | ||
6191 | # It is recommended to activate "buildhistory" for testing the PR service | ||
6192 | INHERIT += "buildhistory" | ||
6193 | BUILDHISTORY_COMMIT = "1" | ||
6194 | </literallayout> | ||
6195 | For information on build history, see the | ||
6196 | "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" | ||
6197 | section in the Yocto Project Reference Manual. | ||
6198 | </para> | ||
6199 | |||
6200 | <note> | ||
6201 | <para>The OpenEmbedded build system does not maintain | ||
6202 | <filename>PR</filename> information as part of the | ||
6203 | shared state (sstate) packages. | ||
6204 | If you maintain an sstate feed, its expected that either | ||
6205 | all your building systems that contribute to the sstate | ||
6206 | feed use a shared PR Service, or you do not run a PR | ||
6207 | Service on any of your building systems. | ||
6208 | Having some systems use a PR Service while others do | ||
6209 | not leads to obvious problems.</para> | ||
6210 | <para>For more information on shared state, see the | ||
6211 | "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" | ||
6212 | section in the Yocto Project Reference Manual.</para> | ||
6213 | </note> | ||
6214 | </section> | ||
6215 | |||
6216 | <section id='manually-bumping-pr'> | ||
6217 | <title>Manually Bumping PR</title> | ||
6218 | |||
6219 | <para> | ||
6220 | The alternative to setting up a PR Service is to manually | ||
6221 | bump the | ||
6222 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
6223 | variable. | ||
6224 | </para> | ||
6225 | |||
6226 | <para> | ||
6227 | If a committed change results in changing the package output, | ||
6228 | then the value of the PR variable needs to be increased | ||
6229 | (or "bumped") as part of that commit. | ||
6230 | For new recipes you should add the <filename>PR</filename> | ||
6231 | variable and set its initial value equal to "r0", which is the default. | ||
6232 | Even though the default value is "r0", the practice of adding it to a new recipe makes | ||
6233 | it harder to forget to bump the variable when you make changes | ||
6234 | to the recipe in future. | ||
6235 | </para> | ||
6236 | |||
6237 | <para> | ||
6238 | If you are sharing a common <filename>.inc</filename> file with multiple recipes, | ||
6239 | you can also use the | ||
6240 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename> | ||
6241 | variable to ensure that | ||
6242 | the recipes sharing the <filename>.inc</filename> file are rebuilt when the | ||
6243 | <filename>.inc</filename> file itself is changed. | ||
6244 | The <filename>.inc</filename> file must set <filename>INC_PR</filename> | ||
6245 | (initially to "r0"), and all recipes referring to it should set <filename>PR</filename> | ||
6246 | to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. | ||
6247 | If the <filename>.inc</filename> file is changed then its | ||
6248 | <filename>INC_PR</filename> should be incremented. | ||
6249 | </para> | ||
6250 | |||
6251 | <para> | ||
6252 | When upgrading the version of a package, assuming the | ||
6253 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> | ||
6254 | changes, the <filename>PR</filename> variable should be | ||
6255 | reset to "r0" (or "$(INC_PR).0" if you are using | ||
6256 | <filename>INC_PR</filename>). | ||
6257 | </para> | ||
6258 | |||
6259 | <para> | ||
6260 | Usually, version increases occur only to packages. | ||
6261 | However, if for some reason <filename>PV</filename> changes but does not | ||
6262 | increase, you can increase the | ||
6263 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> | ||
6264 | variable (Package Epoch). | ||
6265 | The <filename>PE</filename> variable defaults to "0". | ||
6266 | </para> | ||
6267 | |||
6268 | <para> | ||
6269 | Version numbering strives to follow the | ||
6270 | <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> | ||
6271 | Debian Version Field Policy Guidelines</ulink>. | ||
6272 | These guidelines define how versions are compared and what "increasing" a version means. | ||
6273 | </para> | ||
6274 | </section> | ||
6275 | </section> | ||
6276 | |||
6277 | <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> | ||
6278 | <title>Handling a Package Name Alias</title> | ||
6279 | <para> | ||
6280 | Sometimes a package name you are using might exist under | ||
6281 | an alias or as a similarly named package in a different | ||
6282 | distribution. | ||
6283 | The OpenEmbedded build system implements a | ||
6284 | <filename>do_distro_check</filename> | ||
6285 | task that automatically connects to major distributions | ||
6286 | and checks for these situations. | ||
6287 | If the package exists under a different name in a different | ||
6288 | distribution, you get a <filename>distro_check</filename> | ||
6289 | mismatch. | ||
6290 | You can resolve this problem by defining a per-distro recipe | ||
6291 | name alias using the | ||
6292 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename> | ||
6293 | variable. | ||
6294 | </para> | ||
6295 | |||
6296 | <para> | ||
6297 | Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename> | ||
6298 | variable: | ||
6299 | <literallayout class='monospaced'> | ||
6300 | DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ | ||
6301 | distro2=package_name_alias2 \ | ||
6302 | distro3=package_name_alias3 \ | ||
6303 | ..." | ||
6304 | </literallayout> | ||
6305 | </para> | ||
6306 | |||
6307 | <para> | ||
6308 | If you have more than one distribution alias, separate them with a space. | ||
6309 | Note that the build system currently automatically checks the | ||
6310 | Fedora, OpenSUSE, Debian, Ubuntu, | ||
6311 | and Mandriva distributions for source package recipes without having to specify them | ||
6312 | using the <filename>DISTRO_PN_ALIAS</filename> variable. | ||
6313 | For example, the following command generates a report that lists the Linux distributions | ||
6314 | that include the sources for each of the recipes. | ||
6315 | <literallayout class='monospaced'> | ||
6316 | $ bitbake world -f -c distro_check | ||
6317 | </literallayout> | ||
6318 | The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> | ||
6319 | file found in the | ||
6320 | <link linkend='source-directory'>Source Directory</link>. | ||
6321 | </para> | ||
6322 | </section> | ||
6323 | |||
6324 | <section id='handling-optional-module-packaging'> | ||
6325 | <title>Handling Optional Module Packaging</title> | ||
6326 | |||
6327 | <para> | ||
6328 | Many pieces of software split functionality into optional | ||
6329 | modules (or plug-ins) and the plug-ins that are built | ||
6330 | might depend on configuration options. | ||
6331 | To avoid having to duplicate the logic that determines what | ||
6332 | modules are available in your recipe or to avoid having | ||
6333 | to package each module by hand, the OpenEmbedded build system | ||
6334 | provides functionality to handle module packaging dynamically. | ||
6335 | </para> | ||
6336 | |||
6337 | <para> | ||
6338 | To handle optional module packaging, you need to do two things: | ||
6339 | <itemizedlist> | ||
6340 | <listitem><para>Ensure the module packaging is actually | ||
6341 | done.</para></listitem> | ||
6342 | <listitem><para>Ensure that any dependencies on optional | ||
6343 | modules from other recipes are satisfied by your recipe. | ||
6344 | </para></listitem> | ||
6345 | </itemizedlist> | ||
6346 | </para> | ||
6347 | |||
6348 | <section id='making-sure-the-packaging-is-done'> | ||
6349 | <title>Making Sure the Packaging is Done</title> | ||
6350 | |||
6351 | <para> | ||
6352 | To ensure the module packaging actually gets done, you use | ||
6353 | the <filename>do_split_packages</filename> function within | ||
6354 | the <filename>populate_packages</filename> Python function | ||
6355 | in your recipe. | ||
6356 | The <filename>do_split_packages</filename> function | ||
6357 | searches for a pattern of files or directories under a | ||
6358 | specified path and creates a package for each one it finds | ||
6359 | by appending to the | ||
6360 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> | ||
6361 | variable and setting the appropriate values for | ||
6362 | <filename>FILES_packagename</filename>, | ||
6363 | <filename>RDEPENDS_packagename</filename>, | ||
6364 | <filename>DESCRIPTION_packagename</filename>, and so forth. | ||
6365 | Here is an example from the <filename>lighttpd</filename> | ||
6366 | recipe: | ||
6367 | <literallayout class='monospaced'> | ||
6368 | python populate_packages_prepend () { | ||
6369 | lighttpd_libdir = d.expand('${libdir}') | ||
6370 | do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$', | ||
6371 | 'lighttpd-module-%s', 'Lighttpd module for %s', | ||
6372 | extra_depends='') | ||
6373 | } | ||
6374 | </literallayout> | ||
6375 | The previous example specifies a number of things in the | ||
6376 | call to <filename>do_split_packages</filename>. | ||
6377 | <itemizedlist> | ||
6378 | <listitem><para>A directory within the files installed | ||
6379 | by your recipe through <filename>do_install</filename> | ||
6380 | in which to search.</para></listitem> | ||
6381 | <listitem><para>A regular expression used to match module | ||
6382 | files in that directory. | ||
6383 | In the example, note the parentheses () that mark | ||
6384 | the part of the expression from which the module | ||
6385 | name should be derived.</para></listitem> | ||
6386 | <listitem><para>A pattern to use for the package names. | ||
6387 | </para></listitem> | ||
6388 | <listitem><para>A description for each package. | ||
6389 | </para></listitem> | ||
6390 | <listitem><para>An empty string for | ||
6391 | <filename>extra_depends</filename>, which disables | ||
6392 | the default dependency on the main | ||
6393 | <filename>lighttpd</filename> package. | ||
6394 | Thus, if a file in <filename>${libdir}</filename> | ||
6395 | called <filename>mod_alias.so</filename> is found, | ||
6396 | a package called <filename>lighttpd-module-alias</filename> | ||
6397 | is created for it and the | ||
6398 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> | ||
6399 | is set to "Lighttpd module for alias".</para></listitem> | ||
6400 | </itemizedlist> | ||
6401 | </para> | ||
6402 | |||
6403 | <para> | ||
6404 | Often, packaging modules is as simple as the previous | ||
6405 | example. | ||
6406 | However, more advanced options exist that you can use | ||
6407 | within <filename>do_split_packages</filename> to modify its | ||
6408 | behavior. | ||
6409 | And, if you need to, you can add more logic by specifying | ||
6410 | a hook function that is called for each package. | ||
6411 | It is also perfectly acceptable to call | ||
6412 | <filename>do_split_packages</filename> multiple times if | ||
6413 | you have more than one set of modules to package. | ||
6414 | </para> | ||
6415 | |||
6416 | <para> | ||
6417 | For more examples that show how to use | ||
6418 | <filename>do_split_packages</filename>, see the | ||
6419 | <filename>connman.inc</filename> file in the | ||
6420 | <filename>meta/recipes-connectivity/connman/</filename> | ||
6421 | directory of the <filename>poky</filename> | ||
6422 | <link linkend='yocto-project-repositories'>source repository</link>. | ||
6423 | You can also find examples in | ||
6424 | <filename>meta/classes/kernel.bbclass</filename>. | ||
6425 | </para> | ||
6426 | |||
6427 | <para> | ||
6428 | Following is a reference that shows | ||
6429 | <filename>do_split_packages</filename> mandatory and | ||
6430 | optional arguments: | ||
6431 | <literallayout class='monospaced'> | ||
6432 | Mandatory arguments | ||
6433 | |||
6434 | root | ||
6435 | The path in which to search | ||
6436 | file_regex | ||
6437 | Regular expression to match searched files. | ||
6438 | Use parentheses () to mark the part of this | ||
6439 | expression that should be used to derive the | ||
6440 | module name (to be substituted where %s is | ||
6441 | used in other function arguments as noted below) | ||
6442 | output_pattern | ||
6443 | Pattern to use for the package names. Must | ||
6444 | include %s. | ||
6445 | description | ||
6446 | Description to set for each package. Must | ||
6447 | include %s. | ||
6448 | |||
6449 | Optional arguments | ||
6450 | |||
6451 | postinst | ||
6452 | Postinstall script to use for all packages | ||
6453 | (as a string) | ||
6454 | recursive | ||
6455 | True to perform a recursive search - default | ||
6456 | False | ||
6457 | hook | ||
6458 | A hook function to be called for every match. | ||
6459 | The function will be called with the following | ||
6460 | arguments (in the order listed): | ||
6461 | |||
6462 | f | ||
6463 | Full path to the file/directory match | ||
6464 | pkg | ||
6465 | The package name | ||
6466 | file_regex | ||
6467 | As above | ||
6468 | output_pattern | ||
6469 | As above | ||
6470 | modulename | ||
6471 | The module name derived using file_regex | ||
6472 | |||
6473 | extra_depends | ||
6474 | Extra runtime dependencies (RDEPENDS) to be | ||
6475 | set for all packages. The default value of None | ||
6476 | causes a dependency on the main package | ||
6477 | (${PN}) - if you do not want this, pass empty | ||
6478 | string '' for this parameter. | ||
6479 | aux_files_pattern | ||
6480 | Extra item(s) to be added to FILES for each | ||
6481 | package. Can be a single string item or a list | ||
6482 | of strings for multiple items. Must include %s. | ||
6483 | postrm | ||
6484 | postrm script to use for all packages (as a | ||
6485 | string) | ||
6486 | allow_dirs | ||
6487 | True to allow directories to be matched - | ||
6488 | default False | ||
6489 | prepend | ||
6490 | If True, prepend created packages to PACKAGES | ||
6491 | instead of the default False which appends them | ||
6492 | match_path | ||
6493 | match file_regex on the whole relative path to | ||
6494 | the root rather than just the file name | ||
6495 | aux_files_pattern_verbatim | ||
6496 | Extra item(s) to be added to FILES for each | ||
6497 | package, using the actual derived module name | ||
6498 | rather than converting it to something legal | ||
6499 | for a package name. Can be a single string item | ||
6500 | or a list of strings for multiple items. Must | ||
6501 | include %s. | ||
6502 | allow_links | ||
6503 | True to allow symlinks to be matched - default | ||
6504 | False | ||
6505 | summary | ||
6506 | Summary to set for each package. Must include %s; | ||
6507 | defaults to description if not set. | ||
6508 | </literallayout> | ||
6509 | </para> | ||
6510 | </section> | ||
6511 | |||
6512 | <section id='satisfying-dependencies'> | ||
6513 | <title>Satisfying Dependencies</title> | ||
6514 | |||
6515 | <para> | ||
6516 | The second part for handling optional module packaging | ||
6517 | is to ensure that any dependencies on optional modules | ||
6518 | from other recipes are satisfied by your recipe. | ||
6519 | You can be sure these dependencies are satisfied by | ||
6520 | using the | ||
6521 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable. | ||
6522 | Here is an example that continues with the | ||
6523 | <filename>lighttpd</filename> recipe shown earlier: | ||
6524 | <literallayout class='monospaced'> | ||
6525 | PACKAGES_DYNAMIC = "lighttpd-module-.*" | ||
6526 | </literallayout> | ||
6527 | The name specified in the regular expression can of | ||
6528 | course be anything. | ||
6529 | In this example, it is <filename>lighttpd-module-</filename> | ||
6530 | and is specified as the prefix to ensure that any | ||
6531 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> | ||
6532 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> | ||
6533 | on a package name starting with the prefix are satisfied | ||
6534 | during build time. | ||
6535 | If you are using <filename>do_split_packages</filename> | ||
6536 | as described in the previous section, the value you put in | ||
6537 | <filename>PACKAGES_DYNAMIC</filename> should correspond to | ||
6538 | the name pattern specified in the call to | ||
6539 | <filename>do_split_packages</filename>. | ||
6540 | </para> | ||
6541 | </section> | ||
6542 | </section> | ||
6543 | |||
6544 | <section id='using-runtime-package-management'> | ||
6545 | <title>Using Runtime Package Management</title> | ||
6546 | |||
6547 | <para> | ||
6548 | During a build, BitBake always transforms a recipe into one or | ||
6549 | more packages. | ||
6550 | For example, BitBake takes the <filename>bash</filename> recipe | ||
6551 | and currently produces the <filename>bash-dbg</filename>, | ||
6552 | <filename>bash-staticdev</filename>, | ||
6553 | <filename>bash-dev</filename>, <filename>bash-doc</filename>, | ||
6554 | <filename>bash-locale</filename>, and | ||
6555 | <filename>bash</filename> packages. | ||
6556 | Not all generated packages are included in an image. | ||
6557 | </para> | ||
6558 | |||
6559 | <para> | ||
6560 | In several situations, you might need to update, add, remove, | ||
6561 | or query the packages on a target device at runtime | ||
6562 | (i.e. without having to generate a new image). | ||
6563 | Examples of such situations include: | ||
6564 | <itemizedlist> | ||
6565 | <listitem><para> | ||
6566 | You want to provide in-the-field updates to deployed | ||
6567 | devices (e.g. security updates). | ||
6568 | </para></listitem> | ||
6569 | <listitem><para> | ||
6570 | You want to have a fast turn-around development cycle | ||
6571 | for one or more applications that run on your device. | ||
6572 | </para></listitem> | ||
6573 | <listitem><para> | ||
6574 | You want to temporarily install the "debug" packages | ||
6575 | of various applications on your device so that | ||
6576 | debugging can be greatly improved by allowing | ||
6577 | access to symbols and source debugging. | ||
6578 | </para></listitem> | ||
6579 | <listitem><para> | ||
6580 | You want to deploy a more minimal package selection of | ||
6581 | your device but allow in-the-field updates to add a | ||
6582 | larger selection for customization. | ||
6583 | </para></listitem> | ||
6584 | </itemizedlist> | ||
6585 | </para> | ||
6586 | |||
6587 | <para> | ||
6588 | In all these situations, you have something similar to a more | ||
6589 | traditional Linux distribution in that in-field devices | ||
6590 | are able to receive pre-compiled packages from a server for | ||
6591 | installation or update. | ||
6592 | Being able to install these packages on a running, | ||
6593 | in-field device is what is termed "runtime package | ||
6594 | management". | ||
6595 | </para> | ||
6596 | |||
6597 | <para> | ||
6598 | In order to use runtime package management, you | ||
6599 | need a host/server machine that serves up the pre-compiled | ||
6600 | packages plus the required metadata. | ||
6601 | You also need package manipulation tools on the target. | ||
6602 | The build machine is a likely candidate to act as the server. | ||
6603 | However, that machine does not necessarily have to be the | ||
6604 | package server. | ||
6605 | The build machine could push its artifacts to another machine | ||
6606 | that acts as the server (e.g. Internet-facing). | ||
6607 | </para> | ||
6608 | |||
6609 | <para> | ||
6610 | A simple build that targets just one device produces | ||
6611 | more than one package database. | ||
6612 | In other words, the packages produced by a build are separated | ||
6613 | out into a couple of different package groupings based on | ||
6614 | criteria such as the target's CPU architecture, the target | ||
6615 | board, or the C library used on the target. | ||
6616 | For example, a build targeting the <filename>qemuarm</filename> | ||
6617 | device produces the following three package databases: | ||
6618 | <filename>all</filename>, <filename>armv5te</filename>, and | ||
6619 | <filename>qemuarm</filename>. | ||
6620 | If you wanted your <filename>qemuarm</filename> device to be | ||
6621 | aware of all the packages that were available to it, | ||
6622 | you would need to point it to each of these databases | ||
6623 | individually. | ||
6624 | In a similar way, a traditional Linux distribution usually is | ||
6625 | configured to be aware of a number of software repositories | ||
6626 | from which it retrieves packages. | ||
6627 | </para> | ||
6628 | |||
6629 | <para> | ||
6630 | Using runtime package management is completely optional and | ||
6631 | not required for a successful build or deployment in any | ||
6632 | way. | ||
6633 | But if you want to make use of runtime package management, | ||
6634 | you need to do a couple things above and beyond the basics. | ||
6635 | The remainder of this section describes what you need to do. | ||
6636 | </para> | ||
6637 | |||
6638 | <section id='runtime-package-management-build'> | ||
6639 | <title>Build Considerations</title> | ||
6640 | |||
6641 | <para> | ||
6642 | This section describes build considerations that you need | ||
6643 | to be aware of in order to provide support for runtime | ||
6644 | package management. | ||
6645 | </para> | ||
6646 | |||
6647 | <para> | ||
6648 | When BitBake generates packages it needs to know | ||
6649 | what format or formats to use. | ||
6650 | In your configuration, you use the | ||
6651 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> | ||
6652 | variable to specify the format. | ||
6653 | <note> | ||
6654 | You can choose to have more than one format but you must | ||
6655 | provide at least one. | ||
6656 | </note> | ||
6657 | </para> | ||
6658 | |||
6659 | <para> | ||
6660 | If you would like your image to start off with a basic | ||
6661 | package database of the packages in your current build | ||
6662 | as well as have the relevant tools available on the | ||
6663 | target for runtime package management, you can include | ||
6664 | "package-management" in the | ||
6665 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> | ||
6666 | variable. | ||
6667 | Including "package-management" in this | ||
6668 | configuration variable ensures that when the image | ||
6669 | is assembled for your target, the image includes | ||
6670 | the currently-known package databases as well as | ||
6671 | the target-specific tools required for runtime | ||
6672 | package management to be performed on the target. | ||
6673 | However, this is not strictly necessary. | ||
6674 | You could start your image off without any databases | ||
6675 | but only include the required on-target package | ||
6676 | tool(s). | ||
6677 | As an example, you could include "opkg" in your | ||
6678 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> | ||
6679 | variable if you are using the IPK package format. | ||
6680 | You can then initialize your target's package database(s) | ||
6681 | later once your image is up and running. | ||
6682 | </para> | ||
6683 | |||
6684 | <para> | ||
6685 | Whenever you perform any sort of build step that can | ||
6686 | potentially generate a package or modify an existing | ||
6687 | package, it is always a good idea to re-generate the | ||
6688 | package index with: | ||
6689 | <literallayout class='monospaced'> | ||
6690 | $ bitbake package-index | ||
6691 | </literallayout> | ||
6692 | Realize that it is not sufficient to simply do the | ||
6693 | following: | ||
6694 | <literallayout class='monospaced'> | ||
6695 | $ bitbake <replaceable>some-package</replaceable> package-index | ||
6696 | </literallayout> | ||
6697 | This is because BitBake does not properly schedule the | ||
6698 | <filename>package-index</filename> target fully after any | ||
6699 | other target has completed. | ||
6700 | Thus, be sure to run the package update step separately. | ||
6701 | </para> | ||
6702 | |||
6703 | <para> | ||
6704 | As described below in the | ||
6705 | "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>" | ||
6706 | section, if you are using IPK as your package format, you | ||
6707 | can make use of the | ||
6708 | <filename>distro-feed-configs</filename> recipe provided | ||
6709 | by <filename>meta-oe</filename> in order to configure your | ||
6710 | target to use your IPK databases. | ||
6711 | </para> | ||
6712 | |||
6713 | <para> | ||
6714 | When your build is complete, your packages reside in the | ||
6715 | <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> | ||
6716 | directory. | ||
6717 | For example, if <filename>${TMPDIR}</filename> | ||
6718 | is <filename>tmp</filename> and your selected package type | ||
6719 | is IPK, then your IPK packages are available in | ||
6720 | <filename>tmp/deploy/ipk</filename>. | ||
6721 | </para> | ||
6722 | </section> | ||
6723 | |||
6724 | <section id='runtime-package-management-server'> | ||
6725 | <title>Host or Server Machine Setup</title> | ||
6726 | |||
6727 | <para> | ||
6728 | Typically, packages are served from a server using | ||
6729 | HTTP. | ||
6730 | However, other protocols are possible. | ||
6731 | If you want to use HTTP, then setup and configure a | ||
6732 | web server, such as Apache 2 or lighttpd, on the machine | ||
6733 | serving the packages. | ||
6734 | </para> | ||
6735 | |||
6736 | <para> | ||
6737 | As previously mentioned, the build machine can act as the | ||
6738 | package server. | ||
6739 | In the following sections that describe server machine | ||
6740 | setups, the build machine is assumed to also be the server. | ||
6741 | </para> | ||
6742 | |||
6743 | <section id='package-server-apache'> | ||
6744 | <title>Serving Packages via Apache 2</title> | ||
6745 | |||
6746 | <para> | ||
6747 | This example assumes you are using the Apache 2 | ||
6748 | server: | ||
6749 | <orderedlist> | ||
6750 | <listitem><para> | ||
6751 | Add the directory to your Apache | ||
6752 | configuration, which you can find at | ||
6753 | <filename>/etc/httpd/conf/httpd.conf</filename>. | ||
6754 | Use commands similar to these on the | ||
6755 | development system. | ||
6756 | These example commands assume a top-level | ||
6757 | <link linkend='source-directory'>Source Directory</link> | ||
6758 | named <filename>poky</filename> in your home | ||
6759 | directory. | ||
6760 | The example also assumes an RPM package type. | ||
6761 | If you are using a different package type, such | ||
6762 | as IPK, use "ipk" in the pathnames: | ||
6763 | <literallayout class='monospaced'> | ||
6764 | <VirtualHost *:80> | ||
6765 | .... | ||
6766 | Alias /rpm ~/poky/build/tmp/deploy/rpm | ||
6767 | <Directory "~/poky/build/tmp/deploy/rpm"> | ||
6768 | Options +Indexes | ||
6769 | </Directory> | ||
6770 | </VirtualHost> | ||
6771 | </literallayout></para></listitem> | ||
6772 | <listitem><para> | ||
6773 | Reload the Apache configuration as described | ||
6774 | in this step. | ||
6775 | For all commands, be sure you have root | ||
6776 | privileges. | ||
6777 | </para> | ||
6778 | |||
6779 | <para> | ||
6780 | If your development system is using Fedora or | ||
6781 | CentOS, use the following: | ||
6782 | <literallayout class='monospaced'> | ||
6783 | # service httpd reload | ||
6784 | </literallayout> | ||
6785 | For Ubuntu and Debian, use the following: | ||
6786 | <literallayout class='monospaced'> | ||
6787 | # /etc/init.d/apache2 reload | ||
6788 | </literallayout> | ||
6789 | For OpenSUSE, use the following: | ||
6790 | <literallayout class='monospaced'> | ||
6791 | # /etc/init.d/apache2 reload | ||
6792 | </literallayout></para></listitem> | ||
6793 | <listitem><para> | ||
6794 | If you are using Security-Enhanced Linux | ||
6795 | (SELinux), you need to label the files as | ||
6796 | being accessible through Apache. | ||
6797 | Use the following command from the development | ||
6798 | host. | ||
6799 | This example assumes RPM package types: | ||
6800 | <literallayout class='monospaced'> | ||
6801 | # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm | ||
6802 | </literallayout></para></listitem> | ||
6803 | </orderedlist> | ||
6804 | </para> | ||
6805 | </section> | ||
6806 | |||
6807 | <section id='package-server-lighttpd'> | ||
6808 | <title>Serving Packages via lighttpd</title> | ||
6809 | |||
6810 | <para> | ||
6811 | If you are using lighttpd, all you need | ||
6812 | to do is to provide a link from your | ||
6813 | <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> | ||
6814 | directory to lighttpd's document-root. | ||
6815 | You can determine the specifics of your lighttpd | ||
6816 | installation by looking through its configuration file, | ||
6817 | which is usually found at: | ||
6818 | <filename>/etc/lighttpd/lighttpd.conf</filename>. | ||
6819 | </para> | ||
6820 | |||
6821 | <para> | ||
6822 | For example, if you are using IPK, lighttpd's | ||
6823 | document-root is set to | ||
6824 | <filename>/var/www/lighttpd</filename>, and you had | ||
6825 | packages for a target named "BOARD", | ||
6826 | then you might create a link from your build location | ||
6827 | to lighttpd's document-root as follows: | ||
6828 | <literallayout class='monospaced'> | ||
6829 | # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir | ||
6830 | </literallayout> | ||
6831 | </para> | ||
6832 | |||
6833 | <para> | ||
6834 | At this point, you need to start the lighttpd server. | ||
6835 | The method used to start the server varies by | ||
6836 | distribution. | ||
6837 | However, one basic method that starts it by hand is: | ||
6838 | <literallayout class='monospaced'> | ||
6839 | # lighttpd -f /etc/lighttpd/lighttpd.conf | ||
6840 | </literallayout> | ||
6841 | </para> | ||
6842 | </section> | ||
6843 | </section> | ||
6844 | |||
6845 | <section id='runtime-package-management-target'> | ||
6846 | <title>Target Setup</title> | ||
6847 | |||
6848 | <para> | ||
6849 | Setting up the target differs depending on the | ||
6850 | package management system. | ||
6851 | This section provides information for RPM and IPK. | ||
6852 | </para> | ||
6853 | |||
6854 | <section id='runtime-package-management-target-rpm'> | ||
6855 | <title>Using RPM</title> | ||
6856 | |||
6857 | <para> | ||
6858 | The application for performing runtime package | ||
6859 | management of RPM packages on the target is called | ||
6860 | <filename>smart</filename>. | ||
6861 | </para> | ||
6862 | |||
6863 | <para> | ||
6864 | On the target machine, you need to inform | ||
6865 | <filename>smart</filename> of every package database | ||
6866 | you want to use. | ||
6867 | As an example, suppose your target device can use the | ||
6868 | following three package databases from a server named | ||
6869 | <filename>server.name</filename>: | ||
6870 | <filename>all</filename>, <filename>i586</filename>, | ||
6871 | and <filename>qemux86</filename>. | ||
6872 | Given this example, issue the following commands on the | ||
6873 | target: | ||
6874 | <literallayout class='monospaced'> | ||
6875 | # smart channel ‐‐add all type=rpm-md baseurl=http://server.name/rpm/all | ||
6876 | # smart channel ‐‐add i585 type=rpm-md baseurl=http://server.name/rpm/i586 | ||
6877 | # smart channel ‐‐add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 | ||
6878 | </literallayout> | ||
6879 | Also from the target machine, fetch the repository | ||
6880 | information using this command: | ||
6881 | <literallayout class='monospaced'> | ||
6882 | # smart update | ||
6883 | </literallayout> | ||
6884 | You can now use the <filename>smart query</filename> | ||
6885 | and <filename>smart install</filename> commands to | ||
6886 | find and install packages from the repositories. | ||
6887 | </para> | ||
6888 | </section> | ||
6889 | |||
6890 | <section id='runtime-package-management-target-ipk'> | ||
6891 | <title>Using IPK</title> | ||
6892 | |||
6893 | <para> | ||
6894 | The application for performing runtime package | ||
6895 | management of IPK packages on the target is called | ||
6896 | <filename>opkg</filename>. | ||
6897 | </para> | ||
6898 | |||
6899 | <para> | ||
6900 | In order to inform <filename>opkg</filename> of the | ||
6901 | package databases you want to use, simply create one | ||
6902 | or more <filename>*.conf</filename> files in the | ||
6903 | <filename>/etc/opkg</filename> directory on the target. | ||
6904 | The <filename>opkg</filename> application uses them | ||
6905 | to find its available package databases. | ||
6906 | As an example, suppose you configured your HTTP server | ||
6907 | on your machine named | ||
6908 | <filename>www.mysite.com</filename> to serve files | ||
6909 | from a <filename>BOARD-dir</filename> directory under | ||
6910 | its document-root. | ||
6911 | In this case, you might create a configuration | ||
6912 | file on the target called | ||
6913 | <filename>/etc/opkg/base-feeds.conf</filename> that | ||
6914 | contains: | ||
6915 | <literallayout class='monospaced'> | ||
6916 | src/gz all http://www.mysite.com/BOARD-dir/all | ||
6917 | src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a | ||
6918 | src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone | ||
6919 | </literallayout> | ||
6920 | </para> | ||
6921 | |||
6922 | <para> | ||
6923 | As a way of making it easier to generate and make | ||
6924 | these IPK configuration files available on your | ||
6925 | target, simply define | ||
6926 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink> | ||
6927 | to point to your server and the location within the | ||
6928 | document-root which contains the databases. | ||
6929 | For example: if you are serving your packages over | ||
6930 | HTTP, your server's IP address is 192.168.7.1, and | ||
6931 | your databases are located in a directory called | ||
6932 | <filename>BOARD-dir</filename> underneath your HTTP | ||
6933 | server's document-root, you need to set | ||
6934 | <filename>FEED_DEPLOYDIR_BASE_URI</filename> to | ||
6935 | <filename>http://192.168.7.1/BOARD-dir</filename> and | ||
6936 | a set of configuration files will be generated for you | ||
6937 | in your target to work with this feed. | ||
6938 | </para> | ||
6939 | |||
6940 | <para> | ||
6941 | On the target machine, fetch (or refresh) the | ||
6942 | repository information using this command: | ||
6943 | <literallayout class='monospaced'> | ||
6944 | # opkg update | ||
6945 | </literallayout> | ||
6946 | You can now use the <filename>opkg list</filename> and | ||
6947 | <filename>opkg install</filename> commands to find and | ||
6948 | install packages from the repositories. | ||
6949 | </para> | ||
6950 | </section> | ||
6951 | </section> | ||
6952 | </section> | ||
6953 | |||
6954 | <section id='testing-packages-with-ptest'> | ||
6955 | <title>Testing Packages With ptest</title> | ||
6956 | |||
6957 | <para> | ||
6958 | A Package Test (ptest) runs tests against packages built | ||
6959 | by the OpenEmbedded build system on the target machine. | ||
6960 | A ptest contains at least two items: the actual test, and | ||
6961 | a shell script (<filename>run-ptest</filename>) that starts | ||
6962 | the test. | ||
6963 | The shell script that starts the test must not contain | ||
6964 | the actual test - the script only starts the test. | ||
6965 | On the other hand, the test can be anything from a simple | ||
6966 | shell script that runs a binary and checks the output to | ||
6967 | an elaborate system of test binaries and data files. | ||
6968 | </para> | ||
6969 | |||
6970 | <para> | ||
6971 | The test generates output in the format used by | ||
6972 | Automake: | ||
6973 | <literallayout class='monospaced'> | ||
6974 | <replaceable>result</replaceable>: <replaceable>testname</replaceable> | ||
6975 | </literallayout> | ||
6976 | where the result can be <filename>PASS</filename>, | ||
6977 | <filename>FAIL</filename>, or <filename>SKIP</filename>, | ||
6978 | and the testname can be any identifying string. | ||
6979 | </para> | ||
6980 | |||
6981 | <para> | ||
6982 | For a list of Yocto Project recipes that are already | ||
6983 | enabled with ptest, see the | ||
6984 | <ulink url='https://wiki.yoctoproject.org/wiki/Ptest'>Ptest</ulink> | ||
6985 | wiki page. | ||
6986 | <note> | ||
6987 | A recipe is "ptest-enabled" if it inherits the | ||
6988 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink> | ||
6989 | class. | ||
6990 | </note> | ||
6991 | </para> | ||
6992 | |||
6993 | <section id='adding-ptest-to-your-build'> | ||
6994 | <title>Adding ptest to Your Build</title> | ||
6995 | |||
6996 | <para> | ||
6997 | To add package testing to your build, add the | ||
6998 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> | ||
6999 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> | ||
7000 | variables to your <filename>local.conf</filename> file, | ||
7001 | which is found in the | ||
7002 | <link linkend='build-directory'>Build Directory</link>: | ||
7003 | <literallayout class='monospaced'> | ||
7004 | DISTRO_FEATURES_append = " ptest" | ||
7005 | EXTRA_IMAGE_FEATURES += "ptest-pkgs" | ||
7006 | </literallayout> | ||
7007 | Once your build is complete, the ptest files are installed | ||
7008 | into the | ||
7009 | <filename>/usr/lib/<replaceable>package</replaceable>/ptest</filename> | ||
7010 | directory within the image, where | ||
7011 | <filename><replaceable>package</replaceable></filename> | ||
7012 | is the name of the package. | ||
7013 | </para> | ||
7014 | </section> | ||
7015 | |||
7016 | <section id='running-ptest'> | ||
7017 | <title>Running ptest</title> | ||
7018 | |||
7019 | <para> | ||
7020 | The <filename>ptest-runner</filename> package installs a | ||
7021 | shell script that loops through all installed ptest test | ||
7022 | suites and runs them in sequence. | ||
7023 | Consequently, you might want to add this package to | ||
7024 | your image. | ||
7025 | </para> | ||
7026 | </section> | ||
7027 | |||
7028 | <section id='getting-your-package-ready'> | ||
7029 | <title>Getting Your Package Ready</title> | ||
7030 | |||
7031 | <para> | ||
7032 | In order to enable a recipe to run installed ptests | ||
7033 | on target hardware, | ||
7034 | you need to prepare the recipes that build the packages | ||
7035 | you want to test. | ||
7036 | Here is what you have to do for each recipe: | ||
7037 | <itemizedlist> | ||
7038 | <listitem><para><emphasis>Be sure the recipe | ||
7039 | inherits the | ||
7040 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink> | ||
7041 | class:</emphasis> | ||
7042 | Include the following line in each recipe: | ||
7043 | <literallayout class='monospaced'> | ||
7044 | inherit ptest | ||
7045 | </literallayout> | ||
7046 | </para></listitem> | ||
7047 | <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis> | ||
7048 | This script starts your test. | ||
7049 | Locate the script where you will refer to it | ||
7050 | using | ||
7051 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. | ||
7052 | Here is an example that starts a test for | ||
7053 | <filename>dbus</filename>: | ||
7054 | <literallayout class='monospaced'> | ||
7055 | #!/bin/sh | ||
7056 | cd test | ||
7057 | make -k runtest-TESTS | ||
7058 | </literallayout> | ||
7059 | </para></listitem> | ||
7060 | <listitem><para><emphasis>Ensure dependencies are | ||
7061 | met:</emphasis> | ||
7062 | If the test adds build or runtime dependencies | ||
7063 | that normally do not exist for the package | ||
7064 | (such as requiring "make" to run the test suite), | ||
7065 | use the | ||
7066 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
7067 | and | ||
7068 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> | ||
7069 | variables in your recipe in order for the package | ||
7070 | to meet the dependencies. | ||
7071 | Here is an example where the package has a runtime | ||
7072 | dependency on "make": | ||
7073 | <literallayout class='monospaced'> | ||
7074 | RDEPENDS_${PN}-ptest += "make" | ||
7075 | </literallayout> | ||
7076 | </para></listitem> | ||
7077 | <listitem><para><emphasis>Add a function to build the | ||
7078 | test suite:</emphasis> | ||
7079 | Not many packages support cross-compilation of | ||
7080 | their test suites. | ||
7081 | Consequently, you usually need to add a | ||
7082 | cross-compilation function to the package. | ||
7083 | </para> | ||
7084 | <para>Many packages based on Automake compile and | ||
7085 | run the test suite by using a single command | ||
7086 | such as <filename>make check</filename>. | ||
7087 | However, the native <filename>make check</filename> | ||
7088 | builds and runs on the same computer, while | ||
7089 | cross-compiling requires that the package is built | ||
7090 | on the host but executed on the target. | ||
7091 | The built version of Automake that ships with the | ||
7092 | Yocto Project includes a patch that separates | ||
7093 | building and execution. | ||
7094 | Consequently, packages that use the unaltered, | ||
7095 | patched version of <filename>make check</filename> | ||
7096 | automatically cross-compiles.</para> | ||
7097 | <para>Regardless, you still must add a | ||
7098 | <filename>do_compile_ptest</filename> function to | ||
7099 | build the test suite. | ||
7100 | Add a function similar to the following to your | ||
7101 | recipe: | ||
7102 | <literallayout class='monospaced'> | ||
7103 | do_compile_ptest() { | ||
7104 | oe_runmake buildtest-TESTS | ||
7105 | } | ||
7106 | </literallayout> | ||
7107 | </para></listitem> | ||
7108 | <listitem><para><emphasis>Ensure special configurations | ||
7109 | are set:</emphasis> | ||
7110 | If the package requires special configurations | ||
7111 | prior to compiling the test code, you must | ||
7112 | insert a <filename>do_configure_ptest</filename> | ||
7113 | function into the recipe. | ||
7114 | </para></listitem> | ||
7115 | <listitem><para><emphasis>Install the test | ||
7116 | suite:</emphasis> | ||
7117 | The <filename>ptest</filename> class | ||
7118 | automatically copies the file | ||
7119 | <filename>run-ptest</filename> to the target and | ||
7120 | then runs make <filename>install-ptest</filename> | ||
7121 | to run the tests. | ||
7122 | If this is not enough, you need to create a | ||
7123 | <filename>do_install_ptest</filename> function and | ||
7124 | make sure it gets called after the | ||
7125 | "make install-ptest" completes. | ||
7126 | </para></listitem> | ||
7127 | </itemizedlist> | ||
7128 | </para> | ||
7129 | </section> | ||
7130 | </section> | ||
7131 | </section> | ||
7132 | |||
7133 | <section id='working-with-source-files'> | ||
7134 | <title>Working with Source Files</title> | ||
7135 | |||
7136 | <para> | ||
7137 | The OpenEmbedded build system works with source files located | ||
7138 | through the | ||
7139 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
7140 | variable. | ||
7141 | When you build something using BitBake, a big part of the operation | ||
7142 | is locating and downloading all the source tarballs. | ||
7143 | For images, downloading all the source for various packages can | ||
7144 | take a significant amount of time. | ||
7145 | </para> | ||
7146 | |||
7147 | <para> | ||
7148 | This section presents information for working with source | ||
7149 | files that can lead to more efficient use of resources and | ||
7150 | time. | ||
7151 | </para> | ||
7152 | |||
7153 | <section id='setting-up-effective-mirrors'> | ||
7154 | <title>Setting up Effective Mirrors</title> | ||
7155 | |||
7156 | <para> | ||
7157 | As mentioned, a good deal that goes into a Yocto Project | ||
7158 | build is simply downloading all of the source tarballs. | ||
7159 | Maybe you have been working with another build system | ||
7160 | (OpenEmbedded or Angstrom) for which you have built up a | ||
7161 | sizable directory of source tarballs. | ||
7162 | Or, perhaps someone else has such a directory for which you | ||
7163 | have read access. | ||
7164 | If so, you can save time by adding statements to your | ||
7165 | configuration file so that the build process checks local | ||
7166 | directories first for existing tarballs before checking the | ||
7167 | Internet. | ||
7168 | </para> | ||
7169 | |||
7170 | <para> | ||
7171 | Here is an efficient way to set it up in your | ||
7172 | <filename>local.conf</filename> file: | ||
7173 | <literallayout class='monospaced'> | ||
7174 | SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" | ||
7175 | INHERIT += "own-mirrors" | ||
7176 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
7177 | # BB_NO_NETWORK = "1" | ||
7178 | </literallayout> | ||
7179 | </para> | ||
7180 | |||
7181 | <para> | ||
7182 | In the previous example, the | ||
7183 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink> | ||
7184 | variable causes the OpenEmbedded build system to generate | ||
7185 | tarballs of the Git repositories and store them in the | ||
7186 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
7187 | directory. | ||
7188 | Due to performance reasons, generating and storing these | ||
7189 | tarballs is not the build system's default behavior. | ||
7190 | </para> | ||
7191 | |||
7192 | <para> | ||
7193 | You can also use the | ||
7194 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink> | ||
7195 | variable. | ||
7196 | For an example, see the variable's glossary entry in the | ||
7197 | Yocto Project Reference Manual. | ||
7198 | </para> | ||
7199 | </section> | ||
7200 | |||
7201 | <section id='getting-source-files-and-suppressing-the-build'> | ||
7202 | <title>Getting Source Files and Suppressing the Build</title> | ||
7203 | |||
7204 | <para> | ||
7205 | Another technique you can use to ready yourself for a | ||
7206 | successive string of build operations, is to pre-fetch | ||
7207 | all the source files without actually starting a build. | ||
7208 | This technique lets you work through any download issues | ||
7209 | and ultimately gathers all the source files into your | ||
7210 | download directory | ||
7211 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-build-downloads'><filename>build/downloads</filename></ulink>, | ||
7212 | which is located with | ||
7213 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>. | ||
7214 | </para> | ||
7215 | |||
7216 | <para> | ||
7217 | Use the following BitBake command form to fetch all the | ||
7218 | necessary sources without starting the build: | ||
7219 | <literallayout class='monospaced'> | ||
7220 | $ bitbake -c fetchall <replaceable>target</replaceable> | ||
7221 | </literallayout> | ||
7222 | This variation of the BitBake command guarantees that you | ||
7223 | have all the sources for that BitBake target should you | ||
7224 | disconnect from the Internet and want to do the build | ||
7225 | later offline. | ||
7226 | </para> | ||
7227 | </section> | ||
7228 | </section> | ||
7229 | |||
7230 | <section id="building-software-from-an-external-source"> | ||
7231 | <title>Building Software from an External Source</title> | ||
7232 | |||
7233 | <para> | ||
7234 | By default, the OpenEmbedded build system uses the | ||
7235 | <link linkend='build-directory'>Build Directory</link> when | ||
7236 | building source code. | ||
7237 | The build process involves fetching the source files, unpacking | ||
7238 | them, and then patching them if necessary before the build takes | ||
7239 | place. | ||
7240 | </para> | ||
7241 | |||
7242 | <para> | ||
7243 | Situations exist where you might want to build software from source | ||
7244 | files that are external to and thus outside of the | ||
7245 | OpenEmbedded build system. | ||
7246 | For example, suppose you have a project that includes a new BSP with | ||
7247 | a heavily customized kernel. | ||
7248 | And, you want to minimize exposing the build system to the | ||
7249 | development team so that they can focus on their project and | ||
7250 | maintain everyone's workflow as much as possible. | ||
7251 | In this case, you want a kernel source directory on the development | ||
7252 | machine where the development occurs. | ||
7253 | You want the recipe's | ||
7254 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
7255 | variable to point to the external directory and use it as is, not | ||
7256 | copy it. | ||
7257 | </para> | ||
7258 | |||
7259 | <para> | ||
7260 | To build from software that comes from an external source, all you | ||
7261 | need to do is inherit the | ||
7262 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> | ||
7263 | class and then set the | ||
7264 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink> | ||
7265 | variable to point to your external source code. | ||
7266 | Here are the statements to put in your | ||
7267 | <filename>local.conf</filename> file: | ||
7268 | <literallayout class='monospaced'> | ||
7269 | INHERIT += "externalsrc" | ||
7270 | EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" | ||
7271 | </literallayout> | ||
7272 | </para> | ||
7273 | |||
7274 | <para> | ||
7275 | This next example shows how to accomplish the same thing by setting | ||
7276 | <filename>EXTERNALSRC</filename> in the recipe itself or in the | ||
7277 | recipe's append file: | ||
7278 | <literallayout class='monospaced'> | ||
7279 | EXTERNALSRC = "<replaceable>path</replaceable>" | ||
7280 | EXTERNALSRC_BUILD = "<replaceable>path</replaceable>" | ||
7281 | </literallayout> | ||
7282 | <note> | ||
7283 | In order for these settings to take effect, you must globally | ||
7284 | or locally inherit the | ||
7285 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> | ||
7286 | class. | ||
7287 | </note> | ||
7288 | </para> | ||
7289 | |||
7290 | <para> | ||
7291 | By default, <filename>externalsrc.bbclass</filename> builds | ||
7292 | the source code in a directory separate from the external source | ||
7293 | directory as specified by | ||
7294 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>. | ||
7295 | If you need to have the source built in the same directory in | ||
7296 | which it resides, or some other nominated directory, you can set | ||
7297 | <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink> | ||
7298 | to point to that directory: | ||
7299 | <literallayout class='monospaced'> | ||
7300 | EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" | ||
7301 | </literallayout> | ||
7302 | </para> | ||
7303 | </section> | ||
7304 | |||
7305 | <section id="selecting-an-initialization-manager"> | ||
7306 | <title>Selecting an Initialization Manager</title> | ||
7307 | |||
7308 | <para> | ||
7309 | By default, the Yocto Project uses SysVinit as the initialization | ||
7310 | manager. | ||
7311 | However, support also exists for systemd, | ||
7312 | which is a full replacement for init with | ||
7313 | parallel starting of services, reduced shell overhead and other | ||
7314 | features that are used by many distributions. | ||
7315 | </para> | ||
7316 | |||
7317 | <para> | ||
7318 | If you want to use SysVinit, you do | ||
7319 | not have to do anything. | ||
7320 | But, if you want to use systemd, you must | ||
7321 | take some steps as described in the following sections. | ||
7322 | </para> | ||
7323 | |||
7324 | <section id='using-systemd-exclusively'> | ||
7325 | <title>Using systemd Exclusively</title> | ||
7326 | |||
7327 | <para> | ||
7328 | Set the these variables in your distribution configuration | ||
7329 | file as follows: | ||
7330 | <literallayout class='monospaced'> | ||
7331 | DISTRO_FEATURES_append = " systemd" | ||
7332 | VIRTUAL-RUNTIME_init_manager = "systemd" | ||
7333 | </literallayout> | ||
7334 | You can also prevent the SysVinit | ||
7335 | distribution feature from | ||
7336 | being automatically enabled as follows: | ||
7337 | <literallayout class='monospaced'> | ||
7338 | DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" | ||
7339 | </literallayout> | ||
7340 | Doing so removes any redundant SysVinit scripts. | ||
7341 | </para> | ||
7342 | |||
7343 | <para> | ||
7344 | To remove initscripts from your image altogether, | ||
7345 | set this variable also: | ||
7346 | <literallayout class='monospaced'> | ||
7347 | VIRTUAL-RUNTIME_initscripts = "" | ||
7348 | </literallayout> | ||
7349 | </para> | ||
7350 | |||
7351 | <para> | ||
7352 | For information on the backfill variable, see | ||
7353 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>. | ||
7354 | </para> | ||
7355 | </section> | ||
7356 | |||
7357 | <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'> | ||
7358 | <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title> | ||
7359 | |||
7360 | <para> | ||
7361 | Set these variables in your distribution configuration | ||
7362 | file as follows: | ||
7363 | <literallayout class='monospaced'> | ||
7364 | DISTRO_FEATURES_append = " systemd" | ||
7365 | VIRTUAL-RUNTIME_init_manager = "systemd" | ||
7366 | </literallayout> | ||
7367 | Doing so causes your main image to use the | ||
7368 | <filename>packagegroup-core-boot.bb</filename> recipe and | ||
7369 | systemd. | ||
7370 | The rescue/minimal image cannot use this package group. | ||
7371 | However, it can install SysVinit | ||
7372 | and the appropriate packages will have support for both | ||
7373 | systemd and SysVinit. | ||
7374 | </para> | ||
7375 | </section> | ||
7376 | </section> | ||
7377 | |||
7378 | <section id="platdev-appdev-srcrev"> | ||
7379 | <title>Using an External SCM</title> | ||
7380 | |||
7381 | <para> | ||
7382 | If you're working on a recipe that pulls from an external Source | ||
7383 | Code Manager (SCM), it is possible to have the OpenEmbedded build | ||
7384 | system notice new recipe changes added to the SCM and then build | ||
7385 | the resulting packages that depend on the new recipes by using | ||
7386 | the latest versions. | ||
7387 | This only works for SCMs from which it is possible to get a | ||
7388 | sensible revision number for changes. | ||
7389 | Currently, you can do this with Apache Subversion (SVN), Git, and | ||
7390 | Bazaar (BZR) repositories. | ||
7391 | </para> | ||
7392 | |||
7393 | <para> | ||
7394 | To enable this behavior, the | ||
7395 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> | ||
7396 | of the recipe needs to reference | ||
7397 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. | ||
7398 | Here is an example: | ||
7399 | <literallayout class='monospaced'> | ||
7400 | PV = "1.2.3+git${SRCPV} | ||
7401 | </literallayout> | ||
7402 | Then, you can add the following to your | ||
7403 | <filename>local.conf</filename>: | ||
7404 | <literallayout class='monospaced'> | ||
7405 | SRCREV_pn-<replaceable>PN</replaceable> = "${AUTOREV}" | ||
7406 | </literallayout> | ||
7407 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> | ||
7408 | is the name of the recipe for which you want to enable automatic source | ||
7409 | revision updating. | ||
7410 | </para> | ||
7411 | |||
7412 | <para> | ||
7413 | If you do not want to update your local configuration file, you can | ||
7414 | add the following directly to the recipe to finish enabling | ||
7415 | the feature: | ||
7416 | <literallayout class='monospaced'> | ||
7417 | SRCREV = "${AUTOREV}" | ||
7418 | </literallayout> | ||
7419 | </para> | ||
7420 | |||
7421 | <para> | ||
7422 | The Yocto Project provides a distribution named | ||
7423 | <filename>poky-bleeding</filename>, whose configuration | ||
7424 | file contains the line: | ||
7425 | <literallayout class='monospaced'> | ||
7426 | require conf/distro/include/poky-floating-revisions.inc | ||
7427 | </literallayout> | ||
7428 | This line pulls in the listed include file that contains | ||
7429 | numerous lines of exactly that form: | ||
7430 | <literallayout class='monospaced'> | ||
7431 | SRCREV_pn-gconf-dbus ?= "${AUTOREV}" | ||
7432 | SRCREV_pn-matchbox-common ?= "${AUTOREV}" | ||
7433 | SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}" | ||
7434 | SRCREV_pn-matchbox-desktop ?= "${AUTOREV}" | ||
7435 | SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}" | ||
7436 | SRCREV_pn-matchbox-panel ?= "${AUTOREV}" | ||
7437 | SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}" | ||
7438 | SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}" | ||
7439 | SRCREV_pn-matchbox-terminal ?= "${AUTOREV}" | ||
7440 | SRCREV_pn-matchbox-wm ?= "${AUTOREV}" | ||
7441 | SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}" | ||
7442 | SRCREV_pn-settings-daemon ?= "${AUTOREV}" | ||
7443 | SRCREV_pn-screenshot ?= "${AUTOREV}" | ||
7444 | SRCREV_pn-libfakekey ?= "${AUTOREV}" | ||
7445 | SRCREV_pn-oprofileui ?= "${AUTOREV}" | ||
7446 | . | ||
7447 | . | ||
7448 | . | ||
7449 | </literallayout> | ||
7450 | These lines allow you to experiment with building a | ||
7451 | distribution that tracks the latest development source | ||
7452 | for numerous packages. | ||
7453 | <note><title>Caution</title> | ||
7454 | The <filename>poky-bleeding</filename> distribution | ||
7455 | is not tested on a regular basis. | ||
7456 | Keep this in mind if you use it. | ||
7457 | </note> | ||
7458 | </para> | ||
7459 | </section> | ||
7460 | |||
7461 | <section id='creating-a-read-only-root-filesystem'> | ||
7462 | <title>Creating a Read-Only Root Filesystem</title> | ||
7463 | |||
7464 | <para> | ||
7465 | Suppose, for security reasons, you need to disable | ||
7466 | your target device's root filesystem's write permissions | ||
7467 | (i.e. you need a read-only root filesystem). | ||
7468 | Or, perhaps you are running the device's operating system | ||
7469 | from a read-only storage device. | ||
7470 | For either case, you can customize your image for | ||
7471 | that behavior. | ||
7472 | </para> | ||
7473 | |||
7474 | <note> | ||
7475 | Supporting a read-only root filesystem requires that the system and | ||
7476 | applications do not try to write to the root filesystem. | ||
7477 | You must configure all parts of the target system to write | ||
7478 | elsewhere, or to gracefully fail in the event of attempting to | ||
7479 | write to the root filesystem. | ||
7480 | </note> | ||
7481 | |||
7482 | <section id='creating-the-root-filesystem'> | ||
7483 | <title>Creating the Root Filesystem</title> | ||
7484 | |||
7485 | <para> | ||
7486 | To create the read-only root filesystem, simply add the | ||
7487 | "read-only-rootfs" feature to your image. | ||
7488 | Using either of the following statements in your | ||
7489 | image recipe or from within the | ||
7490 | <filename>local.conf</filename> file found in the | ||
7491 | <link linkend='build-directory'>Build Directory</link> | ||
7492 | causes the build system to create a read-only root filesystem: | ||
7493 | <literallayout class='monospaced'> | ||
7494 | IMAGE_FEATURES = "read-only-rootfs" | ||
7495 | </literallayout> | ||
7496 | or | ||
7497 | <literallayout class='monospaced'> | ||
7498 | EXTRA_IMAGE_FEATURES += "read-only-rootfs" | ||
7499 | </literallayout> | ||
7500 | </para> | ||
7501 | |||
7502 | <para> | ||
7503 | For more information on how to use these variables, see the | ||
7504 | "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>" | ||
7505 | section. | ||
7506 | For information on the variables, see | ||
7507 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> | ||
7508 | and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>. | ||
7509 | </para> | ||
7510 | </section> | ||
7511 | |||
7512 | <section id='post-installation-scripts'> | ||
7513 | <title>Post-Installation Scripts</title> | ||
7514 | |||
7515 | <para> | ||
7516 | It is very important that you make sure all | ||
7517 | post-Installation (<filename>pkg_postinst</filename>) scripts | ||
7518 | for packages that are installed into the image can be run | ||
7519 | at the time when the root filesystem is created during the | ||
7520 | build on the host system. | ||
7521 | These scripts cannot attempt to run during first-boot on the | ||
7522 | target device. | ||
7523 | With the "read-only-rootfs" feature enabled, | ||
7524 | the build system checks during root filesystem creation to make | ||
7525 | sure all post-installation scripts succeed. | ||
7526 | If any of these scripts still need to be run after the root | ||
7527 | filesystem is created, the build immediately fails. | ||
7528 | These build-time checks ensure that the build fails | ||
7529 | rather than the target device fails later during its | ||
7530 | initial boot operation. | ||
7531 | </para> | ||
7532 | |||
7533 | <para> | ||
7534 | Most of the common post-installation scripts generated by the | ||
7535 | build system for the out-of-the-box Yocto Project are engineered | ||
7536 | so that they can run during root filesystem creation | ||
7537 | (e.g. post-installation scripts for caching fonts). | ||
7538 | However, if you create and add custom scripts, you need | ||
7539 | to be sure they can be run during this file system creation. | ||
7540 | </para> | ||
7541 | |||
7542 | <para> | ||
7543 | Here are some common problems that prevent | ||
7544 | post-installation scripts from running during root filesystem | ||
7545 | creation: | ||
7546 | <itemizedlist> | ||
7547 | <listitem><para> | ||
7548 | <emphasis>Not using $D in front of absolute | ||
7549 | paths:</emphasis> | ||
7550 | The build system defines | ||
7551 | <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> | ||
7552 | when the root filesystem is created. | ||
7553 | Furthermore, <filename>$D</filename> is blank when the | ||
7554 | script is run on the target device. | ||
7555 | This implies two purposes for <filename>$D</filename>: | ||
7556 | ensuring paths are valid in both the host and target | ||
7557 | environments, and checking to determine which | ||
7558 | environment is being used as a method for taking | ||
7559 | appropriate actions. | ||
7560 | </para></listitem> | ||
7561 | <listitem><para> | ||
7562 | <emphasis>Attempting to run processes that are | ||
7563 | specific to or dependent on the target | ||
7564 | architecture:</emphasis> | ||
7565 | You can work around these attempts by using native | ||
7566 | tools to accomplish the same tasks, or | ||
7567 | by alternatively running the processes under QEMU, | ||
7568 | which has the <filename>qemu_run_binary</filename> | ||
7569 | function. | ||
7570 | For more information, see the | ||
7571 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-qemu'><filename>qemu</filename></ulink> | ||
7572 | class.</para></listitem> | ||
7573 | </itemizedlist> | ||
7574 | </para> | ||
7575 | </section> | ||
7576 | |||
7577 | <section id='areas-with-write-access'> | ||
7578 | <title>Areas With Write Access</title> | ||
7579 | |||
7580 | <para> | ||
7581 | With the "read-only-rootfs" feature enabled, | ||
7582 | any attempt by the target to write to the root filesystem at | ||
7583 | runtime fails. | ||
7584 | Consequently, you must make sure that you configure processes | ||
7585 | and applications that attempt these types of writes do so | ||
7586 | to directories with write access (e.g. | ||
7587 | <filename>/tmp</filename> or <filename>/var/run</filename>). | ||
7588 | </para> | ||
7589 | </section> | ||
7590 | </section> | ||
7591 | |||
7592 | <section id="performing-automated-runtime-testing"> | ||
7593 | <title>Performing Automated Runtime Testing</title> | ||
7594 | |||
7595 | <para> | ||
7596 | The OpenEmbedded build system makes available a series of automated | ||
7597 | tests for images to verify runtime functionality. | ||
7598 | You can run these tests on either QEMU or actual target hardware. | ||
7599 | Tests are written in Python making use of the | ||
7600 | <filename>unittest</filename> module, and the majority of them | ||
7601 | run commands on the target system over SSH. | ||
7602 | This section describes how you set up the environment to use these | ||
7603 | tests, run available tests, and write and add your own tests. | ||
7604 | </para> | ||
7605 | |||
7606 | <section id='enabling-tests'> | ||
7607 | <title>Enabling Tests</title> | ||
7608 | |||
7609 | <para> | ||
7610 | Depending on whether you are planning to run tests using | ||
7611 | QEMU or on the hardware, you have to take | ||
7612 | different steps to enable the tests. | ||
7613 | See the following subsections for information on how to | ||
7614 | enable both types of tests. | ||
7615 | </para> | ||
7616 | |||
7617 | <section id='qemu-image-enabling-tests'> | ||
7618 | <title>Enabling Runtime Tests on QEMU</title> | ||
7619 | |||
7620 | <para> | ||
7621 | In order to run tests, you need to do the following: | ||
7622 | <itemizedlist> | ||
7623 | <listitem><para><emphasis>Set up to avoid interaction | ||
7624 | with <filename>sudo</filename> for networking:</emphasis> | ||
7625 | To accomplish this, you must do one of the | ||
7626 | following: | ||
7627 | <itemizedlist> | ||
7628 | <listitem><para>Add | ||
7629 | <filename>NOPASSWD</filename> for your user | ||
7630 | in <filename>/etc/sudoers</filename> either for | ||
7631 | all commands or just for | ||
7632 | <filename>runqemu-ifup</filename>. | ||
7633 | You must provide the full path as that can | ||
7634 | change if you are using multiple clones of the | ||
7635 | source repository. | ||
7636 | <note> | ||
7637 | On some distributions, you also need to | ||
7638 | comment out "Defaults requiretty" in | ||
7639 | <filename>/etc/sudoers</filename>. | ||
7640 | </note></para></listitem> | ||
7641 | <listitem><para>Manually configure a tap interface | ||
7642 | for your system.</para></listitem> | ||
7643 | <listitem><para>Run as root the script in | ||
7644 | <filename>scripts/runqemu-gen-tapdevs</filename>, | ||
7645 | which should generate a list of tap devices. | ||
7646 | This is the option typically chosen for | ||
7647 | Autobuilder-type environments. | ||
7648 | </para></listitem> | ||
7649 | </itemizedlist></para></listitem> | ||
7650 | <listitem><para><emphasis>Set the | ||
7651 | <filename>DISPLAY</filename> variable:</emphasis> | ||
7652 | You need to set this variable so that you have an X | ||
7653 | server available (e.g. start | ||
7654 | <filename>vncserver</filename> for a headless machine). | ||
7655 | </para></listitem> | ||
7656 | <listitem><para><emphasis>Be sure your host's firewall | ||
7657 | accepts incoming connections from | ||
7658 | 192.168.7.0/24:</emphasis> | ||
7659 | Some of the tests (in particular smart tests) start an | ||
7660 | HTTP server on a random high number port, which is | ||
7661 | used to serve files to the target. | ||
7662 | The smart module serves | ||
7663 | <filename>${DEPLOY_DIR}/rpm</filename> so it can run | ||
7664 | smart channel commands. That means your host's firewall | ||
7665 | must accept incoming connections from 192.168.7.0/24, | ||
7666 | which is the default IP range used for tap devices | ||
7667 | by <filename>runqemu</filename>.</para></listitem> | ||
7668 | </itemizedlist> | ||
7669 | </para> | ||
7670 | |||
7671 | <para> | ||
7672 | Once you start running the tests, the following happens: | ||
7673 | <orderedlist> | ||
7674 | <listitem><para>A copy of the root filesystem is written | ||
7675 | to <filename>${WORKDIR}/testimage</filename>. | ||
7676 | </para></listitem> | ||
7677 | <listitem><para>The image is booted under QEMU using the | ||
7678 | standard <filename>runqemu</filename> script. | ||
7679 | </para></listitem> | ||
7680 | <listitem><para>A default timeout of 500 seconds occurs | ||
7681 | to allow for the boot process to reach the login prompt. | ||
7682 | You can change the timeout period by setting | ||
7683 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink> | ||
7684 | in the <filename>local.conf</filename> file. | ||
7685 | </para></listitem> | ||
7686 | <listitem><para>Once the boot process is reached and the | ||
7687 | login prompt appears, the tests run. | ||
7688 | The full boot log is written to | ||
7689 | <filename>${WORKDIR}/testimage/qemu_boot_log</filename>. | ||
7690 | </para></listitem> | ||
7691 | <listitem><para>Each test module loads in the order found | ||
7692 | in <filename>TEST_SUITES</filename>. | ||
7693 | You can find the full output of the commands run over | ||
7694 | SSH in | ||
7695 | <filename>${WORKDIR}/testimgage/ssh_target_log</filename>. | ||
7696 | </para></listitem> | ||
7697 | <listitem><para>If no failures occur, the task running the | ||
7698 | tests ends successfully. | ||
7699 | You can find the output from the | ||
7700 | <filename>unittest</filename> in the task log at | ||
7701 | <filename>${WORKDIR}/temp/log.do_testimage</filename>. | ||
7702 | </para></listitem> | ||
7703 | </orderedlist> | ||
7704 | </para> | ||
7705 | </section> | ||
7706 | |||
7707 | <section id='hardware-image-enabling-tests'> | ||
7708 | <title>Enabling Runtime Tests on Hardware</title> | ||
7709 | |||
7710 | <para> | ||
7711 | The OpenEmbedded build system can run tests on real | ||
7712 | hardware, and for certain devices it can also deploy | ||
7713 | the image to be tested onto the device beforehand. | ||
7714 | </para> | ||
7715 | |||
7716 | <para> | ||
7717 | For automated deployment, a "master image" is installed | ||
7718 | onto the hardware once as part of setup. | ||
7719 | Then, each time tests are to be run, the following | ||
7720 | occurs: | ||
7721 | <orderedlist> | ||
7722 | <listitem><para>The master image is booted into and | ||
7723 | used to write the image to be tested to | ||
7724 | a second partition. | ||
7725 | </para></listitem> | ||
7726 | <listitem><para>The device is then rebooted using an | ||
7727 | external script that you need to provide. | ||
7728 | </para></listitem> | ||
7729 | <listitem><para>The device boots into the image to be | ||
7730 | tested. | ||
7731 | </para></listitem> | ||
7732 | </orderedlist> | ||
7733 | </para> | ||
7734 | |||
7735 | <para> | ||
7736 | When running tests (independent of whether the image | ||
7737 | has been deployed automatically or not), the device is | ||
7738 | expected to be connected to a network on a | ||
7739 | pre-determined IP address. | ||
7740 | You can either use static IP addresses written into | ||
7741 | the image, or set the image to use DHCP and have your | ||
7742 | DHCP server on the test network assign a known IP address | ||
7743 | based on the MAC address of the device. | ||
7744 | </para> | ||
7745 | |||
7746 | <para> | ||
7747 | In order to run tests on hardware, you need to set | ||
7748 | <filename>TEST_TARGET</filename> to an appropriate value. | ||
7749 | For QEMU, you do not have to change anything, the default | ||
7750 | value is "QemuTarget". | ||
7751 | For running tests on hardware, the following options exist: | ||
7752 | <itemizedlist> | ||
7753 | <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis> | ||
7754 | Choose "SimpleRemoteTarget" if you are going to | ||
7755 | run tests on a target system that is already | ||
7756 | running the image to be tested and is available | ||
7757 | on the network. | ||
7758 | You can use "SimpleRemoteTarget" in conjunction | ||
7759 | with either real hardware or an image running | ||
7760 | within a separately started QEMU or any | ||
7761 | other virtual machine manager. | ||
7762 | </para></listitem> | ||
7763 | <listitem><para><emphasis>"GummibootTarget":</emphasis> | ||
7764 | Choose "GummibootTarget" if your hardware is | ||
7765 | an EFI-based machine with | ||
7766 | <filename>gummiboot</filename> as bootloader and | ||
7767 | <filename>core-image-testmaster</filename> | ||
7768 | (or something similar) is installed. | ||
7769 | Also, your hardware under test must be in a | ||
7770 | DHCP-enabled network that gives it the same IP | ||
7771 | address for each reboot.</para> | ||
7772 | <para>If you choose "GummibootTarget", there are | ||
7773 | additional requirements and considerations. | ||
7774 | See the | ||
7775 | "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>" | ||
7776 | section, which follows, for more information. | ||
7777 | </para></listitem> | ||
7778 | <listitem><para><emphasis>"BeagleBoneTarget":</emphasis> | ||
7779 | Choose "BeagleBoneTarget" if you are deploying | ||
7780 | images and running tests on the BeagleBone | ||
7781 | "Black" or original "White" hardware. | ||
7782 | For information on how to use these tests, see the | ||
7783 | comments at the top of the BeagleBoneTarget | ||
7784 | <filename>meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py</filename> | ||
7785 | file. | ||
7786 | </para></listitem> | ||
7787 | <listitem><para><emphasis>"EdgeRouterTarget":</emphasis> | ||
7788 | Choose "EdgeRouterTarget" is you are deploying | ||
7789 | images and running tests on the Ubiquiti Networks | ||
7790 | EdgeRouter Lite. | ||
7791 | For information on how to use these tests, see the | ||
7792 | comments at the top of the EdgeRouterTarget | ||
7793 | <filename>meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py</filename> | ||
7794 | file. | ||
7795 | </para></listitem> | ||
7796 | <listitem><para><emphasis>"GrubTarget":</emphasis> | ||
7797 | Choose the "supports deploying images and running | ||
7798 | tests on any generic PC that boots using GRUB. | ||
7799 | For information on how to use these tests, see the | ||
7800 | comments at the top of the GrubTarget | ||
7801 | <filename>meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py</filename> | ||
7802 | file. | ||
7803 | </para></listitem> | ||
7804 | <listitem><para><emphasis>"<replaceable>your-target</replaceable>":</emphasis> | ||
7805 | Create your own custom target if you want to run | ||
7806 | tests when you are deploying images and running | ||
7807 | tests on a custom machine within your BSP layer. | ||
7808 | To do this, you need to add a Python unit that | ||
7809 | defines the target class under | ||
7810 | <filename>lib/oeqa/controllers/</filename> within | ||
7811 | your layer. | ||
7812 | You must also provide an empty | ||
7813 | <filename>__init__.py</filename>. | ||
7814 | For examples, see files in | ||
7815 | <filename>meta-yocto-bsp/lib/oeqa/controllers/</filename>. | ||
7816 | </para></listitem> | ||
7817 | </itemizedlist> | ||
7818 | </para> | ||
7819 | </section> | ||
7820 | |||
7821 | <section id='selecting-gummiboottarget'> | ||
7822 | <title>Selecting GummibootTarget</title> | ||
7823 | |||
7824 | <para> | ||
7825 | If you did not set <filename>TEST_TARGET</filename> to | ||
7826 | "GummibootTarget", then you do not need any information | ||
7827 | in this section. | ||
7828 | You can skip down to the | ||
7829 | "<link linkend='qemu-image-running-tests'>Running Tests</link>" | ||
7830 | section. | ||
7831 | </para> | ||
7832 | |||
7833 | <para> | ||
7834 | If you did set <filename>TEST_TARGET</filename> to | ||
7835 | "GummibootTarget", you also need to perform a one-time | ||
7836 | setup of your master image by doing the following: | ||
7837 | <orderedlist> | ||
7838 | <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis> | ||
7839 | Be sure that <filename>EFI_PROVIDER</filename> | ||
7840 | is as follows: | ||
7841 | <literallayout class='monospaced'> | ||
7842 | EFI_PROVIDER = "gummiboot" | ||
7843 | </literallayout> | ||
7844 | </para></listitem> | ||
7845 | <listitem><para><emphasis>Build the master image:</emphasis> | ||
7846 | Build the <filename>core-image-testmaster</filename> | ||
7847 | image. | ||
7848 | The <filename>core-image-testmaster</filename> | ||
7849 | recipe is provided as an example for a | ||
7850 | "master" image and you can customize the image | ||
7851 | recipe as you would any other recipe. | ||
7852 | </para> | ||
7853 | <para>Here are the image recipe requirements: | ||
7854 | <itemizedlist> | ||
7855 | <listitem><para>Inherits | ||
7856 | <filename>core-image</filename> | ||
7857 | so that kernel modules are installed. | ||
7858 | </para></listitem> | ||
7859 | <listitem><para>Installs normal linux utilities | ||
7860 | not busybox ones (e.g. | ||
7861 | <filename>bash</filename>, | ||
7862 | <filename>coreutils</filename>, | ||
7863 | <filename>tar</filename>, | ||
7864 | <filename>gzip</filename>, and | ||
7865 | <filename>kmod</filename>). | ||
7866 | </para></listitem> | ||
7867 | <listitem><para>Uses a custom | ||
7868 | Initial RAM Disk (initramfs) image with a | ||
7869 | custom installer. | ||
7870 | A normal image that you can install usually | ||
7871 | creates a single rootfs partition. | ||
7872 | This image uses another installer that | ||
7873 | creates a specific partition layout. | ||
7874 | Not all Board Support Packages (BSPs) | ||
7875 | can use an installer. | ||
7876 | For such cases, you need to manually create | ||
7877 | the following partition layout on the | ||
7878 | target: | ||
7879 | <itemizedlist> | ||
7880 | <listitem><para>First partition mounted | ||
7881 | under <filename>/boot</filename>, | ||
7882 | labeled "boot". | ||
7883 | </para></listitem> | ||
7884 | <listitem><para>The main rootfs | ||
7885 | partition where this image gets | ||
7886 | installed, which is mounted under | ||
7887 | <filename>/</filename>. | ||
7888 | </para></listitem> | ||
7889 | <listitem><para>Another partition | ||
7890 | labeled "testrootfs" where test | ||
7891 | images get deployed. | ||
7892 | </para></listitem> | ||
7893 | </itemizedlist> | ||
7894 | </para></listitem> | ||
7895 | </itemizedlist> | ||
7896 | </para></listitem> | ||
7897 | <listitem><para><emphasis>Install image:</emphasis> | ||
7898 | Install the image that you just built on the target | ||
7899 | system. | ||
7900 | </para></listitem> | ||
7901 | </orderedlist> | ||
7902 | </para> | ||
7903 | |||
7904 | <para> | ||
7905 | The final thing you need to do when setting | ||
7906 | <filename>TEST_TARGET</filename> to "GummibootTarget" is | ||
7907 | to set up the test image: | ||
7908 | <orderedlist> | ||
7909 | <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis> | ||
7910 | Make sure you have the following statements in | ||
7911 | your <filename>local.conf</filename> file: | ||
7912 | <literallayout class='monospaced'> | ||
7913 | IMAGE_FSTYPES += "tar.gz" | ||
7914 | INHERIT += "testimage" | ||
7915 | TEST_TARGET = "GummibootTarget" | ||
7916 | TEST_TARGET_IP = "192.168.2.3" | ||
7917 | </literallayout> | ||
7918 | </para></listitem> | ||
7919 | <listitem><para><emphasis>Build your test image:</emphasis> | ||
7920 | Use BitBake to build the image: | ||
7921 | <literallayout class='monospaced'> | ||
7922 | $ bitbake core-image-sato | ||
7923 | </literallayout> | ||
7924 | </para></listitem> | ||
7925 | </orderedlist> | ||
7926 | </para> | ||
7927 | </section> | ||
7928 | |||
7929 | <section id='power-control'> | ||
7930 | <title>Power Control</title> | ||
7931 | |||
7932 | <para> | ||
7933 | For most hardware targets other than SimpleRemoteTarget, | ||
7934 | you can control power: | ||
7935 | <itemizedlist> | ||
7936 | <listitem><para> | ||
7937 | You can use | ||
7938 | <filename>TEST_POWERCONTROL_CMD</filename> | ||
7939 | together with | ||
7940 | <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename> | ||
7941 | as a command that runs on the host and does power | ||
7942 | cycling. | ||
7943 | The test code passes one argument to that command: | ||
7944 | off, on or cycle (off then on). | ||
7945 | Here is an example that could appear in your | ||
7946 | <filename>local.conf</filename> file: | ||
7947 | <literallayout class='monospaced'> | ||
7948 | TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" | ||
7949 | </literallayout> | ||
7950 | In this example, the expect script does the | ||
7951 | following: | ||
7952 | <literallayout class='monospaced'> | ||
7953 | ssh test@10.11.12.1 "pyctl nuc1 <replaceable>arg</replaceable>" | ||
7954 | </literallayout> | ||
7955 | It then runs a Python script that controls power | ||
7956 | for a label called <filename>nuc1</filename>. | ||
7957 | <note> | ||
7958 | You need to customize | ||
7959 | <filename>TEST_POWERCONTROL_CMD</filename> | ||
7960 | and | ||
7961 | <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename> | ||
7962 | for your own setup. | ||
7963 | The one requirement is that it accepts | ||
7964 | "on", "off", and "cycle" as the last argument. | ||
7965 | </note> | ||
7966 | </para></listitem> | ||
7967 | <listitem><para> | ||
7968 | When no command is defined, it connects to the | ||
7969 | device over SSH and uses the classic reboot command | ||
7970 | to reboot the device. | ||
7971 | Classic reboot is fine as long as the machine | ||
7972 | actually reboots (i.e. the SSH test has not | ||
7973 | failed). | ||
7974 | It is useful for scenarios where you have a simple | ||
7975 | setup, typically with a single board, and where | ||
7976 | some manual interaction is okay from time to time. | ||
7977 | </para></listitem> | ||
7978 | </itemizedlist> | ||
7979 | If you have no hardware to automatically perform power | ||
7980 | control but still wish to experiment with automated | ||
7981 | hardware testing, you can use the dialog-power-control | ||
7982 | script that shows a dialog prompting you to perform the | ||
7983 | required power action. | ||
7984 | This script requires either KDialog or Zenity to be | ||
7985 | installed. | ||
7986 | To use this script, set the | ||
7987 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink> | ||
7988 | variable as follows: | ||
7989 | <literallayout class='monospaced'> | ||
7990 | TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" | ||
7991 | </literallayout> | ||
7992 | </para> | ||
7993 | </section> | ||
7994 | |||
7995 | <section id='serial-console-connection'> | ||
7996 | <title>Serial Console Connection</title> | ||
7997 | |||
7998 | <para> | ||
7999 | For test target classes requiring a serial console | ||
8000 | to interact with the bootloader (e.g. BeagleBoneTarget, | ||
8001 | EdgeRouterTarget, and GrubTarget), you need to | ||
8002 | specify a command to use to connect to the serial console | ||
8003 | of the target machine by using the | ||
8004 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink> | ||
8005 | variable and optionally the | ||
8006 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink> | ||
8007 | variable. | ||
8008 | </para> | ||
8009 | |||
8010 | <para> | ||
8011 | These cases could be a serial terminal program if the | ||
8012 | machine is connected to a local serial port, or a | ||
8013 | <filename>telnet</filename> or | ||
8014 | <filename>ssh</filename> command connecting to a remote | ||
8015 | console server. | ||
8016 | Regardless of the case, the command simply needs to | ||
8017 | connect to the serial console and forward that connection | ||
8018 | to standard input and output as any normal terminal | ||
8019 | program does. | ||
8020 | For example, to use the picocom terminal program on | ||
8021 | serial device <filename>/dev/ttyUSB0</filename> | ||
8022 | at 115200bps, you would set the variable as follows: | ||
8023 | <literallayout class='monospaced'> | ||
8024 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | ||
8025 | </literallayout> | ||
8026 | For local devices where the serial port device disappears | ||
8027 | when the device reboots, an additional "serdevtry" wrapper | ||
8028 | script is provided. | ||
8029 | To use this wrapper, simply prefix the terminal command | ||
8030 | with | ||
8031 | <filename>${COREBASE}/scripts/contrib/serdevtry</filename>: | ||
8032 | <literallayout class='monospaced'> | ||
8033 | TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b | ||
8034 | 115200 /dev/ttyUSB0" | ||
8035 | </literallayout> | ||
8036 | </para> | ||
8037 | </section> | ||
8038 | </section> | ||
8039 | |||
8040 | <section id="qemu-image-running-tests"> | ||
8041 | <title>Running Tests</title> | ||
8042 | |||
8043 | <para> | ||
8044 | You can start the tests automatically or manually: | ||
8045 | <itemizedlist> | ||
8046 | <listitem><para><emphasis>Automatically running tests:</emphasis> | ||
8047 | To run the tests automatically after the | ||
8048 | OpenEmbedded build system successfully creates an image, | ||
8049 | first set the | ||
8050 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink> | ||
8051 | variable to "1" in your <filename>local.conf</filename> | ||
8052 | file in the | ||
8053 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
8054 | <literallayout class='monospaced'> | ||
8055 | TEST_IMAGE = "1" | ||
8056 | </literallayout> | ||
8057 | Next, build your image. | ||
8058 | If the image successfully builds, the tests will be | ||
8059 | run: | ||
8060 | <literallayout class='monospaced'> | ||
8061 | bitbake core-image-sato | ||
8062 | </literallayout></para></listitem> | ||
8063 | <listitem><para><emphasis>Manually running tests:</emphasis> | ||
8064 | To manually run the tests, first globally inherit the | ||
8065 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink> | ||
8066 | class by editing your <filename>local.conf</filename> | ||
8067 | file: | ||
8068 | <literallayout class='monospaced'> | ||
8069 | INHERIT += "testimage" | ||
8070 | </literallayout> | ||
8071 | Next, use BitBake to run the tests: | ||
8072 | <literallayout class='monospaced'> | ||
8073 | bitbake -c testimage <replaceable>image</replaceable> | ||
8074 | </literallayout></para></listitem> | ||
8075 | </itemizedlist> | ||
8076 | </para> | ||
8077 | |||
8078 | <para> | ||
8079 | All test files reside in | ||
8080 | <filename>meta/lib/oeqa/runtime</filename> in the | ||
8081 | <link linkend='source-directory'>Source Directory</link>. | ||
8082 | A test name maps directly to a Python module. | ||
8083 | Each test module may contain a number of individual tests. | ||
8084 | Tests are usually grouped together by the area | ||
8085 | tested (e.g tests for systemd reside in | ||
8086 | <filename>meta/lib/oeqa/runtime/systemd.py</filename>). | ||
8087 | </para> | ||
8088 | |||
8089 | <para> | ||
8090 | You can add tests to any layer provided you place them in the | ||
8091 | proper area and you extend | ||
8092 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink> | ||
8093 | in the <filename>local.conf</filename> file as normal. | ||
8094 | Be sure that tests reside in | ||
8095 | <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>. | ||
8096 | <note> | ||
8097 | Be sure that module names do not collide with module names | ||
8098 | used in the default set of test modules in | ||
8099 | <filename>meta/lib/oeqa/runtime</filename>. | ||
8100 | </note> | ||
8101 | </para> | ||
8102 | |||
8103 | <para> | ||
8104 | You can change the set of tests run by appending or overriding | ||
8105 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink> | ||
8106 | variable in <filename>local.conf</filename>. | ||
8107 | Each name in <filename>TEST_SUITES</filename> represents a | ||
8108 | required test for the image. | ||
8109 | Test modules named within <filename>TEST_SUITES</filename> | ||
8110 | cannot be skipped even if a test is not suitable for an image | ||
8111 | (e.g. running the RPM tests on an image without | ||
8112 | <filename>rpm</filename>). | ||
8113 | Appending "auto" to <filename>TEST_SUITES</filename> causes the | ||
8114 | build system to try to run all tests that are suitable for the | ||
8115 | image (i.e. each test module may elect to skip itself). | ||
8116 | </para> | ||
8117 | |||
8118 | <para> | ||
8119 | The order you list tests in <filename>TEST_SUITES</filename> | ||
8120 | is important and influences test dependencies. | ||
8121 | Consequently, tests that depend on other tests should be added | ||
8122 | after the test on which they depend. | ||
8123 | For example, since the <filename>ssh</filename> test | ||
8124 | depends on the | ||
8125 | <filename>ping</filename> test, "ssh" needs to come after | ||
8126 | "ping" in the list. | ||
8127 | The test class provides no re-ordering or dependency handling. | ||
8128 | <note> | ||
8129 | Each module can have multiple classes with multiple test | ||
8130 | methods. | ||
8131 | And, Python <filename>unittest</filename> rules apply. | ||
8132 | </note> | ||
8133 | </para> | ||
8134 | |||
8135 | <para> | ||
8136 | Here are some things to keep in mind when running tests: | ||
8137 | <itemizedlist> | ||
8138 | <listitem><para>The default tests for the image are defined | ||
8139 | as: | ||
8140 | <literallayout class='monospaced'> | ||
8141 | DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" | ||
8142 | </literallayout></para></listitem> | ||
8143 | <listitem><para>Add your own test to the list of the | ||
8144 | by using the following: | ||
8145 | <literallayout class='monospaced'> | ||
8146 | TEST_SUITES_append = " mytest" | ||
8147 | </literallayout></para></listitem> | ||
8148 | <listitem><para>Run a specific list of tests as follows: | ||
8149 | <literallayout class='monospaced'> | ||
8150 | TEST_SUITES = "test1 test2 test3" | ||
8151 | </literallayout> | ||
8152 | Remember, order is important. | ||
8153 | Be sure to place a test that is dependent on another test | ||
8154 | later in the order.</para></listitem> | ||
8155 | </itemizedlist> | ||
8156 | </para> | ||
8157 | </section> | ||
8158 | |||
8159 | <section id="exporting-tests"> | ||
8160 | <title>Exporting Tests</title> | ||
8161 | |||
8162 | <para> | ||
8163 | You can export tests so that they can run independently of | ||
8164 | the build system. | ||
8165 | Exporting tests is required if you want to be able to hand | ||
8166 | the test execution off to a scheduler. | ||
8167 | You can only export tests that are defined in | ||
8168 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>. | ||
8169 | </para> | ||
8170 | |||
8171 | <para> | ||
8172 | If your image is already built, make sure the following are set | ||
8173 | in your <filename>local.conf</filename> file. | ||
8174 | Be sure to provide the IP address you need: | ||
8175 | <literallayout class='monospaced'> | ||
8176 | TEST_EXPORT_ONLY = "1" | ||
8177 | TEST_TARGET = "simpleremote" | ||
8178 | TEST_TARGET_IP = "192.168.7.2" | ||
8179 | TEST_SERVER_IP = "192.168.7.1" | ||
8180 | </literallayout> | ||
8181 | You can then export the tests with the following: | ||
8182 | <literallayout class='monospaced'> | ||
8183 | $ bitbake core-image-sato -c testimage | ||
8184 | </literallayout> | ||
8185 | Exporting the tests places them in the | ||
8186 | <link linkend='build-directory'>Build Directory</link> in | ||
8187 | <filename>tmp/testimage/core-image-sato</filename>, which | ||
8188 | is controlled by the | ||
8189 | <filename>TEST_EXPORT_DIR</filename> variable. | ||
8190 | </para> | ||
8191 | |||
8192 | <para> | ||
8193 | You can now run the tests outside of the build environment: | ||
8194 | <literallayout class='monospaced'> | ||
8195 | $ cd tmp/testimage/core-image-sato | ||
8196 | $ ./runexported.py testdata.json | ||
8197 | </literallayout> | ||
8198 | <note> | ||
8199 | This "export" feature does not deploy or boot the target | ||
8200 | image. | ||
8201 | Your target (be it a Qemu or hardware one) | ||
8202 | has to already be up and running when you call | ||
8203 | <filename>runexported.py</filename> | ||
8204 | </note> | ||
8205 | </para> | ||
8206 | |||
8207 | <para> | ||
8208 | The exported data (i.e. <filename>testdata.json</filename>) | ||
8209 | contains paths to the Build Directory. | ||
8210 | Thus, the contents of the directory can be moved | ||
8211 | to another machine as long as you update some paths in the | ||
8212 | JSON. | ||
8213 | Usually, you only care about the | ||
8214 | <filename>${DEPLOY_DIR}/rpm</filename> directory | ||
8215 | (assuming the RPM and Smart tests are enabled). | ||
8216 | Consequently, running the tests on other machine | ||
8217 | means that you have to move the contents and call | ||
8218 | <filename>runexported.py</filename> with | ||
8219 | "‐‐deploy-dir <replaceable>path</replaceable>" as | ||
8220 | follows: | ||
8221 | <literallayout class='monospaced'> | ||
8222 | ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json | ||
8223 | </literallayout> | ||
8224 | <filename>runexported.py</filename> accepts other arguments | ||
8225 | as well as described using <filename>‐‐help</filename>. | ||
8226 | </para> | ||
8227 | </section> | ||
8228 | |||
8229 | <section id="qemu-image-writing-new-tests"> | ||
8230 | <title>Writing New Tests</title> | ||
8231 | |||
8232 | <para> | ||
8233 | As mentioned previously, all new test files need to be in the | ||
8234 | proper place for the build system to find them. | ||
8235 | New tests for additional functionality outside of the core | ||
8236 | should be added to the layer that adds the functionality, in | ||
8237 | <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename> | ||
8238 | (as long as | ||
8239 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink> | ||
8240 | is extended in the layer's | ||
8241 | <filename>layer.conf</filename> file as normal). | ||
8242 | Just remember that filenames need to map directly to test | ||
8243 | (module) names and that you do not use module names that | ||
8244 | collide with existing core tests. | ||
8245 | </para> | ||
8246 | |||
8247 | <para> | ||
8248 | To create a new test, start by copying an existing module | ||
8249 | (e.g. <filename>syslog.py</filename> or | ||
8250 | <filename>gcc.py</filename> are good ones to use). | ||
8251 | Test modules can use code from | ||
8252 | <filename>meta/lib/oeqa/utils</filename>, which are helper | ||
8253 | classes. | ||
8254 | </para> | ||
8255 | |||
8256 | <note> | ||
8257 | Structure shell commands such that you rely on them and they | ||
8258 | return a single code for success. | ||
8259 | Be aware that sometimes you will need to parse the output. | ||
8260 | See the <filename>df.py</filename> and | ||
8261 | <filename>date.py</filename> modules for examples. | ||
8262 | </note> | ||
8263 | |||
8264 | <para> | ||
8265 | You will notice that all test classes inherit | ||
8266 | <filename>oeRuntimeTest</filename>, which is found in | ||
8267 | <filename>meta/lib/oetest.py</filename>. | ||
8268 | This base class offers some helper attributes, which are | ||
8269 | described in the following sections: | ||
8270 | </para> | ||
8271 | |||
8272 | <section id='qemu-image-writing-tests-class-methods'> | ||
8273 | <title>Class Methods</title> | ||
8274 | |||
8275 | <para> | ||
8276 | Class methods are as follows: | ||
8277 | <itemizedlist> | ||
8278 | <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis> | ||
8279 | Returns "True" if <filename>pkg</filename> is in the | ||
8280 | installed package list of the image, which is based | ||
8281 | on the manifest file that is generated during the | ||
8282 | <filename>do_rootfs</filename> task. | ||
8283 | </para></listitem> | ||
8284 | <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis> | ||
8285 | Returns "True" if the feature is in | ||
8286 | <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> | ||
8287 | or | ||
8288 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>. | ||
8289 | </para></listitem> | ||
8290 | </itemizedlist> | ||
8291 | </para> | ||
8292 | </section> | ||
8293 | |||
8294 | <section id='qemu-image-writing-tests-class-attributes'> | ||
8295 | <title>Class Attributes</title> | ||
8296 | |||
8297 | <para> | ||
8298 | Class attributes are as follows: | ||
8299 | <itemizedlist> | ||
8300 | <listitem><para><emphasis><filename>pscmd</filename>:</emphasis> | ||
8301 | Equals "ps -ef" if <filename>procps</filename> is | ||
8302 | installed in the image. | ||
8303 | Otherwise, <filename>pscmd</filename> equals | ||
8304 | "ps" (busybox). | ||
8305 | </para></listitem> | ||
8306 | <listitem><para><emphasis><filename>tc</filename>:</emphasis> | ||
8307 | The called text context, which gives access to the | ||
8308 | following attributes: | ||
8309 | <itemizedlist> | ||
8310 | <listitem><para><emphasis><filename>d</filename>:</emphasis> | ||
8311 | The BitBake datastore, which allows you to | ||
8312 | use stuff such as | ||
8313 | <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>. | ||
8314 | </para></listitem> | ||
8315 | <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis> | ||
8316 | Used internally. | ||
8317 | The tests do not need these. | ||
8318 | </para></listitem> | ||
8319 | <listitem><para><emphasis><filename>filesdir</filename>:</emphasis> | ||
8320 | The absolute path to | ||
8321 | <filename>meta/lib/oeqa/runtime/files</filename>, | ||
8322 | which contains helper files for tests meant | ||
8323 | for copying on the target such as small | ||
8324 | files written in C for compilation. | ||
8325 | </para></listitem> | ||
8326 | <listitem><para><emphasis><filename>target</filename>:</emphasis> | ||
8327 | The target controller object used to deploy | ||
8328 | and start an image on a particular target | ||
8329 | (e.g. QemuTarget, SimpleRemote, and | ||
8330 | GummibootTarget). | ||
8331 | Tests usually use the following: | ||
8332 | <itemizedlist> | ||
8333 | <listitem><para><emphasis><filename>ip</filename>:</emphasis> | ||
8334 | The target's IP address. | ||
8335 | </para></listitem> | ||
8336 | <listitem><para><emphasis><filename>server_ip</filename>:</emphasis> | ||
8337 | The host's IP address, which is | ||
8338 | usually used by the "smart" test | ||
8339 | suite. | ||
8340 | </para></listitem> | ||
8341 | <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis> | ||
8342 | The single, most used method. | ||
8343 | This command is a wrapper for: | ||
8344 | <filename>ssh root@host "cmd"</filename>. | ||
8345 | The command returns a tuple: | ||
8346 | (status, output), which are what | ||
8347 | their names imply - the return code | ||
8348 | of "cmd" and whatever output | ||
8349 | it produces. | ||
8350 | The optional timeout argument | ||
8351 | represents the number of seconds the | ||
8352 | test should wait for "cmd" to | ||
8353 | return. | ||
8354 | If the argument is "None", the | ||
8355 | test uses the default instance's | ||
8356 | timeout period, which is 300 | ||
8357 | seconds. | ||
8358 | If the argument is "0", the test | ||
8359 | runs until the command returns. | ||
8360 | </para></listitem> | ||
8361 | <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis> | ||
8362 | <filename>scp localpath root@ip:remotepath</filename>. | ||
8363 | </para></listitem> | ||
8364 | <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis> | ||
8365 | <filename>scp root@host:remotepath localpath</filename>. | ||
8366 | </para></listitem> | ||
8367 | </itemizedlist></para></listitem> | ||
8368 | </itemizedlist></para></listitem> | ||
8369 | </itemizedlist> | ||
8370 | </para> | ||
8371 | </section> | ||
8372 | |||
8373 | <section id='qemu-image-writing-tests-instance-attributes'> | ||
8374 | <title>Instance Attributes</title> | ||
8375 | |||
8376 | <para> | ||
8377 | A single instance attribute exists, which is | ||
8378 | <filename>target</filename>. | ||
8379 | The <filename>target</filename> instance attribute is | ||
8380 | identical to the class attribute of the same name, which | ||
8381 | is described in the previous section. | ||
8382 | This attribute exists as both an instance and class | ||
8383 | attribute so tests can use | ||
8384 | <filename>self.target.run(cmd)</filename> in instance | ||
8385 | methods instead of | ||
8386 | <filename>oeRuntimeTest.tc.target.run(cmd)</filename>. | ||
8387 | </para> | ||
8388 | </section> | ||
8389 | </section> | ||
8390 | </section> | ||
8391 | |||
8392 | <section id="platdev-gdb-remotedebug"> | ||
8393 | <title>Debugging With the GNU Project Debugger (GDB) Remotely</title> | ||
8394 | |||
8395 | <para> | ||
8396 | GDB allows you to examine running programs, which in turn helps you to understand and fix problems. | ||
8397 | It also allows you to perform post-mortem style analysis of program crashes. | ||
8398 | GDB is available as a package within the Yocto Project and is | ||
8399 | installed in SDK images by default. | ||
8400 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter | ||
8401 | in the Yocto Project Reference Manual for a description of these images. | ||
8402 | You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>. | ||
8403 | </para> | ||
8404 | |||
8405 | <tip> | ||
8406 | For best results, install debug (<filename>-dbg</filename>) packages | ||
8407 | for the applications you are going to debug. | ||
8408 | Doing so makes extra debug symbols available that give you more | ||
8409 | meaningful output. | ||
8410 | </tip> | ||
8411 | |||
8412 | <para> | ||
8413 | Sometimes, due to memory or disk space constraints, it is not possible | ||
8414 | to use GDB directly on the remote target to debug applications. | ||
8415 | These constraints arise because GDB needs to load the debugging information and the | ||
8416 | binaries of the process being debugged. | ||
8417 | Additionally, GDB needs to perform many computations to locate information such as function | ||
8418 | names, variable names and values, stack traces and so forth - even before starting the | ||
8419 | debugging process. | ||
8420 | These extra computations place more load on the target system and can alter the | ||
8421 | characteristics of the program being debugged. | ||
8422 | </para> | ||
8423 | |||
8424 | <para> | ||
8425 | To help get past the previously mentioned constraints, you can use Gdbserver. | ||
8426 | Gdbserver runs on the remote target and does not load any debugging information | ||
8427 | from the debugged process. | ||
8428 | Instead, a GDB instance processes the debugging information that is run on a | ||
8429 | remote computer - the host GDB. | ||
8430 | The host GDB then sends control commands to Gdbserver to make it stop or start the debugged | ||
8431 | program, as well as read or write memory regions of that debugged program. | ||
8432 | All the debugging information loaded and processed as well | ||
8433 | as all the heavy debugging is done by the host GDB. | ||
8434 | Offloading these processes gives the Gdbserver running on the target a chance to remain | ||
8435 | small and fast. | ||
8436 | <note> | ||
8437 | By default, source files are part of the | ||
8438 | <filename>*-dbg</filename> packages in order to enable GDB | ||
8439 | to show source lines in its output. | ||
8440 | You can save further space on the target by setting the | ||
8441 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink> | ||
8442 | variable to "debug-without-src" so that these packages do not | ||
8443 | include the source files. | ||
8444 | </note> | ||
8445 | </para> | ||
8446 | |||
8447 | <para> | ||
8448 | Because the host GDB is responsible for loading the debugging information and | ||
8449 | for doing the necessary processing to make actual debugging happen, | ||
8450 | you have to make sure the host can access the unstripped binaries complete | ||
8451 | with their debugging information and also be sure the target is compiled with no optimizations. | ||
8452 | The host GDB must also have local access to all the libraries used by the | ||
8453 | debugged program. | ||
8454 | Because Gdbserver does not need any local debugging information, the binaries on | ||
8455 | the remote target can remain stripped. | ||
8456 | However, the binaries must also be compiled without optimization | ||
8457 | so they match the host's binaries. | ||
8458 | </para> | ||
8459 | |||
8460 | <para> | ||
8461 | To remain consistent with GDB documentation and terminology, the binary being debugged | ||
8462 | on the remote target machine is referred to as the "inferior" binary. | ||
8463 | For documentation on GDB see the | ||
8464 | <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>. | ||
8465 | </para> | ||
8466 | |||
8467 | <para> | ||
8468 | The remainder of this section describes the steps you need to take | ||
8469 | to debug using the GNU project debugger. | ||
8470 | </para> | ||
8471 | |||
8472 | <section id='platdev-gdb-remotedebug-setup'> | ||
8473 | <title>Set Up the Cross-Development Debugging Environment</title> | ||
8474 | |||
8475 | <para> | ||
8476 | Before you can initiate a remote debugging session, you need | ||
8477 | to be sure you have set up the cross-development environment, | ||
8478 | toolchain, and sysroot. | ||
8479 | The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>" | ||
8480 | chapter of the Yocto Project Application Developer's Guide | ||
8481 | describes this process. | ||
8482 | Be sure you have read that chapter and have set up | ||
8483 | your environment. | ||
8484 | </para> | ||
8485 | </section> | ||
8486 | |||
8487 | <section id="platdev-gdb-remotedebug-launch-gdbserver"> | ||
8488 | <title>Launch Gdbserver on the Target</title> | ||
8489 | |||
8490 | <para> | ||
8491 | Make sure Gdbserver is installed on the target. | ||
8492 | If it is not, install the package | ||
8493 | <filename>gdbserver</filename>, which needs the | ||
8494 | <filename>libthread-db1</filename> package. | ||
8495 | </para> | ||
8496 | |||
8497 | <para> | ||
8498 | Here is an example, that when entered from the host, | ||
8499 | connects to the target and launches Gdbserver in order to | ||
8500 | "debug" a binary named <filename>helloworld</filename>: | ||
8501 | <literallayout class='monospaced'> | ||
8502 | $ gdbserver localhost:2345 /usr/bin/helloworld | ||
8503 | </literallayout> | ||
8504 | Gdbserver should now be listening on port 2345 for debugging | ||
8505 | commands coming from a remote GDB process that is running on | ||
8506 | the host computer. | ||
8507 | Communication between Gdbserver and the host GDB are done | ||
8508 | using TCP. | ||
8509 | To use other communication protocols, please refer to the | ||
8510 | <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. | ||
8511 | </para> | ||
8512 | </section> | ||
8513 | |||
8514 | <section id="platdev-gdb-remotedebug-launch-gdb"> | ||
8515 | <title>Launch GDB on the Host Computer</title> | ||
8516 | |||
8517 | <para> | ||
8518 | Running GDB on the host computer takes a number of stages, which | ||
8519 | this section describes. | ||
8520 | </para> | ||
8521 | |||
8522 | <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> | ||
8523 | <title>Build the Cross-GDB Package</title> | ||
8524 | <para> | ||
8525 | A suitable GDB cross-binary is required that runs on your | ||
8526 | host computer but also knows about the the ABI of the | ||
8527 | remote target. | ||
8528 | You can get this binary from the | ||
8529 | <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>. | ||
8530 | Here is an example where the toolchain has been installed | ||
8531 | in the default directory | ||
8532 | <filename>/opt/poky/&DISTRO;</filename>: | ||
8533 | <literallayout class='monospaced'> | ||
8534 | /opt/poky/&DISTRO;/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb | ||
8535 | </literallayout> | ||
8536 | where <filename>arm</filename> is the target architecture | ||
8537 | and <filename>linux-gnueabi</filename> is the target ABI. | ||
8538 | </para> | ||
8539 | |||
8540 | <para> | ||
8541 | Alternatively, you can use BitBake to build the | ||
8542 | <filename>gdb-cross</filename> binary. | ||
8543 | Here is an example: | ||
8544 | <literallayout class='monospaced'> | ||
8545 | $ bitbake gdb-cross | ||
8546 | </literallayout> | ||
8547 | Once the binary is built, you can find it here: | ||
8548 | <literallayout class='monospaced'> | ||
8549 | tmp/sysroots/<replaceable>host-arch</replaceable>/usr/bin/<replaceable>target-platform</replaceable>/<replaceable>target-abi</replaceable>-gdb | ||
8550 | </literallayout> | ||
8551 | </para> | ||
8552 | </section> | ||
8553 | |||
8554 | <section id='create-the-gdb-initialization-file'> | ||
8555 | <title>Create the GDB Initialization File and Point to Your Root Filesystem</title> | ||
8556 | |||
8557 | <para> | ||
8558 | Aside from the GDB cross-binary, you also need a GDB | ||
8559 | initialization file in the same top directory in which | ||
8560 | your binary resides. | ||
8561 | When you start GDB on your host development system, GDB | ||
8562 | finds this initialization file and executes all the | ||
8563 | commands within. | ||
8564 | For information on the <filename>.gdbinit</filename>, see | ||
8565 | "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>", | ||
8566 | which is maintained by | ||
8567 | <ulink url='http://www.sourceware.org'>sourceware.org</ulink>. | ||
8568 | </para> | ||
8569 | |||
8570 | <para> | ||
8571 | You need to add a statement in the | ||
8572 | <filename>~/.gdbinit</filename> file that points to your | ||
8573 | root filesystem. | ||
8574 | Here is an example that points to the root filesystem for | ||
8575 | an ARM-based target device: | ||
8576 | <literallayout class='monospaced'> | ||
8577 | set sysroot ~/sysroot_arm | ||
8578 | </literallayout> | ||
8579 | </para> | ||
8580 | </section> | ||
8581 | |||
8582 | <section id="platdev-gdb-remotedebug-launch-gdb-launchhost"> | ||
8583 | <title>Launch the Host GDB</title> | ||
8584 | |||
8585 | <para> | ||
8586 | Before launching the host GDB, you need to be sure | ||
8587 | you have sourced the cross-debugging environment script, | ||
8588 | which if you installed the root filesystem in the default | ||
8589 | location is at <filename>/opt/poky/&DISTRO;</filename> | ||
8590 | and begins with the string "environment-setup". | ||
8591 | For more information, see the | ||
8592 | "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>" | ||
8593 | section in the Yocto Project Application Developer's | ||
8594 | Guide. | ||
8595 | </para> | ||
8596 | |||
8597 | <para> | ||
8598 | Finally, switch to the directory where the binary resides | ||
8599 | and run the <filename>cross-gdb</filename> binary. | ||
8600 | Provide the binary file you are going to debug. | ||
8601 | For example, the following command continues with the | ||
8602 | example used in the previous section by loading | ||
8603 | the <filename>helloworld</filename> binary as well as the | ||
8604 | debugging information: | ||
8605 | <literallayout class='monospaced'> | ||
8606 | $ arm-poky-linux-gnuabi-gdb helloworld | ||
8607 | </literallayout> | ||
8608 | The commands in your <filename>.gdbinit</filename> execute | ||
8609 | and the GDB prompt appears. | ||
8610 | </para> | ||
8611 | </section> | ||
8612 | </section> | ||
8613 | |||
8614 | <section id='platdev-gdb-connect-to-the-remote-gdb-server'> | ||
8615 | <title>Connect to the Remote GDB Server</title> | ||
8616 | |||
8617 | <para> | ||
8618 | From the target, you need to connect to the remote GDB | ||
8619 | server that is running on the host. | ||
8620 | You need to specify the remote host and port. | ||
8621 | Here is the command continuing with the example: | ||
8622 | <literallayout class='monospaced'> | ||
8623 | target remote 192.168.7.2:2345 | ||
8624 | </literallayout> | ||
8625 | </para> | ||
8626 | </section> | ||
8627 | |||
8628 | <section id="platdev-gdb-remotedebug-launch-gdb-using"> | ||
8629 | <title>Use the Debugger</title> | ||
8630 | |||
8631 | <para> | ||
8632 | You can now proceed with debugging as normal - as if you were debugging | ||
8633 | on the local machine. | ||
8634 | For example, to instruct GDB to break in the "main" function and then | ||
8635 | continue with execution of the inferior binary use the following commands | ||
8636 | from within GDB: | ||
8637 | <literallayout class='monospaced'> | ||
8638 | (gdb) break main | ||
8639 | (gdb) continue | ||
8640 | </literallayout> | ||
8641 | </para> | ||
8642 | |||
8643 | <para> | ||
8644 | For more information about using GDB, see the project's online documentation at | ||
8645 | <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. | ||
8646 | </para> | ||
8647 | </section> | ||
8648 | </section> | ||
8649 | |||
8650 | <section id='debugging-parallel-make-races'> | ||
8651 | <title>Debugging Parallel Make Races</title> | ||
8652 | |||
8653 | <para> | ||
8654 | A parallel <filename>make</filename> race occurs when the build | ||
8655 | consists of several parts that are run simultaneously and | ||
8656 | a situation occurs when the output or result of one | ||
8657 | part is not ready for use with a different part of the build that | ||
8658 | depends on that output. | ||
8659 | Parallel make races are annoying and can sometimes be difficult | ||
8660 | to reproduce and fix. | ||
8661 | However, some simple tips and tricks exist that can help | ||
8662 | you debug and fix them. | ||
8663 | This section presents a real-world example of an error encountered | ||
8664 | on the Yocto Project autobuilder and the process used to fix it. | ||
8665 | </para> | ||
8666 | |||
8667 | <section id='the-failure'> | ||
8668 | <title>The Failure</title> | ||
8669 | |||
8670 | <para> | ||
8671 | For this example, assume that you are building an image that | ||
8672 | depends on the "neard" package. | ||
8673 | And, during the build, BitBake runs into problems and | ||
8674 | creates the following output. | ||
8675 | <note> | ||
8676 | This example log file has longer lines artificially | ||
8677 | broken to make the listing easier to read. | ||
8678 | </note> | ||
8679 | If you examine the output or the log file, you see the | ||
8680 | failure during <filename>make</filename>: | ||
8681 | <literallayout class='monospaced'> | ||
8682 | | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] | ||
8683 | | DEBUG: Executing shell function do_compile | ||
8684 | | NOTE: make -j 16 | ||
8685 | | make ‐‐no-print-directory all-am | ||
8686 | | /bin/mkdir -p include/near | ||
8687 | | /bin/mkdir -p include/near | ||
8688 | | /bin/mkdir -p include/near | ||
8689 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8690 | 0.14-r0/neard-0.14/include/types.h include/near/types.h | ||
8691 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8692 | 0.14-r0/neard-0.14/include/log.h include/near/log.h | ||
8693 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8694 | 0.14-r0/neard-0.14/include/plugin.h include/near/plugin.h | ||
8695 | | /bin/mkdir -p include/near | ||
8696 | | /bin/mkdir -p include/near | ||
8697 | | /bin/mkdir -p include/near | ||
8698 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8699 | 0.14-r0/neard-0.14/include/tag.h include/near/tag.h | ||
8700 | | /bin/mkdir -p include/near | ||
8701 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8702 | 0.14-r0/neard-0.14/include/adapter.h include/near/adapter.h | ||
8703 | | /bin/mkdir -p include/near | ||
8704 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8705 | 0.14-r0/neard-0.14/include/ndef.h include/near/ndef.h | ||
8706 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8707 | 0.14-r0/neard-0.14/include/tlv.h include/near/tlv.h | ||
8708 | | /bin/mkdir -p include/near | ||
8709 | | /bin/mkdir -p include/near | ||
8710 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8711 | 0.14-r0/neard-0.14/include/setting.h include/near/setting.h | ||
8712 | | /bin/mkdir -p include/near | ||
8713 | | /bin/mkdir -p include/near | ||
8714 | | /bin/mkdir -p include/near | ||
8715 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8716 | 0.14-r0/neard-0.14/include/device.h include/near/device.h | ||
8717 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8718 | 0.14-r0/neard-0.14/include/nfc_copy.h include/near/nfc_copy.h | ||
8719 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8720 | 0.14-r0/neard-0.14/include/snep.h include/near/snep.h | ||
8721 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8722 | 0.14-r0/neard-0.14/include/version.h include/near/version.h | ||
8723 | | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ | ||
8724 | 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h | ||
8725 | | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h | ||
8726 | | i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ | ||
8727 | build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/ | ||
8728 | yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 | ||
8729 | -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ | ||
8730 | lib/glib-2.0/include -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/ | ||
8731 | tmp/sysroots/qemux86/usr/include/dbus-1.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/ | ||
8732 | nightly-x86/build/build/tmp/sysroots/qemux86/usr/lib/dbus-1.0/include -I/home/pokybuild/yocto-autobuilder/ | ||
8733 | yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/libnl3 | ||
8734 | -DNEAR_PLUGIN_BUILTIN -DPLUGINDIR=\""/usr/lib/near/plugins"\" | ||
8735 | -DCONFIGDIR=\""/etc/neard\"" -O2 -pipe -g -feliminate-unused-debug-types -c | ||
8736 | -o tools/snep-send.o tools/snep-send.c | ||
8737 | | In file included from tools/snep-send.c:16:0: | ||
8738 | | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory | ||
8739 | | #include <near/dbus.h> | ||
8740 | | ^ | ||
8741 | | compilation terminated. | ||
8742 | | make[1]: *** [tools/snep-send.o] Error 1 | ||
8743 | | make[1]: *** Waiting for unfinished jobs.... | ||
8744 | | make: *** [all] Error 2 | ||
8745 | | ERROR: oe_runmake failed | ||
8746 | </literallayout> | ||
8747 | </para> | ||
8748 | </section> | ||
8749 | |||
8750 | <section id='reproducing-the-error'> | ||
8751 | <title>Reproducing the Error</title> | ||
8752 | |||
8753 | <para> | ||
8754 | Because race conditions are intermittent, they do not | ||
8755 | manifest themselves every time you do the build. | ||
8756 | In fact, most times the build will complete without problems | ||
8757 | even though the potential race condition exists. | ||
8758 | Thus, once the error surfaces, you need a way to reproduce it. | ||
8759 | </para> | ||
8760 | |||
8761 | <para> | ||
8762 | In this example, compiling the "neard" package is causing the | ||
8763 | problem. | ||
8764 | So the first thing to do is build "neard" locally. | ||
8765 | Before you start the build, set the | ||
8766 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> | ||
8767 | variable in your <filename>local.conf</filename> file to | ||
8768 | a high number (e.g. "-j 20"). | ||
8769 | Using a high value for <filename>PARALLEL_MAKE</filename> | ||
8770 | increases the chances of the race condition showing up: | ||
8771 | <literallayout class='monospaced'> | ||
8772 | $ bitbake neard | ||
8773 | </literallayout> | ||
8774 | </para> | ||
8775 | |||
8776 | <para> | ||
8777 | Once the local build for "neard" completes, start a | ||
8778 | <filename>devshell</filename> build: | ||
8779 | <literallayout class='monospaced'> | ||
8780 | $ bitbake neard -c devshell | ||
8781 | </literallayout> | ||
8782 | For information on how to use a | ||
8783 | <filename>devshell</filename>, see the | ||
8784 | "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>" | ||
8785 | section. | ||
8786 | </para> | ||
8787 | |||
8788 | <para> | ||
8789 | In the <filename>devshell</filename>, do the following: | ||
8790 | <literallayout class='monospaced'> | ||
8791 | $ make clean | ||
8792 | $ make tools/snep-send.o | ||
8793 | </literallayout> | ||
8794 | The <filename>devshell</filename> commands cause the failure | ||
8795 | to clearly be visible. | ||
8796 | In this case, a missing dependency exists for the "neard" | ||
8797 | Makefile target. | ||
8798 | Here is some abbreviated, sample output with the | ||
8799 | missing dependency clearly visible at the end: | ||
8800 | <literallayout class='monospaced'> | ||
8801 | i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/scott-lenovo/...... | ||
8802 | . | ||
8803 | . | ||
8804 | . | ||
8805 | tools/snep-send.c | ||
8806 | In file included from tools/snep-send.c:16:0: | ||
8807 | tools/../src/near.h:41:23: fatal error: near/dbus.h: No such file or directory | ||
8808 | #include <near/dbus.h> | ||
8809 | ^ | ||
8810 | compilation terminated. | ||
8811 | make: *** [tools/snep-send.o] Error 1 | ||
8812 | $ | ||
8813 | </literallayout> | ||
8814 | </para> | ||
8815 | </section> | ||
8816 | |||
8817 | <section id='creating-a-patch-for-the-fix'> | ||
8818 | <title>Creating a Patch for the Fix</title> | ||
8819 | |||
8820 | <para> | ||
8821 | Because there is a missing dependency for the Makefile | ||
8822 | target, you need to patch the | ||
8823 | <filename>Makefile.am</filename> file, which is generated | ||
8824 | from <filename>Makefile.in</filename>. | ||
8825 | You can use Quilt to create the patch: | ||
8826 | <literallayout class='monospaced'> | ||
8827 | $ quilt new parallelmake.patch | ||
8828 | Patch patches/parallelmake.patch is now on top | ||
8829 | $ quilt add Makefile.am | ||
8830 | File Makefile.am added to patch patches/parallelmake.patch | ||
8831 | </literallayout> | ||
8832 | For more information on using Quilt, see the | ||
8833 | "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>" | ||
8834 | section. | ||
8835 | </para> | ||
8836 | |||
8837 | <para> | ||
8838 | At this point you need to make the edits to | ||
8839 | <filename>Makefile.am</filename> to add the missing | ||
8840 | dependency. | ||
8841 | For our example, you have to add the following line | ||
8842 | to the file: | ||
8843 | <literallayout class='monospaced'> | ||
8844 | tools/snep-send.$(OBJEXT): include/near/dbus.h | ||
8845 | </literallayout> | ||
8846 | </para> | ||
8847 | |||
8848 | <para> | ||
8849 | Once you have edited the file, use the | ||
8850 | <filename>refresh</filename> command to create the patch: | ||
8851 | <literallayout class='monospaced'> | ||
8852 | $ quilt refresh | ||
8853 | Refreshed patch patches/parallelmake.patch | ||
8854 | </literallayout> | ||
8855 | Once the patch file exists, you need to add it back to the | ||
8856 | originating recipe folder. | ||
8857 | Here is an example assuming a top-level | ||
8858 | <link linkend='source-directory'>Source Directory</link> | ||
8859 | named <filename>poky</filename>: | ||
8860 | <literallayout class='monospaced'> | ||
8861 | $ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard | ||
8862 | </literallayout> | ||
8863 | The final thing you need to do to implement the fix in the | ||
8864 | build is to update the "neard" recipe (i.e. | ||
8865 | <filename>neard-0.14.bb</filename>) so that the | ||
8866 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> | ||
8867 | statement includes the patch file. | ||
8868 | The recipe file is in the folder above the patch. | ||
8869 | Here is what the edited <filename>SRC_URI</filename> | ||
8870 | statement would look like: | ||
8871 | <literallayout class='monospaced'> | ||
8872 | SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ | ||
8873 | file://neard.in \ | ||
8874 | file://neard.service.in \ | ||
8875 | file://parallelmake.patch \ | ||
8876 | " | ||
8877 | </literallayout> | ||
8878 | </para> | ||
8879 | |||
8880 | <para> | ||
8881 | With the patch complete and moved to the correct folder and | ||
8882 | the <filename>SRC_URI</filename> statement updated, you can | ||
8883 | exit the <filename>devshell</filename>: | ||
8884 | <literallayout class='monospaced'> | ||
8885 | $ exit | ||
8886 | </literallayout> | ||
8887 | </para> | ||
8888 | </section> | ||
8889 | |||
8890 | <section id='testing-the-build'> | ||
8891 | <title>Testing the Build</title> | ||
8892 | |||
8893 | <para> | ||
8894 | With everything in place, you can get back to trying the | ||
8895 | build again locally: | ||
8896 | <literallayout class='monospaced'> | ||
8897 | $ bitbake neard | ||
8898 | </literallayout> | ||
8899 | This build should succeed. | ||
8900 | </para> | ||
8901 | |||
8902 | <para> | ||
8903 | Now you can open up a <filename>devshell</filename> again | ||
8904 | and repeat the clean and make operations as follows: | ||
8905 | <literallayout class='monospaced'> | ||
8906 | $ bitbake neard -c devshell | ||
8907 | $ make clean | ||
8908 | $ make tools/snep-send.o | ||
8909 | </literallayout> | ||
8910 | The build should work without issue. | ||
8911 | </para> | ||
8912 | |||
8913 | <para> | ||
8914 | As with all solved problems, if they originated upstream, you | ||
8915 | need to submit the fix for the recipe in OE-Core and upstream | ||
8916 | so that the problem is taken care of at its source. | ||
8917 | See the | ||
8918 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
8919 | section for more information. | ||
8920 | </para> | ||
8921 | </section> | ||
8922 | </section> | ||
8923 | |||
8924 | <section id="examining-builds-using-toaster"> | ||
8925 | <title>Examining Builds Using the Toaster API</title> | ||
8926 | |||
8927 | <para> | ||
8928 | Toaster is an Application Programming Interface (API) and | ||
8929 | web-based interface to the OpenEmbedded build system, which uses | ||
8930 | BitBake. | ||
8931 | Both interfaces are based on a Representational State Transfer | ||
8932 | (REST) API that queries for and returns build information using | ||
8933 | <filename>GET</filename> and <filename>JSON</filename>. | ||
8934 | These types of search operations retrieve sets of objects from | ||
8935 | a datastore used to collect build information. | ||
8936 | The results contain all the data for the objects being returned. | ||
8937 | You can order the results of the search by key and the search | ||
8938 | parameters are consistent for all object types. | ||
8939 | </para> | ||
8940 | |||
8941 | <para> | ||
8942 | Using the interfaces you can do the following: | ||
8943 | <itemizedlist> | ||
8944 | <listitem><para>See information about the tasks executed | ||
8945 | and reused during the build.</para></listitem> | ||
8946 | <listitem><para>See what is built (recipes and | ||
8947 | packages) and what packages were installed into the final | ||
8948 | image.</para></listitem> | ||
8949 | <listitem><para>See performance-related information such | ||
8950 | as build time, CPU usage, and disk I/O.</para></listitem> | ||
8951 | <listitem><para>Examine error, warning and trace messages | ||
8952 | to aid in debugging.</para></listitem> | ||
8953 | </itemizedlist> | ||
8954 | </para> | ||
8955 | |||
8956 | <note> | ||
8957 | <para>This release of Toaster provides you with information | ||
8958 | about a BitBake run. | ||
8959 | The tool does not allow you to configure and launch a build. | ||
8960 | However, future development includes plans to integrate the | ||
8961 | configuration and build launching capabilities of | ||
8962 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. | ||
8963 | </para> | ||
8964 | <para>For more information on using Hob to build an image, | ||
8965 | see the | ||
8966 | "<link linkend='image-development-using-hob'>Image Development Using Hob</link>" | ||
8967 | section.</para> | ||
8968 | </note> | ||
8969 | |||
8970 | <para> | ||
8971 | The remainder of this section describes what you need to have in | ||
8972 | place to use Toaster, how to start it, use it, and stop it. | ||
8973 | For additional information on installing and running Toaster, see the | ||
8974 | "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" | ||
8975 | section of the "Toaster" wiki page. | ||
8976 | For complete information on the API and its search operation | ||
8977 | URI, parameters, and responses, see the | ||
8978 | <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> | ||
8979 | Wiki page. | ||
8980 | </para> | ||
8981 | |||
8982 | <section id='starting-toaster'> | ||
8983 | <title>Starting Toaster</title> | ||
8984 | |||
8985 | <para> | ||
8986 | Getting set up to use and start Toaster is simple. | ||
8987 | First, be sure you have met the following requirements: | ||
8988 | <itemizedlist> | ||
8989 | <listitem><para>You have set up your | ||
8990 | <link linkend='source-directory'>Source Directory</link> | ||
8991 | by cloning the upstream <filename>poky</filename> | ||
8992 | repository. | ||
8993 | See the | ||
8994 | <link linkend='local-yp-release'>Yocto Project Release</link> | ||
8995 | item for information on how to set up the Source | ||
8996 | Directory.</para></listitem> | ||
8997 | <listitem><para>Be sure your build machine has | ||
8998 | <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink> | ||
8999 | version 1.5 installed.</para></listitem> | ||
9000 | <listitem><para>Make sure that port 8000 and 8200 are | ||
9001 | free (i.e. they have no servers on them). | ||
9002 | </para></listitem> | ||
9003 | </itemizedlist> | ||
9004 | </para> | ||
9005 | |||
9006 | <para> | ||
9007 | Once you have met the requirements, follow these steps to | ||
9008 | start Toaster running in the background of your shell: | ||
9009 | <orderedlist> | ||
9010 | <listitem><para><emphasis>Set up your build environment:</emphasis> | ||
9011 | Source a build environment script (i.e. | ||
9012 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
9013 | or | ||
9014 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). | ||
9015 | </para></listitem> | ||
9016 | <listitem><para><emphasis>Start Toaster:</emphasis> | ||
9017 | Start the Toaster service using this | ||
9018 | command from within your | ||
9019 | <link linkend='build-directory'>Build Directory</link>: | ||
9020 | <literallayout class='monospaced'> | ||
9021 | $ source toaster start | ||
9022 | </literallayout></para></listitem> | ||
9023 | <note> | ||
9024 | The Toaster must be started and running in order | ||
9025 | for it to collect data. | ||
9026 | </note> | ||
9027 | </orderedlist> | ||
9028 | </para> | ||
9029 | |||
9030 | <para> | ||
9031 | When Toaster starts, it creates some additional files in your | ||
9032 | Build Directory. | ||
9033 | Deleting these files will cause you to lose data or interrupt | ||
9034 | Toaster: | ||
9035 | <itemizedlist> | ||
9036 | <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis> | ||
9037 | Toaster's database file.</para></listitem> | ||
9038 | <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis> | ||
9039 | The log file of the web server.</para></listitem> | ||
9040 | <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis> | ||
9041 | The log file of the user interface component. | ||
9042 | </para></listitem> | ||
9043 | <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis> | ||
9044 | The PID of the web server.</para></listitem> | ||
9045 | <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis> | ||
9046 | The PID of the DSI data bridge.</para></listitem> | ||
9047 | <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis> | ||
9048 | The BitBake server's log file.</para></listitem> | ||
9049 | </itemizedlist> | ||
9050 | </para> | ||
9051 | </section> | ||
9052 | |||
9053 | <section id='using-toaster'> | ||
9054 | <title>Using Toaster</title> | ||
9055 | |||
9056 | <para> | ||
9057 | Once Toaster is running, it logs information for any BitBake | ||
9058 | run from your Build Directory. | ||
9059 | This logging is automatic. | ||
9060 | All you need to do is access and use the information. | ||
9061 | </para> | ||
9062 | |||
9063 | <para> | ||
9064 | You access the information one of two ways: | ||
9065 | <itemizedlist> | ||
9066 | <listitem><para>Open a Browser and enter | ||
9067 | <filename>http://localhost:8000</filename> | ||
9068 | for the URL. | ||
9069 | </para></listitem> | ||
9070 | <listitem><para>Use the <filename>xdg-open</filename> | ||
9071 | tool from the shell and pass it the same URL. | ||
9072 | </para></listitem> | ||
9073 | </itemizedlist> | ||
9074 | Either method opens the home page for the Toaster interface. | ||
9075 | </para> | ||
9076 | |||
9077 | <note><title>Notes</title> | ||
9078 | <itemizedlist> | ||
9079 | <listitem><para> | ||
9080 | For information on how to delete information from the | ||
9081 | Toaster database, see the | ||
9082 | <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink> | ||
9083 | wiki page. | ||
9084 | </para></listitem> | ||
9085 | <listitem><para> | ||
9086 | For information on how to set up an instance of Toaster | ||
9087 | on a remote host, see the | ||
9088 | <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink> | ||
9089 | wiki page. | ||
9090 | </para></listitem> | ||
9091 | </itemizedlist> | ||
9092 | </note> | ||
9093 | </section> | ||
9094 | |||
9095 | <section id='examining-toaster-data'> | ||
9096 | <title>Examining Toaster Data</title> | ||
9097 | |||
9098 | <para> | ||
9099 | The Toaster database is persistent regardless of whether you | ||
9100 | start or stop the service. | ||
9101 | </para> | ||
9102 | |||
9103 | <para> | ||
9104 | Toaster's interface shows you a list of builds | ||
9105 | (successful and unsuccessful) for which it has data. | ||
9106 | You can click on any build to see related information. | ||
9107 | This information includes configuration details, information | ||
9108 | about tasks, all recipes and packages built and their | ||
9109 | dependencies, packages and their directory structure as | ||
9110 | installed in your final image, | ||
9111 | execution time, CPU usage and disk I/O per task. | ||
9112 | </para> | ||
9113 | |||
9114 | <para> | ||
9115 | For details on the interface, see the | ||
9116 | <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>. | ||
9117 | </para> | ||
9118 | </section> | ||
9119 | |||
9120 | <section id='stopping-toaster'> | ||
9121 | <title>Stopping Toaster</title> | ||
9122 | |||
9123 | <para> | ||
9124 | Stop the Toaster service with the following command | ||
9125 | from with the | ||
9126 | <link linkend='build-directory'>Build Directory</link>: | ||
9127 | <literallayout class='monospaced'> | ||
9128 | $ source toaster stop | ||
9129 | </literallayout> | ||
9130 | The service stops but the Toaster database remains persistent. | ||
9131 | </para> | ||
9132 | </section> | ||
9133 | </section> | ||
9134 | |||
9135 | <section id="platdev-oprofile"> | ||
9136 | <title>Profiling with OProfile</title> | ||
9137 | |||
9138 | <para> | ||
9139 | <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a | ||
9140 | statistical profiler well suited for finding performance | ||
9141 | bottlenecks in both user-space software and in the kernel. | ||
9142 | This profiler provides answers to questions like "Which functions does my application spend | ||
9143 | the most time in when doing X?" | ||
9144 | Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling | ||
9145 | applications on target hardware straight forward. | ||
9146 | <note> | ||
9147 | For more information on how to set up and run OProfile, see the | ||
9148 | "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" | ||
9149 | section in the Yocto Project Profiling and Tracing Manual. | ||
9150 | </note> | ||
9151 | </para> | ||
9152 | |||
9153 | <para> | ||
9154 | To use OProfile, you need an image that has OProfile installed. | ||
9155 | The easiest way to do this is with "tools-profile" in the | ||
9156 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable. | ||
9157 | You also need debugging symbols to be available on the system where the analysis | ||
9158 | takes place. | ||
9159 | You can gain access to the symbols by using "dbg-pkgs" in the | ||
9160 | <filename>IMAGE_FEATURES</filename> variable or by | ||
9161 | installing the appropriate debug (<filename>-dbg</filename>) | ||
9162 | packages. | ||
9163 | </para> | ||
9164 | |||
9165 | <para> | ||
9166 | For successful call graph analysis, the binaries must preserve the frame | ||
9167 | pointer register and should also be compiled with the | ||
9168 | <filename>-fno-omit-framepointer</filename> flag. | ||
9169 | You can achieve this by setting the | ||
9170 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> | ||
9171 | variable with the following options: | ||
9172 | <literallayout class='monospaced'> | ||
9173 | -fexpensive-optimizations | ||
9174 | -fno-omit-framepointer | ||
9175 | -frename-registers | ||
9176 | -O2 | ||
9177 | </literallayout> | ||
9178 | You can also achieve it by setting the | ||
9179 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename> | ||
9180 | variable to "1" in the <filename>local.conf</filename> configuration file. | ||
9181 | If you use the <filename>DEBUG_BUILD</filename> variable, | ||
9182 | you also add extra debugging information that can make the debug | ||
9183 | packages large. | ||
9184 | </para> | ||
9185 | |||
9186 | <section id="platdev-oprofile-target"> | ||
9187 | <title>Profiling on the Target</title> | ||
9188 | |||
9189 | <para> | ||
9190 | Using OProfile, you can perform all the profiling work on the target device. | ||
9191 | A simple OProfile session might look like the following: | ||
9192 | </para> | ||
9193 | |||
9194 | <para> | ||
9195 | <literallayout class='monospaced'> | ||
9196 | # opcontrol ‐‐reset | ||
9197 | # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 | ||
9198 | . | ||
9199 | . | ||
9200 | [do whatever is being profiled] | ||
9201 | . | ||
9202 | . | ||
9203 | # opcontrol ‐‐stop | ||
9204 | $ opreport -cl | ||
9205 | </literallayout> | ||
9206 | </para> | ||
9207 | |||
9208 | <para> | ||
9209 | In this example, the <filename>reset</filename> command clears any previously profiled data. | ||
9210 | The next command starts OProfile. | ||
9211 | The options used when starting the profiler separate dynamic library data | ||
9212 | within applications, disable kernel profiling, and enable callgraphing up to | ||
9213 | five levels deep. | ||
9214 | <note> | ||
9215 | To profile the kernel, you would specify the | ||
9216 | <filename>‐‐vmlinux=/path/to/vmlinux</filename> option. | ||
9217 | The <filename>vmlinux</filename> file is usually in the source directory in the | ||
9218 | <filename>/boot/</filename> directory and must match the running kernel. | ||
9219 | </note> | ||
9220 | </para> | ||
9221 | |||
9222 | <para> | ||
9223 | After you perform your profiling tasks, the next command stops the profiler. | ||
9224 | After that, you can view results with the <filename>opreport</filename> command with options | ||
9225 | to see the separate library symbols and callgraph information. | ||
9226 | </para> | ||
9227 | |||
9228 | <para> | ||
9229 | Callgraphing logs information about time spent in functions and about a function's | ||
9230 | calling function (parent) and called functions (children). | ||
9231 | The higher the callgraphing depth, the more accurate the results. | ||
9232 | However, higher depths also increase the logging overhead. | ||
9233 | Consequently, you should take care when setting the callgraphing depth. | ||
9234 | <note> | ||
9235 | On ARM, binaries need to have the frame pointer enabled for callgraphing to work. | ||
9236 | To accomplish this use the <filename>-fno-omit-framepointer</filename> option | ||
9237 | with <filename>gcc</filename>. | ||
9238 | </note> | ||
9239 | </para> | ||
9240 | |||
9241 | <para> | ||
9242 | For more information on using OProfile, see the OProfile | ||
9243 | online documentation at | ||
9244 | <ulink url="http://oprofile.sourceforge.net/docs/"/>. | ||
9245 | </para> | ||
9246 | </section> | ||
9247 | |||
9248 | <section id="platdev-oprofile-oprofileui"> | ||
9249 | <title>Using OProfileUI</title> | ||
9250 | |||
9251 | <para> | ||
9252 | A graphical user interface for OProfile is also available. | ||
9253 | You can download and build this interface from the Yocto Project at | ||
9254 | <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>. | ||
9255 | If the "tools-profile" image feature is selected, all necessary binaries | ||
9256 | are installed onto the target device for OProfileUI interaction. | ||
9257 | For a list of image features that ship with the Yocto Project, | ||
9258 | see the | ||
9259 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>" | ||
9260 | section in the Yocto Project Reference Manual. | ||
9261 | </para> | ||
9262 | |||
9263 | <para> | ||
9264 | Even though the source directory usually includes all needed patches on the target device, you | ||
9265 | might find you need other OProfile patches for recent OProfileUI features. | ||
9266 | If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> | ||
9267 | OProfileUI README</ulink> for the most recent information. | ||
9268 | </para> | ||
9269 | |||
9270 | <section id="platdev-oprofile-oprofileui-online"> | ||
9271 | <title>Online Mode</title> | ||
9272 | |||
9273 | <para> | ||
9274 | Using OProfile in online mode assumes a working network connection with the target | ||
9275 | hardware. | ||
9276 | With this connection, you just need to run "oprofile-server" on the device. | ||
9277 | By default, OProfile listens on port 4224. | ||
9278 | <note> | ||
9279 | You can change the port using the <filename>‐‐port</filename> command-line | ||
9280 | option. | ||
9281 | </note> | ||
9282 | </para> | ||
9283 | |||
9284 | <para> | ||
9285 | The client program is called <filename>oprofile-viewer</filename> and its UI is relatively | ||
9286 | straight forward. | ||
9287 | You access key functionality through the buttons on the toolbar, which | ||
9288 | are duplicated in the menus. | ||
9289 | Here are the buttons: | ||
9290 | <itemizedlist> | ||
9291 | <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host. | ||
9292 | You can also supply the IP address or hostname.</para></listitem> | ||
9293 | <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target. | ||
9294 | </para></listitem> | ||
9295 | <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device. | ||
9296 | </para></listitem> | ||
9297 | <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and | ||
9298 | downloads the data to the local host. | ||
9299 | Stopping the profiler generates the profile and displays it in the viewer. | ||
9300 | </para></listitem> | ||
9301 | <listitem><para><emphasis>Download:</emphasis> Downloads the data from the | ||
9302 | target and generates the profile, which appears in the viewer.</para></listitem> | ||
9303 | <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device. | ||
9304 | Resetting the data removes sample information collected from previous | ||
9305 | sampling runs. | ||
9306 | Be sure you reset the data if you do not want to include old sample information. | ||
9307 | </para></listitem> | ||
9308 | <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the | ||
9309 | target to another directory for later examination.</para></listitem> | ||
9310 | <listitem><para><emphasis>Open:</emphasis> Loads previously saved data. | ||
9311 | </para></listitem> | ||
9312 | </itemizedlist> | ||
9313 | </para> | ||
9314 | |||
9315 | <para> | ||
9316 | The client downloads the complete profile archive from | ||
9317 | the target to the host for processing. | ||
9318 | This archive is a directory that contains the sample data, the object files, | ||
9319 | and the debug information for the object files. | ||
9320 | The archive is then converted using the <filename>oparchconv</filename> script, which is | ||
9321 | included in this distribution. | ||
9322 | The script uses <filename>opimport</filename> to convert the archive from | ||
9323 | the target to something that can be processed on the host. | ||
9324 | </para> | ||
9325 | |||
9326 | <para> | ||
9327 | Downloaded archives reside in the | ||
9328 | <link linkend='build-directory'>Build Directory</link> in | ||
9329 | <filename>tmp</filename> and are cleared up when they are no longer in use. | ||
9330 | </para> | ||
9331 | |||
9332 | <para> | ||
9333 | If you wish to perform kernel profiling, you need to be sure | ||
9334 | a <filename>vmlinux</filename> file that matches the running kernel is available. | ||
9335 | In the source directory, that file is usually located in | ||
9336 | <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where | ||
9337 | <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel. | ||
9338 | The OpenEmbedded build system generates separate <filename>vmlinux</filename> | ||
9339 | packages for each kernel it builds. | ||
9340 | Thus, it should just be a question of making sure a matching package is | ||
9341 | installed (e.g. <filename>opkg install kernel-vmlinux</filename>). | ||
9342 | The files are automatically installed into development and profiling images | ||
9343 | alongside OProfile. | ||
9344 | A configuration option exists within the OProfileUI settings page that you can use to | ||
9345 | enter the location of the <filename>vmlinux</filename> file. | ||
9346 | </para> | ||
9347 | |||
9348 | <para> | ||
9349 | Waiting for debug symbols to transfer from the device can be slow, and it | ||
9350 | is not always necessary to actually have them on the device for OProfile use. | ||
9351 | All that is needed is a copy of the filesystem with the debug symbols present | ||
9352 | on the viewer system. | ||
9353 | The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>" | ||
9354 | section covers how to create such a directory within | ||
9355 | the source directory and how to use the OProfileUI Settings | ||
9356 | Dialog to specify the location. | ||
9357 | If you specify the directory, it will be used when the file checksums | ||
9358 | match those on the system you are profiling. | ||
9359 | </para> | ||
9360 | </section> | ||
9361 | |||
9362 | <section id="platdev-oprofile-oprofileui-offline"> | ||
9363 | <title>Offline Mode</title> | ||
9364 | |||
9365 | <para> | ||
9366 | If network access to the target is unavailable, you can generate | ||
9367 | an archive for processing in <filename>oprofile-viewer</filename> as follows: | ||
9368 | <literallayout class='monospaced'> | ||
9369 | # opcontrol ‐‐reset | ||
9370 | # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 | ||
9371 | . | ||
9372 | . | ||
9373 | [do whatever is being profiled] | ||
9374 | . | ||
9375 | . | ||
9376 | # opcontrol ‐‐stop | ||
9377 | # oparchive -o my_archive | ||
9378 | </literallayout> | ||
9379 | </para> | ||
9380 | |||
9381 | <para> | ||
9382 | In the above example, <filename>my_archive</filename> is the name of the | ||
9383 | archive directory where you would like the profile archive to be kept. | ||
9384 | After the directory is created, you can copy it to another host and load it | ||
9385 | using <filename>oprofile-viewer</filename> open functionality. | ||
9386 | If necessary, the archive is converted. | ||
9387 | </para> | ||
9388 | </section> | ||
9389 | </section> | ||
9390 | </section> | ||
9391 | |||
9392 | <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> | ||
9393 | <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> | ||
9394 | |||
9395 | <para> | ||
9396 | One of the concerns for a development organization using open source | ||
9397 | software is how to maintain compliance with various open source | ||
9398 | licensing during the lifecycle of the product. | ||
9399 | While this section does not provide legal advice or | ||
9400 | comprehensively cover all scenarios, it does | ||
9401 | present methods that you can use to | ||
9402 | assist you in meeting the compliance requirements during a software | ||
9403 | release. | ||
9404 | </para> | ||
9405 | |||
9406 | <para> | ||
9407 | With hundreds of different open source licenses that the Yocto | ||
9408 | Project tracks, it is difficult to know the requirements of each | ||
9409 | and every license. | ||
9410 | However, the requirements of the major FLOSS licenses can begin | ||
9411 | to be covered by | ||
9412 | assuming that three main areas of concern exist: | ||
9413 | <itemizedlist> | ||
9414 | <listitem><para>Source code must be provided.</para></listitem> | ||
9415 | <listitem><para>License text for the software must be | ||
9416 | provided.</para></listitem> | ||
9417 | <listitem><para>Compilation scripts and modifications to the | ||
9418 | source code must be provided. | ||
9419 | </para></listitem> | ||
9420 | </itemizedlist> | ||
9421 | There are other requirements beyond the scope of these | ||
9422 | three and the methods described in this section | ||
9423 | (e.g. the mechanism through which source code is distributed). | ||
9424 | </para> | ||
9425 | |||
9426 | <para> | ||
9427 | As different organizations have different methods of complying with | ||
9428 | open source licensing, this section is not meant to imply that | ||
9429 | there is only one single way to meet your compliance obligations, | ||
9430 | but rather to describe one method of achieving compliance. | ||
9431 | The remainder of this section describes methods supported to meet the | ||
9432 | previously mentioned three requirements. | ||
9433 | Once you take steps to meet these requirements, | ||
9434 | and prior to releasing images, sources, and the build system, | ||
9435 | you should audit all artifacts to ensure completeness. | ||
9436 | <note> | ||
9437 | The Yocto Project generates a license manifest during | ||
9438 | image creation that is located | ||
9439 | in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename> | ||
9440 | to assist with any audits. | ||
9441 | </note> | ||
9442 | </para> | ||
9443 | |||
9444 | <section id='providing-the-source-code'> | ||
9445 | <title>Providing the Source Code</title> | ||
9446 | |||
9447 | <para> | ||
9448 | Compliance activities should begin before you generate the | ||
9449 | final image. | ||
9450 | The first thing you should look at is the requirement that | ||
9451 | tops the list for most compliance groups - providing | ||
9452 | the source. | ||
9453 | The Yocto Project has a few ways of meeting this | ||
9454 | requirement. | ||
9455 | </para> | ||
9456 | |||
9457 | <para> | ||
9458 | One of the easiest ways to meet this requirement is | ||
9459 | to provide the entire | ||
9460 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> | ||
9461 | used by the build. | ||
9462 | This method, however, has a few issues. | ||
9463 | The most obvious is the size of the directory since it includes | ||
9464 | all sources used in the build and not just the source used in | ||
9465 | the released image. | ||
9466 | It will include toolchain source, and other artifacts, which | ||
9467 | you would not generally release. | ||
9468 | However, the more serious issue for most companies is accidental | ||
9469 | release of proprietary software. | ||
9470 | The Yocto Project provides an | ||
9471 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink> | ||
9472 | class to help avoid some of these concerns. | ||
9473 | </para> | ||
9474 | |||
9475 | <para> | ||
9476 | Before you employ <filename>DL_DIR</filename> or the | ||
9477 | archiver class, you need to decide how you choose to | ||
9478 | provide source. | ||
9479 | The source archiver class can generate tarballs and SRPMs | ||
9480 | and can create them with various levels of compliance in mind. | ||
9481 | </para> | ||
9482 | |||
9483 | <para> | ||
9484 | One way of doing this (but certainly not the only way) is to | ||
9485 | release just the source as a tarball. | ||
9486 | You can do this by adding the following to the | ||
9487 | <filename>local.conf</filename> file found in the | ||
9488 | <link linkend='build-directory'>Build Directory</link>: | ||
9489 | <literallayout class='monospaced'> | ||
9490 | INHERIT += "archiver" | ||
9491 | ARCHIVER_MODE[src] = "original" | ||
9492 | </literallayout> | ||
9493 | During the creation of your image, the source from all | ||
9494 | recipes that deploy packages to the image is placed within | ||
9495 | subdirectories of | ||
9496 | <filename>DEPLOY_DIR/sources</filename> based on the | ||
9497 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> | ||
9498 | for each recipe. | ||
9499 | Releasing the entire directory enables you to comply with | ||
9500 | requirements concerning providing the unmodified source. | ||
9501 | It is important to note that the size of the directory can | ||
9502 | get large. | ||
9503 | </para> | ||
9504 | |||
9505 | <para> | ||
9506 | A way to help mitigate the size issue is to only release | ||
9507 | tarballs for licenses that require the release of | ||
9508 | source. | ||
9509 | Let us assume you are only concerned with GPL code as | ||
9510 | identified with the following: | ||
9511 | <literallayout class='monospaced'> | ||
9512 | $ cd poky/build/tmp/deploy/sources | ||
9513 | $ mkdir ~/gpl_source_release | ||
9514 | $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done | ||
9515 | </literallayout> | ||
9516 | At this point, you could create a tarball from the | ||
9517 | <filename>gpl_source_release</filename> directory and | ||
9518 | provide that to the end user. | ||
9519 | This method would be a step toward achieving compliance | ||
9520 | with section 3a of GPLv2 and with section 6 of GPLv3. | ||
9521 | </para> | ||
9522 | </section> | ||
9523 | |||
9524 | <section id='providing-license-text'> | ||
9525 | <title>Providing License Text</title> | ||
9526 | |||
9527 | <para> | ||
9528 | One requirement that is often overlooked is inclusion | ||
9529 | of license text. | ||
9530 | This requirement also needs to be dealt with prior to | ||
9531 | generating the final image. | ||
9532 | Some licenses require the license text to accompany | ||
9533 | the binary. | ||
9534 | You can achieve this by adding the following to your | ||
9535 | <filename>local.conf</filename> file: | ||
9536 | <literallayout class='monospaced'> | ||
9537 | COPY_LIC_MANIFEST = "1" | ||
9538 | COPY_LIC_DIRS = "1" | ||
9539 | </literallayout> | ||
9540 | Adding these statements to the configuration file ensures | ||
9541 | that the licenses collected during package generation | ||
9542 | are included on your image. | ||
9543 | As the source archiver has already archived the original | ||
9544 | unmodified source that contains the license files, | ||
9545 | you would have already met the requirements for inclusion | ||
9546 | of the license information with source as defined by the GPL | ||
9547 | and other open source licenses. | ||
9548 | </para> | ||
9549 | </section> | ||
9550 | |||
9551 | <section id='providing-compilation-scripts-and-source-code-modifications'> | ||
9552 | <title>Providing Compilation Scripts and Source Code Modifications</title> | ||
9553 | |||
9554 | <para> | ||
9555 | At this point, we have addressed all we need to address | ||
9556 | prior to generating the image. | ||
9557 | The next two requirements are addressed during the final | ||
9558 | packaging of the release. | ||
9559 | </para> | ||
9560 | |||
9561 | <para> | ||
9562 | By releasing the version of the OpenEmbedded build system | ||
9563 | and the layers used during the build, you will be providing both | ||
9564 | compilation scripts and the source code modifications in one | ||
9565 | step. | ||
9566 | </para> | ||
9567 | |||
9568 | <para> | ||
9569 | If the deployment team has a | ||
9570 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> | ||
9571 | and a distro layer, and those those layers are used to patch, | ||
9572 | compile, package, or modify (in any way) any open source | ||
9573 | software included in your released images, you | ||
9574 | might be required to to release those layers under section 3 of | ||
9575 | GPLv2 or section 1 of GPLv3. | ||
9576 | One way of doing that is with a clean | ||
9577 | checkout of the version of the Yocto Project and layers used | ||
9578 | during your build. | ||
9579 | Here is an example: | ||
9580 | <literallayout class='monospaced'> | ||
9581 | # We built using the &DISTRO_NAME; branch of the poky repo | ||
9582 | $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky | ||
9583 | $ cd poky | ||
9584 | # We built using the release_branch for our layers | ||
9585 | $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer | ||
9586 | $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer | ||
9587 | # clean up the .git repos | ||
9588 | $ find . -name ".git" -type d -exec rm -rf {} \; | ||
9589 | </literallayout> | ||
9590 | One thing a development organization might want to consider | ||
9591 | for end-user convenience is to modify | ||
9592 | <filename>meta-yocto/conf/bblayers.conf.sample</filename> to | ||
9593 | ensure that when the end user utilizes the released build | ||
9594 | system to build an image, the development organization's | ||
9595 | layers are included in the <filename>bblayers.conf</filename> | ||
9596 | file automatically: | ||
9597 | <literallayout class='monospaced'> | ||
9598 | # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf | ||
9599 | # changes incompatibly | ||
9600 | LCONF_VERSION = "6" | ||
9601 | |||
9602 | BBPATH = "${TOPDIR}" | ||
9603 | BBFILES ?= "" | ||
9604 | |||
9605 | BBLAYERS ?= " \ | ||
9606 | ##OEROOT##/meta \ | ||
9607 | ##OEROOT##/meta-yocto \ | ||
9608 | ##OEROOT##/meta-yocto-bsp \ | ||
9609 | ##OEROOT##/meta-mylayer \ | ||
9610 | " | ||
9611 | |||
9612 | BBLAYERS_NON_REMOVABLE ?= " \ | ||
9613 | ##OEROOT##/meta \ | ||
9614 | ##OEROOT##/meta-yocto \ | ||
9615 | " | ||
9616 | </literallayout> | ||
9617 | Creating and providing an archive of the | ||
9618 | <link linkend='metadata'>Metadata</link> layers | ||
9619 | (recipes, configuration files, and so forth) | ||
9620 | enables you to meet your | ||
9621 | requirements to include the scripts to control compilation | ||
9622 | as well as any modifications to the original source. | ||
9623 | </para> | ||
9624 | </section> | ||
9625 | </section> | ||
9626 | |||
9627 | <section id='using-the-error-reporting-tool'> | ||
9628 | <title>Using the Error Reporting Tool</title> | ||
9629 | |||
9630 | <para> | ||
9631 | The error reporting tool allows you to | ||
9632 | submit errors encountered during builds to a central database. | ||
9633 | Outside of the build environment, you can use a web interface to | ||
9634 | browse errors, view statistics, and query for errors. | ||
9635 | The tool works using a client-server system where the client | ||
9636 | portion is integrated with the installed Yocto Project | ||
9637 | <link linkend='source-directory'>Source Directory</link> | ||
9638 | (e.g. <filename>poky</filename>). | ||
9639 | The server receives the information collected and saves it in a | ||
9640 | database. | ||
9641 | </para> | ||
9642 | |||
9643 | <para> | ||
9644 | A live instance of the error reporting server exists at | ||
9645 | <ulink url='http://errors.yoctoproject.org'></ulink>. | ||
9646 | This server exists so that when you want to get help with | ||
9647 | build failures, you can submit all of the information on the | ||
9648 | failure easily and then point to the URL in your bug report | ||
9649 | or send an email to the mailing list. | ||
9650 | <note> | ||
9651 | If you send error reports to this server, the reports become | ||
9652 | publicly visible. | ||
9653 | </note> | ||
9654 | </para> | ||
9655 | |||
9656 | <section id='enabling-and-using-the-tool'> | ||
9657 | <title>Enabling and Using the Tool</title> | ||
9658 | |||
9659 | <para> | ||
9660 | By default, the error reporting tool is disabled. | ||
9661 | You can enable it by inheriting the | ||
9662 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-report-error'><filename>report-error</filename></ulink> | ||
9663 | class by adding the following statement to the end of | ||
9664 | your <filename>local.conf</filename> file in your | ||
9665 | <link linkend='build-directory'>Build Directory</link>. | ||
9666 | <literallayout class='monospaced'> | ||
9667 | INHERIT += "report-error" | ||
9668 | </literallayout> | ||
9669 | </para> | ||
9670 | |||
9671 | <para> | ||
9672 | By default, the error reporting feature stores information in | ||
9673 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LOG_DIR'><filename>LOG_DIR</filename></ulink><filename>}/error-report</filename>. | ||
9674 | However, you can specify a directory to use by adding the following | ||
9675 | to your <filename>local.conf</filename> file: | ||
9676 | <literallayout class='monospaced'> | ||
9677 | ERR_REPORT_DIR = "path" | ||
9678 | </literallayout> | ||
9679 | Enabling error reporting causes the build process to collect | ||
9680 | the errors and store them in a file as previously described. | ||
9681 | When the build system encounters an error, it includes a command | ||
9682 | as part of the console output. | ||
9683 | You can run the command to send the error file to the server. | ||
9684 | For example, the following command sends the errors to an upstream | ||
9685 | server: | ||
9686 | <literallayout class='monospaced'> | ||
9687 | send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server] | ||
9688 | </literallayout> | ||
9689 | In the above example, the <filename>server</filename> parameter is | ||
9690 | optional. | ||
9691 | By default, the errors are sent to a database used by the entire | ||
9692 | community. | ||
9693 | If you specify a particular server, you can send them to a different | ||
9694 | database. | ||
9695 | </para> | ||
9696 | |||
9697 | <para> | ||
9698 | When sending the error file, you receive a link that corresponds | ||
9699 | to your entry in the database. | ||
9700 | For example, here is a typical link: | ||
9701 | <literallayout class='monospaced'> | ||
9702 | http://localhost:8000/Errors/Search/1/158 | ||
9703 | </literallayout> | ||
9704 | Following the link takes you to a web interface where you can | ||
9705 | browse, query the errors, and view statistics. | ||
9706 | </para> | ||
9707 | </section> | ||
9708 | |||
9709 | <section id='disabling-the-tool'> | ||
9710 | <title>Disabling the Tool</title> | ||
9711 | |||
9712 | <para> | ||
9713 | To disable the error reporting feature, simply remove or comment | ||
9714 | out the following statement from the end of your | ||
9715 | <filename>local.conf</filename> file in your | ||
9716 | <link linkend='build-directory'>Build Directory</link>. | ||
9717 | <literallayout class='monospaced'> | ||
9718 | INHERIT += "report-error" | ||
9719 | </literallayout> | ||
9720 | </para> | ||
9721 | </section> | ||
9722 | |||
9723 | <section id='setting-up-your-own-error-reporting-server'> | ||
9724 | <title>Setting Up Your Own Error Reporting Server</title> | ||
9725 | |||
9726 | <para> | ||
9727 | If you want to set up your own error reporting server, you | ||
9728 | can obtain the code from the Git repository at | ||
9729 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/'></ulink>. | ||
9730 | Instructions on how to set it up are in the README document. | ||
9731 | </para> | ||
9732 | </section> | ||
9733 | </section> | ||
9734 | </chapter> | ||
9735 | |||
9736 | <!-- | ||
9737 | vim: expandtab tw=80 ts=4 | ||
9738 | --> | ||
diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl new file mode 100644 index 0000000000..5dd425c810 --- /dev/null +++ b/documentation/dev-manual/dev-manual-customization.xsl | |||
@@ -0,0 +1,19 @@ | |||
1 | <?xml version='1.0'?> | ||
2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> | ||
3 | |||
4 | <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> | ||
5 | |||
6 | <xsl:include href="../template/permalinks.xsl"/> | ||
7 | <xsl:include href="../template/section.title.xsl"/> | ||
8 | <xsl:include href="../template/component.title.xsl"/> | ||
9 | <xsl:include href="../template/division.title.xsl"/> | ||
10 | <xsl:include href="../template/formal.object.heading.xsl"/> | ||
11 | |||
12 | <xsl:param name="html.stylesheet" select="'dev-style.css'" /> | ||
13 | <xsl:param name="chapter.autolabel" select="1" /> | ||
14 | <xsl:param name="appendix.autolabel" select="A" /> | ||
15 | <xsl:param name="section.autolabel" select="1" /> | ||
16 | <xsl:param name="section.label.includes.component.label" select="1" /> | ||
17 | <xsl:param name="generate.id.attributes" select="1" /> | ||
18 | |||
19 | </xsl:stylesheet> | ||
diff --git a/documentation/dev-manual/dev-manual-eclipse-customization.xsl b/documentation/dev-manual/dev-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..8ac4c18f25 --- /dev/null +++ b/documentation/dev-manual/dev-manual-eclipse-customization.xsl | |||
@@ -0,0 +1,27 @@ | |||
1 | <?xml version='1.0'?> | ||
2 | <xsl:stylesheet | ||
3 | xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | ||
4 | xmlns="http://www.w3.org/1999/xhtml" | ||
5 | xmlns:fo="http://www.w3.org/1999/XSL/Format" | ||
6 | version="1.0"> | ||
7 | |||
8 | <xsl:import | ||
9 | href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> | ||
10 | |||
11 | <xsl:param name="chunker.output.indent" select="'yes'"/> | ||
12 | <xsl:param name="chunk.quietly" select="1"/> | ||
13 | <xsl:param name="chunk.first.sections" select="1"/> | ||
14 | <xsl:param name="chunk.section.depth" select="10"/> | ||
15 | <xsl:param name="use.id.as.filename" select="1"/> | ||
16 | <xsl:param name="ulink.target" select="'_self'" /> | ||
17 | <xsl:param name="base.dir" select="'html/dev-manual/'"/> | ||
18 | <xsl:param name="html.stylesheet" select="'../book.css'"/> | ||
19 | <xsl:param name="eclipse.manifest" select="0"/> | ||
20 | <xsl:param name="create.plugin.xml" select="0"/> | ||
21 | <xsl:param name="suppress.navigation" select="1"/> | ||
22 | <xsl:param name="generate.index" select="0"/> | ||
23 | <xsl:param name="chapter.autolabel" select="1" /> | ||
24 | <xsl:param name="appendix.autolabel" select="1" /> | ||
25 | <xsl:param name="section.autolabel" select="1" /> | ||
26 | <xsl:param name="section.label.includes.component.label" select="1" /> | ||
27 | </xsl:stylesheet> | ||
diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml new file mode 100644 index 0000000000..21fba29670 --- /dev/null +++ b/documentation/dev-manual/dev-manual-intro.xml | |||
@@ -0,0 +1,240 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='dev-manual-intro'> | ||
6 | |||
7 | <title>The Yocto Project Development Manual</title> | ||
8 | <section id='intro'> | ||
9 | <title>Introduction</title> | ||
10 | |||
11 | <para> | ||
12 | Welcome to the Yocto Project Development Manual! | ||
13 | This manual provides information on how to use the Yocto Project to | ||
14 | develop embedded Linux images and user-space applications that | ||
15 | run on targeted devices. | ||
16 | The manual provides an overview of image, kernel, and | ||
17 | user-space application development using the Yocto Project. | ||
18 | Because much of the information in this manual is general, it | ||
19 | contains many references to other sources where you can find more | ||
20 | detail. | ||
21 | For example, you can find detailed information on Git, repositories, | ||
22 | and open source in general in many places on the Internet. | ||
23 | Another example specific to the Yocto Project is how to quickly | ||
24 | set up your host development system and build an image, which you | ||
25 | find in the | ||
26 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. | ||
27 | </para> | ||
28 | |||
29 | <para> | ||
30 | The Yocto Project Development Manual does, however, provide | ||
31 | guidance and examples on how to change the kernel source code, | ||
32 | reconfigure the kernel, and develop an application using the | ||
33 | popular <trademark class='trade'>Eclipse</trademark> IDE. | ||
34 | </para> | ||
35 | |||
36 | <note> | ||
37 | By default, using the Yocto Project creates a Poky distribution. | ||
38 | However, you can create your own distribution by providing key | ||
39 | <link linkend='metadata'>Metadata</link>. | ||
40 | A good example is Angstrom, which has had a distribution | ||
41 | based on the Yocto Project since its inception. | ||
42 | Other examples include commercial distributions like | ||
43 | <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>, | ||
44 | <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>, | ||
45 | <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink> | ||
46 | and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>. | ||
47 | See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" | ||
48 | section for more information. | ||
49 | </note> | ||
50 | </section> | ||
51 | |||
52 | <section id='what-this-manual-provides'> | ||
53 | <title>What This Manual Provides</title> | ||
54 | |||
55 | <para> | ||
56 | The following list describes what you can get from this manual: | ||
57 | <itemizedlist> | ||
58 | <listitem><para>Information that lets you get set | ||
59 | up to develop using the Yocto Project.</para></listitem> | ||
60 | <listitem><para>Information to help developers who are new to | ||
61 | the open source environment and to the distributed revision | ||
62 | control system Git, which the Yocto Project uses. | ||
63 | </para></listitem> | ||
64 | <listitem><para>An understanding of common end-to-end | ||
65 | development models and tasks.</para></listitem> | ||
66 | <listitem><para>Information about common development tasks | ||
67 | generally used during image development for | ||
68 | embedded devices. | ||
69 | </para></listitem> | ||
70 | <listitem><para>Information on using the Yocto Project | ||
71 | integration of the QuickEMUlator (QEMU), which lets you | ||
72 | simulate running on hardware an image you have built using | ||
73 | the OpenEmbedded build system. | ||
74 | </para></listitem> | ||
75 | <listitem><para>Many references to other sources of related | ||
76 | information.</para></listitem> | ||
77 | </itemizedlist> | ||
78 | </para> | ||
79 | </section> | ||
80 | |||
81 | <section id='what-this-manual-does-not-provide'> | ||
82 | <title>What this Manual Does Not Provide</title> | ||
83 | |||
84 | <para> | ||
85 | This manual will not give you the following: | ||
86 | <itemizedlist> | ||
87 | <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto | ||
88 | Project documentation:</emphasis> | ||
89 | For example, the Yocto Project Application Developer's Guide contains detailed | ||
90 | instructions on how to run the | ||
91 | <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>ADT Installer</ulink>, | ||
92 | which is used to set up a cross-development environment.</para></listitem> | ||
93 | <listitem><para><emphasis>Reference material:</emphasis> | ||
94 | This type of material resides in an appropriate reference manual. | ||
95 | For example, system variables are documented in the | ||
96 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem> | ||
97 | <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis> | ||
98 | For example, exhaustive information on how to use Git is covered better through the | ||
99 | Internet than in this manual.</para></listitem> | ||
100 | </itemizedlist> | ||
101 | </para> | ||
102 | </section> | ||
103 | |||
104 | <section id='other-information'> | ||
105 | <title>Other Information</title> | ||
106 | |||
107 | <para> | ||
108 | Because this manual presents overview information for many different | ||
109 | topics, supplemental information is recommended for full | ||
110 | comprehension. | ||
111 | The following list presents other sources of information you might find helpful: | ||
112 | <itemizedlist> | ||
113 | <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: | ||
114 | </emphasis> The home page for the Yocto Project provides lots of information on the project | ||
115 | as well as links to software and documentation. | ||
116 | </para></listitem> | ||
117 | <listitem><para><emphasis> | ||
118 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> | ||
119 | This short document lets you get started | ||
120 | with the Yocto Project and quickly begin building an image. | ||
121 | </para></listitem> | ||
122 | <listitem><para><emphasis> | ||
123 | <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> | ||
124 | This manual is a reference | ||
125 | guide to the OpenEmbedded build system, which is based on BitBake. | ||
126 | The build system is sometimes referred to as "Poky". | ||
127 | </para></listitem> | ||
128 | <listitem><para><emphasis> | ||
129 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> | ||
130 | This guide provides information that lets you get going with the Application | ||
131 | Development Toolkit (ADT) and stand-alone cross-development toolchains to | ||
132 | develop projects using the Yocto Project. | ||
133 | </para></listitem> | ||
134 | <listitem><para><emphasis> | ||
135 | <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> | ||
136 | This guide defines the structure for BSP components. | ||
137 | Having a commonly understood structure encourages standardization. | ||
138 | </para></listitem> | ||
139 | <listitem><para><emphasis> | ||
140 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:</emphasis> | ||
141 | This manual describes how to work with Linux Yocto kernels as well as provides a bit | ||
142 | of conceptual information on the construction of the Yocto Linux kernel tree. | ||
143 | </para></listitem> | ||
144 | <listitem><para><emphasis> | ||
145 | <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:</emphasis> | ||
146 | This manual presents a set of common and generally useful tracing and | ||
147 | profiling schemes along with their applications (as appropriate) to each tool. | ||
148 | </para></listitem> | ||
149 | <listitem><para><emphasis> | ||
150 | <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> | ||
151 | Eclipse IDE Yocto Plug-in</ulink>:</emphasis> | ||
152 | A step-by-step instructional video that | ||
153 | demonstrates how an application developer uses Yocto Plug-in features within | ||
154 | the Eclipse IDE. | ||
155 | </para></listitem> | ||
156 | <listitem><para><emphasis> | ||
157 | <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> | ||
158 | A list of commonly asked questions and their answers. | ||
159 | </para></listitem> | ||
160 | <listitem><para><emphasis> | ||
161 | <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:</emphasis> | ||
162 | Features, updates and known issues for the current | ||
163 | release of the Yocto Project. | ||
164 | </para></listitem> | ||
165 | <listitem><para><emphasis> | ||
166 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>:</emphasis> | ||
167 | A graphical user interface for BitBake. | ||
168 | Hob's primary goal is to enable a user to perform common tasks more easily. | ||
169 | </para></listitem> | ||
170 | <listitem><para><emphasis> | ||
171 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/toaster'>Toaster</ulink>:</emphasis> | ||
172 | An Application Programming Interface (API) and web-based | ||
173 | interface to the OpenEmbedded build system, which uses | ||
174 | BitBake, that reports build information. | ||
175 | </para></listitem> | ||
176 | <listitem><para><emphasis> | ||
177 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/build-appliance'>Build Appliance</ulink>:</emphasis> | ||
178 | A virtual machine that | ||
179 | enables you to build and boot a custom embedded Linux image | ||
180 | with the Yocto Project using a non-Linux development system. | ||
181 | </para></listitem> | ||
182 | <listitem><para><emphasis> | ||
183 | <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis> | ||
184 | The bug tracking application the Yocto Project uses. | ||
185 | If you find problems with the Yocto Project, you should report them using this | ||
186 | application. | ||
187 | </para></listitem> | ||
188 | <listitem><para><emphasis>Yocto Project Mailing Lists:</emphasis> | ||
189 | To subscribe to the Yocto Project mailing | ||
190 | lists, click on the following URLs and follow the instructions: | ||
191 | <itemizedlist> | ||
192 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> | ||
193 | for a Yocto Project Discussions mailing list. | ||
194 | </para></listitem> | ||
195 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> | ||
196 | for a Yocto Project Discussions mailing list about the | ||
197 | OpenEmbedded build system (Poky). | ||
198 | </para></listitem> | ||
199 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> | ||
200 | for a mailing list to receive official Yocto Project announcements | ||
201 | as well as Yocto Project milestones. | ||
202 | </para></listitem> | ||
203 | <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> | ||
204 | for a listing of all public mailing lists on | ||
205 | <filename>lists.yoctoproject.org</filename>. | ||
206 | </para></listitem> | ||
207 | </itemizedlist></para></listitem> | ||
208 | <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> | ||
209 | Two IRC channels on freenode are available | ||
210 | for Yocto Project and Poky discussions: <filename>#yocto</filename> and | ||
211 | <filename>#poky</filename>, respectively. | ||
212 | </para></listitem> | ||
213 | <listitem><para><emphasis> | ||
214 | <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> | ||
215 | The build system used by the Yocto Project. | ||
216 | This project is the upstream, generic, embedded distribution | ||
217 | from which the Yocto Project derives its build system (Poky) | ||
218 | and to which it contributes. | ||
219 | </para></listitem> | ||
220 | <listitem><para><emphasis> | ||
221 | <ulink url='http://www.openembedded.org/wiki/BitBake'>BitBake</ulink>:</emphasis> | ||
222 | The tool used by the OpenEmbedded build system | ||
223 | to process project metadata. | ||
224 | </para></listitem> | ||
225 | <listitem><para><emphasis> | ||
226 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual:</ulink></emphasis> | ||
227 | A comprehensive guide to the BitBake tool. | ||
228 | If you want information on BitBake, see this manual. | ||
229 | </para></listitem> | ||
230 | <listitem><para><emphasis> | ||
231 | <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:</emphasis> | ||
232 | An open-source machine emulator and virtualizer. | ||
233 | </para></listitem> | ||
234 | </itemizedlist> | ||
235 | </para> | ||
236 | </section> | ||
237 | </chapter> | ||
238 | <!-- | ||
239 | vim: expandtab tw=80 ts=4 | ||
240 | --> | ||
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml new file mode 100644 index 0000000000..43c31b8405 --- /dev/null +++ b/documentation/dev-manual/dev-manual-model.xml | |||
@@ -0,0 +1,2112 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='dev-manual-model'> | ||
6 | |||
7 | <title>Common Development Models</title> | ||
8 | |||
9 | <para> | ||
10 | Many development models exist for which you can use the Yocto Project. | ||
11 | This chapter overviews simple methods that use tools provided by the | ||
12 | Yocto Project: | ||
13 | <itemizedlist> | ||
14 | <listitem><para><emphasis>System Development:</emphasis> | ||
15 | System Development covers Board Support Package (BSP) development and kernel | ||
16 | modification or configuration. | ||
17 | For an example on how to create a BSP, see the | ||
18 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | ||
19 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | ||
20 | For more complete information on how to work with the kernel, see the | ||
21 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. | ||
22 | </para></listitem> | ||
23 | <listitem><para><emphasis>User Application Development:</emphasis> | ||
24 | User Application Development covers development of applications that you intend | ||
25 | to run on target hardware. | ||
26 | For information on how to set up your host development system for user-space | ||
27 | application development, see the | ||
28 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. | ||
29 | For a simple example of user-space application development using the | ||
30 | <trademark class='trade'>Eclipse</trademark> IDE, see the | ||
31 | "<link linkend='application-development-workflow'>Application | ||
32 | Development Workflow</link>" section. | ||
33 | </para></listitem> | ||
34 | <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> | ||
35 | Direct modification of temporary source code is a convenient development model | ||
36 | to quickly iterate and develop towards a solution. | ||
37 | Once you implement the solution, you should of course take steps to | ||
38 | get the changes upstream and applied in the affected recipes.</para></listitem> | ||
39 | <listitem><para><emphasis>Image Development using Hob:</emphasis> | ||
40 | You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build | ||
41 | custom operating system images within the build environment. | ||
42 | Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem> | ||
43 | <listitem><para><emphasis>Using a Development Shell:</emphasis> | ||
44 | You can use a <filename>devshell</filename> to efficiently debug commands or simply | ||
45 | edit packages. | ||
46 | Working inside a development shell is a quick way to set up the OpenEmbedded build | ||
47 | environment to work on parts of a project.</para></listitem> | ||
48 | </itemizedlist> | ||
49 | </para> | ||
50 | |||
51 | <section id='system-development-model'> | ||
52 | <title>System Development Workflow</title> | ||
53 | |||
54 | <para> | ||
55 | System development involves modification or creation of an image that you want to run on | ||
56 | a specific hardware target. | ||
57 | Usually, when you want to create an image that runs on embedded hardware, the image does | ||
58 | not require the same number of features that a full-fledged Linux distribution provides. | ||
59 | Thus, you can create a much smaller image that is designed to use only the | ||
60 | features for your particular hardware. | ||
61 | </para> | ||
62 | |||
63 | <para> | ||
64 | To help you understand how system development works in the Yocto Project, this section | ||
65 | covers two types of image development: BSP creation and kernel modification or | ||
66 | configuration. | ||
67 | </para> | ||
68 | |||
69 | <section id='developing-a-board-support-package-bsp'> | ||
70 | <title>Developing a Board Support Package (BSP)</title> | ||
71 | |||
72 | <para> | ||
73 | A BSP is a collection of recipes that, when applied during a build, results in | ||
74 | an image that you can run on a particular board. | ||
75 | Thus, the package when compiled into the new image, supports the operation of the board. | ||
76 | </para> | ||
77 | |||
78 | <note> | ||
79 | For a brief list of terms used when describing the development process in the Yocto Project, | ||
80 | see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section. | ||
81 | </note> | ||
82 | |||
83 | <para> | ||
84 | The remainder of this section presents the basic | ||
85 | steps used to create a BSP using the Yocto Project's | ||
86 | <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>. | ||
87 | Although not required for BSP creation, the | ||
88 | <filename>meta-intel</filename> repository, which contains | ||
89 | many BSPs supported by the Yocto Project, is part of the example. | ||
90 | </para> | ||
91 | |||
92 | <para> | ||
93 | For an example that shows how to create a new layer using the tools, see the | ||
94 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | ||
95 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | ||
96 | </para> | ||
97 | |||
98 | <para> | ||
99 | The following illustration and list summarize the BSP creation general workflow. | ||
100 | </para> | ||
101 | |||
102 | <para> | ||
103 | <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" /> | ||
104 | </para> | ||
105 | |||
106 | <para> | ||
107 | <orderedlist> | ||
108 | <listitem><para><emphasis>Set up your host development system to support | ||
109 | development using the Yocto Project</emphasis>: See the | ||
110 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" | ||
111 | and the | ||
112 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | ||
113 | in the Yocto Project Quick Start for requirements.</para></listitem> | ||
114 | <listitem><para><emphasis>Establish a local copy of the project files on your | ||
115 | system</emphasis>: You need this <link linkend='source-directory'>Source | ||
116 | Directory</link> available on your host system. | ||
117 | Having these files on your system gives you access to the build | ||
118 | process and to the tools you need. | ||
119 | For information on how to set up the Source Directory, | ||
120 | see the | ||
121 | "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> | ||
122 | <listitem><para><emphasis>Establish the <filename>meta-intel</filename> | ||
123 | repository on your system</emphasis>: Having local copies | ||
124 | of these supported BSP layers on your system gives you | ||
125 | access to layers you might be able to build on or modify | ||
126 | to create your BSP. | ||
127 | For information on how to get these files, see the | ||
128 | "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> | ||
129 | <listitem><para><emphasis>Create your own BSP layer using the | ||
130 | <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: | ||
131 | Layers are ideal for | ||
132 | isolating and storing work for a given piece of hardware. | ||
133 | A layer is really just a location or area in which you place | ||
134 | the recipes and configurations for your BSP. | ||
135 | In fact, a BSP is, in itself, a special type of layer. | ||
136 | The simplest way to create a new BSP layer that is compliant with the | ||
137 | Yocto Project is to use the <filename>yocto-bsp</filename> script. | ||
138 | For information about that script, see the | ||
139 | "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" | ||
140 | section in the Yocto Project Board Support (BSP) Developer's Guide. | ||
141 | </para> | ||
142 | <para> | ||
143 | Another example that illustrates a layer is an application. | ||
144 | Suppose you are creating an application that has library or other dependencies in | ||
145 | order for it to compile and run. | ||
146 | The layer, in this case, would be where all the recipes that define those dependencies | ||
147 | are kept. | ||
148 | The key point for a layer is that it is an isolated area that contains | ||
149 | all the relevant information for the project that the OpenEmbedded build | ||
150 | system knows about. | ||
151 | For more information on layers, see the | ||
152 | "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" | ||
153 | section. | ||
154 | For more information on BSP layers, see the | ||
155 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the | ||
156 | Yocto Project Board Support Package (BSP) Developer's Guide.</para> | ||
157 | <note>Five BSPs exist that are part of the | ||
158 | Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>, | ||
159 | <filename>beaglebone</filename> (ARM), | ||
160 | <filename>mpc8315e</filename> (PowerPC), | ||
161 | and <filename>edgerouter</filename> (MIPS). | ||
162 | The recipes and configurations for these five BSPs are located and dispersed | ||
163 | within the <link linkend='source-directory'>Source Directory</link>. | ||
164 | On the other hand, the <filename>meta-intel</filename> layer | ||
165 | contains BSP layers for many supported BSPs (e.g. | ||
166 | Crystal Forest, Emenlow, Fish River Island 2, Haswell, | ||
167 | Jasper Forest, and so forth). | ||
168 | Aside from the BSPs in the <filename>meta-intel</filename> | ||
169 | layer, the | ||
170 | <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> | ||
171 | contain additional BSP layers such as | ||
172 | <filename>meta-minnow</filename> and | ||
173 | <filename>meta-raspberrypi</filename>.</note> | ||
174 | <para>When you set up a layer for a new BSP, you should follow a standard layout. | ||
175 | This layout is described in the | ||
176 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" | ||
177 | section of the Board Support Package (BSP) Development Guide. | ||
178 | In the standard layout, you will notice a suggested structure for recipes and | ||
179 | configuration information. | ||
180 | You can see the standard layout for a BSP by examining | ||
181 | any supported BSP found in the <filename>meta-intel</filename> layer inside | ||
182 | the Source Directory.</para></listitem> | ||
183 | <listitem><para><emphasis>Make configuration changes to your new BSP | ||
184 | layer</emphasis>: The standard BSP layer structure organizes the files you need | ||
185 | to edit in <filename>conf</filename> and several <filename>recipes-*</filename> | ||
186 | directories within the BSP layer. | ||
187 | Configuration changes identify where your new layer is on the local system | ||
188 | and identify which kernel you are going to use. | ||
189 | When you run the <filename>yocto-bsp</filename> script, you are able to interactively | ||
190 | configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). | ||
191 | </para></listitem> | ||
192 | <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe | ||
193 | changes include altering recipes (<filename>.bb</filename> files), removing | ||
194 | recipes you do not use, and adding new recipes or append files | ||
195 | (<filename>.bbappend</filename>) that you need to support your hardware. | ||
196 | </para></listitem> | ||
197 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | ||
198 | changes to your BSP layer, there remains a few things | ||
199 | you need to do for the OpenEmbedded build system in order for it to create your image. | ||
200 | You need to get the build environment ready by sourcing an environment setup script | ||
201 | (i.e. <filename>oe-init-build-env</filename> or | ||
202 | <filename>oe-init-build-env-memres</filename>) | ||
203 | and you need to be sure two key configuration files are configured appropriately: | ||
204 | the <filename>conf/local.conf</filename> and the | ||
205 | <filename>conf/bblayers.conf</filename> file. | ||
206 | You must make the OpenEmbedded build system aware of your new layer. | ||
207 | See the | ||
208 | "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section | ||
209 | for information on how to let the build system know about your new layer.</para> | ||
210 | <para>The entire process for building an image is overviewed in the section | ||
211 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section | ||
212 | of the Yocto Project Quick Start. | ||
213 | You might want to reference this information.</para></listitem> | ||
214 | <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system | ||
215 | uses the BitBake tool to build images based on the type of image you want to create. | ||
216 | You can find more information about BitBake in the | ||
217 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
218 | </para> | ||
219 | <para>The build process supports several types of images to satisfy different needs. | ||
220 | See the | ||
221 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter | ||
222 | in the Yocto Project Reference Manual for information on | ||
223 | supported images.</para></listitem> | ||
224 | </orderedlist> | ||
225 | </para> | ||
226 | |||
227 | <para> | ||
228 | You can view a video presentation on "Building Custom Embedded Images with Yocto" | ||
229 | at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. | ||
230 | After going to the page, just search for "Embedded". | ||
231 | You can also find supplemental information in the | ||
232 | <ulink url='&YOCTO_DOCS_BSP_URL;'> | ||
233 | Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. | ||
234 | Finally, there is a wiki page write up of the example also located | ||
235 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> | ||
236 | here</ulink> that you might find helpful. | ||
237 | </para> | ||
238 | </section> | ||
239 | |||
240 | <section id='modifying-the-kernel'> | ||
241 | <title><anchor id='kernel-spot' />Modifying the Kernel</title> | ||
242 | |||
243 | <para> | ||
244 | Kernel modification involves changing the Yocto Project kernel, which could involve changing | ||
245 | configuration options as well as adding new kernel recipes. | ||
246 | Configuration changes can be added in the form of configuration fragments, while recipe | ||
247 | modification comes through the kernel's <filename>recipes-kernel</filename> area | ||
248 | in a kernel layer you create. | ||
249 | </para> | ||
250 | |||
251 | <para> | ||
252 | The remainder of this section presents a high-level overview of the Yocto Project | ||
253 | kernel architecture and the steps to modify the kernel. | ||
254 | You can reference the | ||
255 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section | ||
256 | for an example that changes the source code of the kernel. | ||
257 | For information on how to configure the kernel, see the | ||
258 | "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. | ||
259 | For more information on the kernel and on modifying the kernel, see the | ||
260 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. | ||
261 | </para> | ||
262 | |||
263 | <section id='kernel-overview'> | ||
264 | <title>Kernel Overview</title> | ||
265 | |||
266 | <para> | ||
267 | Traditionally, when one thinks of a patched kernel, they think of a base kernel | ||
268 | source tree and a fixed structure that contains kernel patches. | ||
269 | The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source | ||
270 | generator. | ||
271 | By the end of this section, this analogy will become clearer. | ||
272 | </para> | ||
273 | |||
274 | <para> | ||
275 | You can find a web interface to the Yocto Project kernel source repositories at | ||
276 | <ulink url='&YOCTO_GIT_URL;'></ulink>. | ||
277 | If you look at the interface, you will see to the left a grouping of | ||
278 | Git repositories titled "Yocto Linux Kernel." | ||
279 | Within this group, you will find several kernels supported by | ||
280 | the Yocto Project: | ||
281 | <itemizedlist> | ||
282 | <listitem><para><emphasis> | ||
283 | <filename>linux-yocto-3.8</filename></emphasis> - The | ||
284 | stable Yocto Project kernel to use with the Yocto | ||
285 | Project Release 1.4. This kernel is based on the | ||
286 | Linux 3.8 released kernel. | ||
287 | </para></listitem> | ||
288 | <listitem><para><emphasis> | ||
289 | <filename>linux-yocto-3.10</filename></emphasis> - The | ||
290 | stable Yocto Project kernel to use with the Yocto | ||
291 | Project Release 1.5. | ||
292 | This kernel is based on the Linux 3.10 released kernel. | ||
293 | </para></listitem> | ||
294 | <listitem><para><emphasis> | ||
295 | <filename>linux-yocto-3.14</filename></emphasis> - The | ||
296 | stable Yocto Project kernel to use with the Yocto | ||
297 | Project Releases 1.6 and 1.7. | ||
298 | This kernel is based on the Linux 3.14 released kernel. | ||
299 | </para></listitem> | ||
300 | <listitem><para><emphasis> | ||
301 | <filename>linux-yocto-3.17</filename></emphasis> - An | ||
302 | additional Yocto Project kernel used with the Yocto | ||
303 | Project Release 1.7. | ||
304 | This kernel is based on the Linux 3.17 released kernel. | ||
305 | </para></listitem> | ||
306 | <listitem><para><emphasis> | ||
307 | <filename>linux-yocto-dev</filename></emphasis> - A | ||
308 | development kernel based on the latest upstream release | ||
309 | candidate available. | ||
310 | </para></listitem> | ||
311 | </itemizedlist> | ||
312 | </para> | ||
313 | |||
314 | <para> | ||
315 | The kernels are maintained using the Git revision control system | ||
316 | that structures them using the familiar "tree", "branch", and "leaf" scheme. | ||
317 | Branches represent diversions from general code to more specific code, while leaves | ||
318 | represent the end-points for a complete and unique kernel whose source files, | ||
319 | when gathered from the root of the tree to the leaf, accumulate to create the files | ||
320 | necessary for a specific piece of hardware and its features. | ||
321 | The following figure displays this concept: | ||
322 | <para> | ||
323 | <imagedata fileref="figures/kernel-overview-1.png" | ||
324 | width="6in" depth="6in" align="center" scale="100" /> | ||
325 | </para> | ||
326 | |||
327 | <para> | ||
328 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree | ||
329 | where a supported base kernel is modified from the Linux kernel. | ||
330 | For example, this could be the branch point for the <filename>linux-yocto-3.4</filename> | ||
331 | kernel. | ||
332 | Thus, everything further to the right in the structure is based on the | ||
333 | <filename>linux-yocto-3.4</filename> kernel. | ||
334 | Branch points to the right in the figure represent where the | ||
335 | <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware | ||
336 | or types of kernels, such as real-time kernels. | ||
337 | Each leaf thus represents the end-point for a kernel designed to run on a specific | ||
338 | targeted device. | ||
339 | </para> | ||
340 | |||
341 | <para> | ||
342 | The overall result is a Git-maintained repository from which all the supported | ||
343 | kernel types can be derived for all the supported devices. | ||
344 | A big advantage to this scheme is the sharing of common features by keeping them in | ||
345 | "larger" branches within the tree. | ||
346 | This practice eliminates redundant storage of similar features shared among kernels. | ||
347 | </para> | ||
348 | |||
349 | <note> | ||
350 | Keep in mind the figure does not take into account all the supported Yocto | ||
351 | Project kernel types, but rather shows a single generic kernel just for conceptual purposes. | ||
352 | Also keep in mind that this structure represents the Yocto Project source repositories | ||
353 | that are either pulled from during the build or established on the host development system | ||
354 | prior to the build by either cloning a particular kernel's Git repository or by | ||
355 | downloading and unpacking a tarball. | ||
356 | </note> | ||
357 | |||
358 | <para> | ||
359 | Upstream storage of all the available kernel source code is one thing, while | ||
360 | representing and using the code on your host development system is another. | ||
361 | Conceptually, you can think of the kernel source repositories as all the | ||
362 | source files necessary for all the supported kernels. | ||
363 | As a developer, you are just interested in the source files for the kernel on | ||
364 | which you are working. | ||
365 | And, furthermore, you need them available on your host system. | ||
366 | </para> | ||
367 | |||
368 | <para> | ||
369 | Kernel source code is available on your host system a couple of different | ||
370 | ways. | ||
371 | If you are working in the kernel all the time, you probably would want | ||
372 | to set up your own local Git repository of the kernel tree. | ||
373 | If you just need to make some patches to the kernel, you can access | ||
374 | temporary kernel source files that were extracted and used | ||
375 | during a build. | ||
376 | We will just talk about working with the temporary source code. | ||
377 | For more information on how to get kernel source code onto your | ||
378 | host system, see the | ||
379 | "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" | ||
380 | bulleted item earlier in the manual. | ||
381 | </para> | ||
382 | |||
383 | <para> | ||
384 | What happens during the build? | ||
385 | When you build the kernel on your development system, all files needed for the build | ||
386 | are taken from the source repositories pointed to by the | ||
387 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable | ||
388 | and gathered in a temporary work area | ||
389 | where they are subsequently used to create the unique kernel. | ||
390 | Thus, in a sense, the process constructs a local source tree specific to your | ||
391 | kernel to generate the new kernel image - a source generator if you will. | ||
392 | </para> | ||
393 | The following figure shows the temporary file structure | ||
394 | created on your host system when the build occurs. | ||
395 | This | ||
396 | <link linkend='build-directory'>Build Directory</link> contains all the | ||
397 | source files used during the build. | ||
398 | </para> | ||
399 | |||
400 | <para> | ||
401 | <imagedata fileref="figures/kernel-overview-2-generic.png" | ||
402 | width="6in" depth="5in" align="center" scale="100" /> | ||
403 | </para> | ||
404 | |||
405 | <para> | ||
406 | Again, for additional information on the Yocto Project kernel's | ||
407 | architecture and its branching strategy, see the | ||
408 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. | ||
409 | You can also reference the | ||
410 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" | ||
411 | section for a detailed example that modifies the kernel. | ||
412 | </para> | ||
413 | </section> | ||
414 | |||
415 | <section id='kernel-modification-workflow'> | ||
416 | <title>Kernel Modification Workflow</title> | ||
417 | |||
418 | <para> | ||
419 | This illustration and the following list summarizes the kernel modification general workflow. | ||
420 | </para> | ||
421 | |||
422 | <para> | ||
423 | <imagedata fileref="figures/kernel-dev-flow.png" | ||
424 | width="6in" depth="5in" align="center" scalefit="1" /> | ||
425 | </para> | ||
426 | |||
427 | <para> | ||
428 | <orderedlist> | ||
429 | <listitem><para><emphasis>Set up your host development system to support | ||
430 | development using the Yocto Project</emphasis>: See | ||
431 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and | ||
432 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | ||
433 | in the Yocto Project Quick Start for requirements.</para></listitem> | ||
434 | <listitem><para><emphasis>Establish a local copy of project files on your | ||
435 | system</emphasis>: Having the <link linkend='source-directory'>Source | ||
436 | Directory</link> on your system gives you access to the build process and tools | ||
437 | you need. | ||
438 | For information on how to get these files, see the bulleted item | ||
439 | "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. | ||
440 | </para></listitem> | ||
441 | <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: | ||
442 | Temporary kernel source files are kept in the | ||
443 | <link linkend='build-directory'>Build Directory</link> | ||
444 | created by the | ||
445 | OpenEmbedded build system when you run BitBake. | ||
446 | If you have never built the kernel in which you are | ||
447 | interested, you need to run an initial build to | ||
448 | establish local kernel source files.</para> | ||
449 | <para>If you are building an image for the first time, you need to get the build | ||
450 | environment ready by sourcing an environment setup script | ||
451 | (i.e. <filename>oe-init-build-env</filename> or | ||
452 | <filename>oe-init-build-env-memres</filename>). | ||
453 | You also need to be sure two key configuration files | ||
454 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) | ||
455 | are configured appropriately.</para> | ||
456 | <para>The entire process for building an image is overviewed in the | ||
457 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
458 | section of the Yocto Project Quick Start. | ||
459 | You might want to reference this information. | ||
460 | You can find more information on BitBake in the | ||
461 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
462 | </para> | ||
463 | <para>The build process supports several types of images to satisfy different needs. | ||
464 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in | ||
465 | the Yocto Project Reference Manual for information on supported images. | ||
466 | </para></listitem> | ||
467 | <listitem><para><emphasis>Make changes to the kernel source code if | ||
468 | applicable</emphasis>: Modifying the kernel does not always mean directly | ||
469 | changing source files. | ||
470 | However, if you have to do this, you make the changes to the files in the | ||
471 | Build Directory.</para></listitem> | ||
472 | <listitem><para><emphasis>Make kernel configuration changes | ||
473 | if applicable</emphasis>: | ||
474 | If your situation calls for changing the kernel's configuration, you can | ||
475 | use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename> | ||
476 | to enable and disable kernel configurations. | ||
477 | Using the script lets you interactively set up kernel configurations. | ||
478 | Using <filename>menuconfig</filename> allows you to interactively develop and test the | ||
479 | configuration changes you are making to the kernel. | ||
480 | When saved, changes using <filename>menuconfig</filename> update the kernel's | ||
481 | <filename>.config</filename> file. | ||
482 | Try to resist the temptation of directly editing the <filename>.config</filename> | ||
483 | file found in the Build Directory at | ||
484 | <filename>tmp/sysroots/<machine-name>/kernel</filename>. | ||
485 | Doing so, can produce unexpected results when the OpenEmbedded build system | ||
486 | regenerates the configuration file.</para> | ||
487 | <para>Once you are satisfied with the configuration changes made using | ||
488 | <filename>menuconfig</filename>, you can directly compare the | ||
489 | <filename>.config</filename> file against a saved original and gather those | ||
490 | changes into a config fragment to be referenced from within the kernel's | ||
491 | <filename>.bbappend</filename> file.</para></listitem> | ||
492 | <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: | ||
493 | Rebuilding the kernel image applies your changes.</para></listitem> | ||
494 | </orderedlist> | ||
495 | </para> | ||
496 | </section> | ||
497 | </section> | ||
498 | </section> | ||
499 | |||
500 | <section id='application-development-workflow'> | ||
501 | <title>Application Development Workflow</title> | ||
502 | |||
503 | <para> | ||
504 | Application development involves creating an application that you want | ||
505 | to run on your target hardware, which is running a kernel image created using the | ||
506 | OpenEmbedded build system. | ||
507 | The Yocto Project provides an | ||
508 | <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink> | ||
509 | and stand-alone | ||
510 | <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink> | ||
511 | that facilitate quick development and integration of your application into its runtime environment. | ||
512 | Using the ADT and toolchains, you can compile and link your application. | ||
513 | You can then deploy your application to the actual hardware or to the QEMU emulator for testing. | ||
514 | If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE, | ||
515 | you can use an Eclipse Yocto Plug-in to | ||
516 | allow you to develop, deploy, and test your application all from within Eclipse. | ||
517 | </para> | ||
518 | |||
519 | <para> | ||
520 | While we strongly suggest using the ADT to develop your application, this option might not | ||
521 | be best for you. | ||
522 | If this is the case, you can still use pieces of the Yocto Project for your development process. | ||
523 | However, because the process can vary greatly, this manual does not provide detail on the process. | ||
524 | </para> | ||
525 | |||
526 | <section id='workflow-using-the-adt-and-eclipse'> | ||
527 | <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> | ||
528 | |||
529 | <para> | ||
530 | To help you understand how application development works using the ADT, this section | ||
531 | provides an overview of the general development process and a detailed example of the process | ||
532 | as it is used from within the Eclipse IDE. | ||
533 | </para> | ||
534 | |||
535 | <para> | ||
536 | The following illustration and list summarize the application development general workflow. | ||
537 | </para> | ||
538 | |||
539 | <para> | ||
540 | <imagedata fileref="figures/app-dev-flow.png" | ||
541 | width="7in" depth="8in" align="center" scale="100" /> | ||
542 | </para> | ||
543 | |||
544 | <para> | ||
545 | <orderedlist> | ||
546 | <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: | ||
547 | See | ||
548 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" | ||
549 | and | ||
550 | "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both | ||
551 | in the Yocto Project Reference Manual for requirements. | ||
552 | In particular, be sure your host system has the | ||
553 | <filename>xterm</filename> package installed. | ||
554 | </para></listitem> | ||
555 | <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: | ||
556 | You must have a target kernel image that has been built using the OpenEmbedded | ||
557 | build system.</para> | ||
558 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target | ||
559 | architecture and where you are going to run the image while you develop your application | ||
560 | (QEMU or real hardware), the area from which you get the image differs. | ||
561 | <itemizedlist> | ||
562 | <listitem><para>Download the image from | ||
563 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> | ||
564 | if your target architecture is supported and you are going to develop | ||
565 | and test your application on actual hardware.</para></listitem> | ||
566 | <listitem><para>Download the image from | ||
567 | <ulink url='&YOCTO_QEMU_DL_URL;'> | ||
568 | <filename>machines/qemu</filename></ulink> if your target architecture is supported | ||
569 | and you are going to develop and test your application using the QEMU | ||
570 | emulator.</para></listitem> | ||
571 | <listitem><para>Build your image if you cannot find a pre-built image that matches | ||
572 | your target architecture. | ||
573 | If your target architecture is similar to a supported architecture, you can | ||
574 | modify the kernel image before you build it. | ||
575 | See the | ||
576 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" | ||
577 | section for an example.</para></listitem> | ||
578 | </itemizedlist></para> | ||
579 | <para>For information on pre-built kernel image naming schemes for images | ||
580 | that can run on the QEMU emulator, see the | ||
581 | "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" | ||
582 | section in the Yocto Project Quick Start.</para></listitem> | ||
583 | <listitem><para><emphasis>Install the ADT</emphasis>: | ||
584 | The ADT provides a target-specific cross-development toolchain, the root filesystem, | ||
585 | the QEMU emulator, and other tools that can help you develop your application. | ||
586 | While it is possible to get these pieces separately, the ADT Installer provides an | ||
587 | easy, inclusive method. | ||
588 | You can get these pieces by running an ADT installer script, which is configurable. | ||
589 | For information on how to install the ADT, see the | ||
590 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" | ||
591 | section | ||
592 | in the Yocto Project Application Developer's Guide.</para></listitem> | ||
593 | <listitem><para><emphasis>If applicable, secure the target root filesystem | ||
594 | and the Cross-development toolchain</emphasis>: | ||
595 | If you choose not to install the ADT using the ADT Installer, | ||
596 | you need to find and download the appropriate root filesystem and | ||
597 | the cross-development toolchain.</para> | ||
598 | <para>You can find the tarballs for the root filesystem in the same area used | ||
599 | for the kernel image. | ||
600 | Depending on the type of image you are running, the root filesystem you need differs. | ||
601 | For example, if you are developing an application that runs on an image that | ||
602 | supports Sato, you need to get a root filesystem that supports Sato.</para> | ||
603 | <para>You can find the cross-development toolchains at | ||
604 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. | ||
605 | Be sure to get the correct toolchain for your development host and your | ||
606 | target architecture. | ||
607 | See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | ||
608 | section in the Yocto Project Application Developer's Guide for information | ||
609 | and the | ||
610 | "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" | ||
611 | in the Yocto Project Quick Start for information on finding and installing | ||
612 | the correct toolchain based on your host development system and your target | ||
613 | architecture. | ||
614 | </para></listitem> | ||
615 | <listitem><para><emphasis>Create and build your application</emphasis>: | ||
616 | At this point, you need to have source files for your application. | ||
617 | Once you have the files, you can use the Eclipse IDE to import them and build the | ||
618 | project. | ||
619 | If you are not using Eclipse, you need to use the cross-development tools you have | ||
620 | installed to create the image.</para></listitem> | ||
621 | <listitem><para><emphasis>Deploy the image with the application</emphasis>: | ||
622 | If you are using the Eclipse IDE, you can deploy your image to the hardware or to | ||
623 | QEMU through the project's preferences. | ||
624 | If you are not using the Eclipse IDE, then you need to deploy the application | ||
625 | to the hardware using other methods. | ||
626 | Or, if you are using QEMU, you need to use that tool and | ||
627 | load your image in for testing. | ||
628 | See the | ||
629 | "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" | ||
630 | chapter for information on using QEMU. | ||
631 | </para></listitem> | ||
632 | <listitem><para><emphasis>Test and debug the application</emphasis>: | ||
633 | Once your application is deployed, you need to test it. | ||
634 | Within the Eclipse IDE, you can use the debugging environment along with the | ||
635 | set of user-space tools installed along with the ADT to debug your application. | ||
636 | Of course, the same user-space tools are available separately if you choose | ||
637 | not to use the Eclipse IDE.</para></listitem> | ||
638 | </orderedlist> | ||
639 | </para> | ||
640 | </section> | ||
641 | |||
642 | <section id='adt-eclipse'> | ||
643 | <title>Working Within Eclipse</title> | ||
644 | |||
645 | <para> | ||
646 | The Eclipse IDE is a popular development environment and it fully | ||
647 | supports development using the Yocto Project. | ||
648 | <note> | ||
649 | This release of the Yocto Project supports both the Kepler | ||
650 | and Juno versions of the Eclipse IDE. | ||
651 | Thus, the following information provides setup information for | ||
652 | both versions. | ||
653 | </note> | ||
654 | </para> | ||
655 | |||
656 | <para> | ||
657 | When you install and configure the Eclipse Yocto Project Plug-in | ||
658 | into the Eclipse IDE, you maximize your Yocto Project experience. | ||
659 | Installing and configuring the Plug-in results in an environment | ||
660 | that has extensions specifically designed to let you more easily | ||
661 | develop software. | ||
662 | These extensions allow for cross-compilation, deployment, and | ||
663 | execution of your output into a QEMU emulation session as well as | ||
664 | actual target hardware. | ||
665 | You can also perform cross-debugging and profiling. | ||
666 | The environment also supports a suite of tools that allows you | ||
667 | to perform remote profiling, tracing, collection of power data, | ||
668 | collection of latency data, and collection of performance data. | ||
669 | </para> | ||
670 | |||
671 | <para> | ||
672 | This section describes how to install and configure the Eclipse IDE | ||
673 | Yocto Plug-in and how to use it to develop your application. | ||
674 | </para> | ||
675 | |||
676 | <section id='setting-up-the-eclipse-ide'> | ||
677 | <title>Setting Up the Eclipse IDE</title> | ||
678 | |||
679 | <para> | ||
680 | To develop within the Eclipse IDE, you need to do the following: | ||
681 | <orderedlist> | ||
682 | <listitem><para>Install the optimal version of the Eclipse | ||
683 | IDE.</para></listitem> | ||
684 | <listitem><para>Configure the Eclipse IDE. | ||
685 | </para></listitem> | ||
686 | <listitem><para>Install the Eclipse Yocto Plug-in. | ||
687 | </para></listitem> | ||
688 | <listitem><para>Configure the Eclipse Yocto Plug-in. | ||
689 | </para></listitem> | ||
690 | </orderedlist> | ||
691 | <note> | ||
692 | Do not install Eclipse from your distribution's package | ||
693 | repository. | ||
694 | Be sure to install Eclipse from the official Eclipse | ||
695 | download site as directed in the next section. | ||
696 | </note> | ||
697 | </para> | ||
698 | |||
699 | <section id='installing-eclipse-ide'> | ||
700 | <title>Installing the Eclipse IDE</title> | ||
701 | |||
702 | <para> | ||
703 | It is recommended that you have the Kepler 4.3.2 version of | ||
704 | the Eclipse IDE installed on your development system. | ||
705 | However, if you currently have the Juno 4.2 version | ||
706 | installed and you do not want to upgrade the IDE, you can | ||
707 | configure Juno to work with the Yocto Project. | ||
708 | </para> | ||
709 | |||
710 | <para> | ||
711 | If you do not have the Kepler 4.3.2 Eclipse IDE installed, | ||
712 | you can find the tarball at | ||
713 | <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. | ||
714 | From that site, choose the Eclipse Standard 4.3.2 version | ||
715 | particular to your development host. | ||
716 | This version contains the Eclipse Platform, the Java | ||
717 | Development Tools (JDT), and the Plug-in Development | ||
718 | Environment. | ||
719 | </para> | ||
720 | |||
721 | <para> | ||
722 | Once you have downloaded the tarball, extract it into a | ||
723 | clean directory. | ||
724 | For example, the following commands unpack and install the | ||
725 | downloaded Eclipse IDE tarball into a clean directory | ||
726 | using the default name <filename>eclipse</filename>: | ||
727 | <literallayout class='monospaced'> | ||
728 | $ cd ~ | ||
729 | $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz | ||
730 | </literallayout> | ||
731 | </para> | ||
732 | </section> | ||
733 | |||
734 | <section id='configuring-the-eclipse-ide'> | ||
735 | <title>Configuring the Eclipse IDE</title> | ||
736 | |||
737 | <para> | ||
738 | This section presents the steps needed to configure the | ||
739 | Eclipse IDE. | ||
740 | </para> | ||
741 | |||
742 | <para> | ||
743 | Before installing and configuring the Eclipse Yocto Plug-in, | ||
744 | you need to configure the Eclipse IDE. | ||
745 | Follow these general steps: | ||
746 | <orderedlist> | ||
747 | <listitem><para>Start the Eclipse IDE.</para></listitem> | ||
748 | <listitem><para>Make sure you are in your Workbench and | ||
749 | select "Install New Software" from the "Help" | ||
750 | pull-down menu.</para></listitem> | ||
751 | <listitem><para>Select | ||
752 | <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> | ||
753 | from the "Work with:" pull-down menu. | ||
754 | <note> | ||
755 | For Juno, select | ||
756 | <filename>Juno - &ECLIPSE_JUNO_URL;</filename> | ||
757 | </note> | ||
758 | </para></listitem> | ||
759 | <listitem><para>Expand the box next to "Linux Tools" | ||
760 | and select the | ||
761 | <filename>LTTng - Linux Tracing Toolkit</filename> | ||
762 | boxes.</para></listitem> | ||
763 | <listitem><para>Expand the box next to "Mobile and | ||
764 | Device Development" and select the following boxes: | ||
765 | <itemizedlist> | ||
766 | <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> | ||
767 | <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> | ||
768 | <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> | ||
769 | <listitem><para><filename>Target Management Terminal</filename></para></listitem> | ||
770 | <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> | ||
771 | <listitem><para><filename>TCF Target Explorer</filename></para></listitem> | ||
772 | </itemizedlist></para></listitem> | ||
773 | <listitem><para>Expand the box next to "Programming | ||
774 | Languages" and select the | ||
775 | <filename>C/C++ Autotools Support</filename> | ||
776 | and <filename>C/C++ Development Tools</filename> | ||
777 | boxes.</para></listitem> | ||
778 | <listitem><para>Complete the installation and restart | ||
779 | the Eclipse IDE.</para></listitem> | ||
780 | </orderedlist> | ||
781 | </para> | ||
782 | </section> | ||
783 | |||
784 | <section id='installing-the-eclipse-yocto-plug-in'> | ||
785 | <title>Installing or Accessing the Eclipse Yocto Plug-in</title> | ||
786 | |||
787 | <para> | ||
788 | You can install the Eclipse Yocto Plug-in into the Eclipse | ||
789 | IDE one of two ways: use the Yocto Project's Eclipse | ||
790 | Update site to install the pre-built plug-in or build and | ||
791 | install the plug-in from the latest source code. | ||
792 | </para> | ||
793 | |||
794 | <section id='new-software'> | ||
795 | <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> | ||
796 | |||
797 | <para> | ||
798 | To install the Eclipse Yocto Plug-in from the update | ||
799 | site, follow these steps: | ||
800 | <orderedlist> | ||
801 | <listitem><para>Start up the Eclipse IDE. | ||
802 | </para></listitem> | ||
803 | <listitem><para>In Eclipse, select "Install New | ||
804 | Software" from the "Help" menu. | ||
805 | </para></listitem> | ||
806 | <listitem><para>Click "Add..." in the "Work with:" | ||
807 | area.</para></listitem> | ||
808 | <listitem><para>Enter | ||
809 | <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> | ||
810 | in the URL field and provide a meaningful name | ||
811 | in the "Name" field. | ||
812 | <note> | ||
813 | If you are using Juno, use | ||
814 | <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename> | ||
815 | in the URL field. | ||
816 | </note></para></listitem> | ||
817 | <listitem><para>Click "OK" to have the entry added | ||
818 | to the "Work with:" drop-down list. | ||
819 | </para></listitem> | ||
820 | <listitem><para>Select the entry for the plug-in | ||
821 | from the "Work with:" drop-down list. | ||
822 | </para></listitem> | ||
823 | <listitem><para>Check the boxes next to | ||
824 | <filename>Yocto Project ADT Plug-in</filename>, | ||
825 | <filename>Yocto Project Bitbake Commander Plug-in</filename>, | ||
826 | and | ||
827 | <filename>Yocto Project Documentation plug-in</filename>. | ||
828 | </para></listitem> | ||
829 | <listitem><para>Complete the remaining software | ||
830 | installation steps and then restart the Eclipse | ||
831 | IDE to finish the installation of the plug-in. | ||
832 | </para></listitem> | ||
833 | </orderedlist> | ||
834 | </para> | ||
835 | </section> | ||
836 | |||
837 | <section id='zip-file-method'> | ||
838 | <title>Installing the Plug-in Using the Latest Source Code</title> | ||
839 | |||
840 | <para> | ||
841 | To install the Eclipse Yocto Plug-in from the latest | ||
842 | source code, follow these steps: | ||
843 | <orderedlist> | ||
844 | <listitem><para>Be sure your development system | ||
845 | is not using OpenJDK to build the plug-in | ||
846 | by doing the following: | ||
847 | <orderedlist> | ||
848 | <listitem><para>Use the Oracle JDK. | ||
849 | If you don't have that, go to | ||
850 | <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> | ||
851 | and download the appropriate tarball | ||
852 | for your development system and | ||
853 | extract it into your home directory. | ||
854 | </para></listitem> | ||
855 | <listitem><para>In the shell you are going | ||
856 | to do your work, export the location of | ||
857 | the Oracle Java as follows: | ||
858 | <literallayout class='monospaced'> | ||
859 | export PATH=~/jdk1.7.0_40/bin:$PATH | ||
860 | </literallayout></para></listitem> | ||
861 | </orderedlist></para></listitem> | ||
862 | <listitem><para>In the same shell, create a Git | ||
863 | repository with: | ||
864 | <literallayout class='monospaced'> | ||
865 | $ cd ~ | ||
866 | $ git clone git://git.yoctoproject.org/eclipse-poky-kepler | ||
867 | </literallayout> | ||
868 | <note> | ||
869 | If you are using Juno, the repository is | ||
870 | located at | ||
871 | <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>. | ||
872 | </note> | ||
873 | For this example, the repository is named | ||
874 | <filename>~/eclipse-poky-kepler</filename>. | ||
875 | </para></listitem> | ||
876 | <listitem><para>Change to the directory where you | ||
877 | set up the Git repository: | ||
878 | <literallayout class='monospaced'> | ||
879 | $ cd ~/eclipse-poky-kepler | ||
880 | </literallayout></para></listitem> | ||
881 | <listitem><para>Be sure you are in the right branch | ||
882 | for your Git repository. | ||
883 | For this release set the branch to | ||
884 | <filename>&DISTRO_NAME;</filename>: | ||
885 | <literallayout class='monospaced'> | ||
886 | $ git checkout &DISTRO_NAME; | ||
887 | </literallayout></para></listitem> | ||
888 | <listitem><para>Change to the | ||
889 | <filename>scripts</filename> | ||
890 | directory within the Git repository: | ||
891 | <literallayout class='monospaced'> | ||
892 | $ cd scripts | ||
893 | </literallayout></para></listitem> | ||
894 | <listitem><para>Set up the local build environment | ||
895 | by running the setup script: | ||
896 | <literallayout class='monospaced'> | ||
897 | $ ./setup.sh | ||
898 | </literallayout></para></listitem> | ||
899 | <listitem><para>When the script finishes execution, | ||
900 | it prompts you with instructions on how to run | ||
901 | the <filename>build.sh</filename> script, which | ||
902 | is also in the <filename>scripts</filename> | ||
903 | directory of | ||
904 | the Git repository created earlier. | ||
905 | </para></listitem> | ||
906 | <listitem><para>Run the <filename>build.sh</filename> script | ||
907 | as directed. | ||
908 | Be sure to provide the name of the Git branch | ||
909 | along with the Yocto Project release you are | ||
910 | using. | ||
911 | Here is an example that uses the | ||
912 | <filename>&DISTRO_NAME;</filename> branch: | ||
913 | <literallayout class='monospaced'> | ||
914 | $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; | ||
915 | </literallayout> | ||
916 | After running the script, the file | ||
917 | <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> | ||
918 | is in the current directory.</para></listitem> | ||
919 | <listitem><para>If necessary, start the Eclipse IDE | ||
920 | and be sure you are in the Workbench. | ||
921 | </para></listitem> | ||
922 | <listitem><para>Select "Install New Software" from the "Help" pull-down menu. | ||
923 | </para></listitem> | ||
924 | <listitem><para>Click "Add".</para></listitem> | ||
925 | <listitem><para>Provide anything you want in the | ||
926 | "Name" field.</para></listitem> | ||
927 | <listitem><para>Click "Archive" and browse to the | ||
928 | ZIP file you built in step eight. | ||
929 | This ZIP file should not be "unzipped", and must | ||
930 | be the <filename>*archive.zip</filename> file | ||
931 | created by running the | ||
932 | <filename>build.sh</filename> script. | ||
933 | </para></listitem> | ||
934 | <listitem><para>Click through the "Okay" buttons. | ||
935 | </para></listitem> | ||
936 | <listitem><para>Check the boxes | ||
937 | in the installation window and complete | ||
938 | the installation.</para></listitem> | ||
939 | <listitem><para>Restart the Eclipse IDE if | ||
940 | necessary.</para></listitem> | ||
941 | </orderedlist> | ||
942 | </para> | ||
943 | |||
944 | <para> | ||
945 | At this point you should be able to configure the | ||
946 | Eclipse Yocto Plug-in as described in the | ||
947 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" | ||
948 | section.</para> | ||
949 | </section> | ||
950 | </section> | ||
951 | |||
952 | <section id='configuring-the-eclipse-yocto-plug-in'> | ||
953 | <title>Configuring the Eclipse Yocto Plug-in</title> | ||
954 | |||
955 | <para> | ||
956 | Configuring the Eclipse Yocto Plug-in involves setting the | ||
957 | Cross Compiler options and the Target options. | ||
958 | The configurations you choose become the default settings | ||
959 | for all projects. | ||
960 | You do have opportunities to change them later when | ||
961 | you configure the project (see the following section). | ||
962 | </para> | ||
963 | |||
964 | <para> | ||
965 | To start, you need to do the following from within the | ||
966 | Eclipse IDE: | ||
967 | <itemizedlist> | ||
968 | <listitem><para>Choose "Preferences" from the | ||
969 | "Windows" menu to display the Preferences Dialog. | ||
970 | </para></listitem> | ||
971 | <listitem><para>Click "Yocto Project ADT". | ||
972 | </para></listitem> | ||
973 | </itemizedlist> | ||
974 | </para> | ||
975 | |||
976 | <section id='configuring-the-cross-compiler-options'> | ||
977 | <title>Configuring the Cross-Compiler Options</title> | ||
978 | |||
979 | <para> | ||
980 | To configure the Cross Compiler Options, you must select | ||
981 | the type of toolchain, point to the toolchain, specify | ||
982 | the sysroot location, and select the target | ||
983 | architecture. | ||
984 | <itemizedlist> | ||
985 | <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> | ||
986 | Choose between | ||
987 | <filename>Standalone pre-built toolchain</filename> | ||
988 | and | ||
989 | <filename>Build system derived toolchain</filename> | ||
990 | for Cross Compiler Options. | ||
991 | <itemizedlist> | ||
992 | <listitem><para><emphasis> | ||
993 | <filename>Standalone Pre-built Toolchain:</filename></emphasis> | ||
994 | Select this mode when you are using | ||
995 | a stand-alone cross-toolchain. | ||
996 | For example, suppose you are an | ||
997 | application developer and do not | ||
998 | need to build a target image. | ||
999 | Instead, you just want to use an | ||
1000 | architecture-specific toolchain on | ||
1001 | an existing kernel and target root | ||
1002 | filesystem.</para></listitem> | ||
1003 | <listitem><para><emphasis> | ||
1004 | <filename>Build System Derived Toolchain:</filename></emphasis> | ||
1005 | Select this mode if the | ||
1006 | cross-toolchain has been installed | ||
1007 | and built as part of the | ||
1008 | <link linkend='build-directory'>Build Directory</link>. | ||
1009 | When you select | ||
1010 | <filename>Build system derived toolchain</filename>, | ||
1011 | you are using the toolchain bundled | ||
1012 | inside the Build Directory. | ||
1013 | </para></listitem> | ||
1014 | </itemizedlist> | ||
1015 | </para></listitem> | ||
1016 | <listitem><para><emphasis>Point to the Toolchain:</emphasis> | ||
1017 | If you are using a stand-alone pre-built | ||
1018 | toolchain, you should be pointing to where it is | ||
1019 | installed. | ||
1020 | If you used the ADT Installer script and | ||
1021 | accepted the default installation directory, the | ||
1022 | toolchain will be installed in the | ||
1023 | <filename>&YOCTO_ADTPATH_DIR;</filename> | ||
1024 | directory. | ||
1025 | Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>" | ||
1026 | and | ||
1027 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | ||
1028 | in the Yocto Project Application Developer's | ||
1029 | Guide describe how to install a stand-alone | ||
1030 | cross-toolchain.</para> | ||
1031 | <para>If you are using a system-derived | ||
1032 | toolchain, the path you provide for the | ||
1033 | <filename>Toolchain Root Location</filename> | ||
1034 | field is the | ||
1035 | <link linkend='build-directory'>Build Directory</link>. | ||
1036 | See the | ||
1037 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" | ||
1038 | section in the Yocto Project Application | ||
1039 | Developer's Guide for information on how to | ||
1040 | install the toolchain into the Build | ||
1041 | Directory.</para></listitem> | ||
1042 | <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> | ||
1043 | This location is where the root filesystem for | ||
1044 | the target hardware resides. | ||
1045 | If you used the ADT Installer script and | ||
1046 | accepted the default installation directory, | ||
1047 | then the location is | ||
1048 | <filename>/opt/poky/&DISTRO;</filename>. | ||
1049 | Additionally, when you use the ADT Installer | ||
1050 | script, the same location is used for the QEMU | ||
1051 | user-space tools and the NFS boot process. | ||
1052 | </para> | ||
1053 | <para>If you used either of the other two | ||
1054 | methods to install the toolchain or did not | ||
1055 | accept the ADT Installer script's default | ||
1056 | installation directory, then the location of | ||
1057 | the sysroot filesystem depends on where you | ||
1058 | separately extracted and installed the | ||
1059 | filesystem.</para> | ||
1060 | <para>For information on how to install the | ||
1061 | toolchain and on how to extract and install the | ||
1062 | sysroot filesystem, see the | ||
1063 | "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" | ||
1064 | section in the Yocto Project Application | ||
1065 | Developer's Guide. | ||
1066 | </para></listitem> | ||
1067 | <listitem><para><emphasis>Select the Target Architecture:</emphasis> | ||
1068 | The target architecture is the type of hardware | ||
1069 | you are going to use or emulate. | ||
1070 | Use the pull-down | ||
1071 | <filename>Target Architecture</filename> menu | ||
1072 | to make your selection. | ||
1073 | The pull-down menu should have the supported | ||
1074 | architectures. | ||
1075 | If the architecture you need is not listed in | ||
1076 | the menu, you will need to build the image. | ||
1077 | See the | ||
1078 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
1079 | section of the Yocto Project Quick Start for | ||
1080 | more information.</para></listitem> | ||
1081 | </itemizedlist> | ||
1082 | </para> | ||
1083 | </section> | ||
1084 | |||
1085 | <section id='configuring-the-target-options'> | ||
1086 | <title>Configuring the Target Options</title> | ||
1087 | |||
1088 | <para> | ||
1089 | You can choose to emulate hardware using the QEMU | ||
1090 | emulator, or you can choose to run your image on actual | ||
1091 | hardware. | ||
1092 | <itemizedlist> | ||
1093 | <listitem><para><emphasis>QEMU:</emphasis> | ||
1094 | Select this option if you will be using the | ||
1095 | QEMU emulator. | ||
1096 | If you are using the emulator, you also need to | ||
1097 | locate the kernel and specify any custom | ||
1098 | options.</para> | ||
1099 | <para>If you selected | ||
1100 | <filename>Build system derived toolchain</filename>, | ||
1101 | the target kernel you built will be located in | ||
1102 | the Build Directory in | ||
1103 | <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> | ||
1104 | directory. | ||
1105 | If you selected | ||
1106 | <filename>Standalone pre-built toolchain</filename>, | ||
1107 | the pre-built image you downloaded is located | ||
1108 | in the directory you specified when you | ||
1109 | downloaded the image.</para> | ||
1110 | <para>Most custom options are for advanced QEMU | ||
1111 | users to further customize their QEMU instance. | ||
1112 | These options are specified between paired | ||
1113 | angled brackets. | ||
1114 | Some options must be specified outside the | ||
1115 | brackets. | ||
1116 | In particular, the options | ||
1117 | <filename>serial</filename>, | ||
1118 | <filename>nographic</filename>, and | ||
1119 | <filename>kvm</filename> must all be outside the | ||
1120 | brackets. | ||
1121 | Use the <filename>man qemu</filename> command | ||
1122 | to get help on all the options and their use. | ||
1123 | The following is an example: | ||
1124 | <literallayout class='monospaced'> | ||
1125 | serial ‘<-m 256 -full-screen>’ | ||
1126 | </literallayout></para> | ||
1127 | <para> | ||
1128 | Regardless of the mode, Sysroot is already | ||
1129 | defined as part of the Cross-Compiler Options | ||
1130 | configuration in the | ||
1131 | <filename>Sysroot Location:</filename> field. | ||
1132 | </para></listitem> | ||
1133 | <listitem><para><emphasis>External HW:</emphasis> | ||
1134 | Select this option if you will be using actual | ||
1135 | hardware.</para></listitem> | ||
1136 | </itemizedlist> | ||
1137 | </para> | ||
1138 | |||
1139 | <para> | ||
1140 | Click the "OK" to save your plug-in configurations. | ||
1141 | </para> | ||
1142 | </section> | ||
1143 | </section> | ||
1144 | </section> | ||
1145 | |||
1146 | <section id='creating-the-project'> | ||
1147 | <title>Creating the Project</title> | ||
1148 | |||
1149 | <para> | ||
1150 | You can create two types of projects: Autotools-based, or | ||
1151 | Makefile-based. | ||
1152 | This section describes how to create Autotools-based projects | ||
1153 | from within the Eclipse IDE. | ||
1154 | For information on creating Makefile-based projects in a | ||
1155 | terminal window, see the section | ||
1156 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" | ||
1157 | in the Yocto Project Application Developer's Guide. | ||
1158 | <note> | ||
1159 | Do not use special characters in project names | ||
1160 | (e.g. spaces, underscores, etc.). Doing so can | ||
1161 | cause configuration to fail. | ||
1162 | </note> | ||
1163 | </para> | ||
1164 | |||
1165 | <para> | ||
1166 | To create a project based on a Yocto template and then display | ||
1167 | the source code, follow these steps: | ||
1168 | <orderedlist> | ||
1169 | <listitem><para>Select "Project" from the "File -> New" menu. | ||
1170 | </para></listitem> | ||
1171 | <listitem><para>Double click <filename>CC++</filename>. | ||
1172 | </para></listitem> | ||
1173 | <listitem><para>Double click <filename>C Project</filename> | ||
1174 | to create the project.</para></listitem> | ||
1175 | <listitem><para>Expand <filename>Yocto Project ADT Project</filename>. | ||
1176 | </para></listitem> | ||
1177 | <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. | ||
1178 | This is an Autotools-based project based on a Yocto | ||
1179 | template.</para></listitem> | ||
1180 | <listitem><para>Put a name in the <filename>Project name:</filename> | ||
1181 | field. | ||
1182 | Do not use hyphens as part of the name. | ||
1183 | </para></listitem> | ||
1184 | <listitem><para>Click "Next".</para></listitem> | ||
1185 | <listitem><para>Add information in the | ||
1186 | <filename>Author</filename> and | ||
1187 | <filename>Copyright notice</filename> fields. | ||
1188 | </para></listitem> | ||
1189 | <listitem><para>Be sure the <filename>License</filename> | ||
1190 | field is correct.</para></listitem> | ||
1191 | <listitem><para>Click "Finish".</para></listitem> | ||
1192 | <listitem><para>If the "open perspective" prompt appears, | ||
1193 | click "Yes" so that you in the C/C++ perspective. | ||
1194 | </para></listitem> | ||
1195 | <listitem><para>The left-hand navigation pane shows your | ||
1196 | project. | ||
1197 | You can display your source by double clicking the | ||
1198 | project's source file.</para></listitem> | ||
1199 | </orderedlist> | ||
1200 | </para> | ||
1201 | </section> | ||
1202 | |||
1203 | <section id='configuring-the-cross-toolchains'> | ||
1204 | <title>Configuring the Cross-Toolchains</title> | ||
1205 | |||
1206 | <para> | ||
1207 | The earlier section, | ||
1208 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", | ||
1209 | sets up the default project configurations. | ||
1210 | You can override these settings for a given project by following | ||
1211 | these steps: | ||
1212 | <orderedlist> | ||
1213 | <listitem><para>Select "Change Yocto Project Settings" from | ||
1214 | the "Project" menu. | ||
1215 | This selection brings up the Yocto Project Settings | ||
1216 | Dialog and allows you to make changes specific to an | ||
1217 | individual project.</para> | ||
1218 | <para>By default, the Cross Compiler Options and Target | ||
1219 | Options for a project are inherited from settings you | ||
1220 | provided using the Preferences Dialog as described | ||
1221 | earlier in the | ||
1222 | "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. | ||
1223 | The Yocto Project Settings Dialog allows you to override | ||
1224 | those default settings for a given project. | ||
1225 | </para></listitem> | ||
1226 | <listitem><para>Make your configurations for the project | ||
1227 | and click "OK". | ||
1228 | If you are running the Juno version of Eclipse, you can | ||
1229 | skip down to the next section where you build the | ||
1230 | project. | ||
1231 | If you are not working with Juno, you need to reconfigure the | ||
1232 | project as described in the next step. | ||
1233 | </para></listitem> | ||
1234 | <listitem><para>Select "Reconfigure Project" from the | ||
1235 | "Project" menu. | ||
1236 | This selection reconfigures the project by running | ||
1237 | <filename>autogen.sh</filename> in the workspace for | ||
1238 | your project. | ||
1239 | The script also runs <filename>libtoolize</filename>, | ||
1240 | <filename>aclocal</filename>, | ||
1241 | <filename>autoconf</filename>, | ||
1242 | <filename>autoheader</filename>, | ||
1243 | <filename>automake --a</filename>, and | ||
1244 | <filename>./configure</filename>. | ||
1245 | Click on the "Console" tab beneath your source code to | ||
1246 | see the results of reconfiguring your project. | ||
1247 | </para></listitem> | ||
1248 | </orderedlist> | ||
1249 | </para> | ||
1250 | </section> | ||
1251 | |||
1252 | <section id='building-the-project'> | ||
1253 | <title>Building the Project</title> | ||
1254 | |||
1255 | <para> | ||
1256 | To build the project in Juno, right click on the project in | ||
1257 | the navigator pane and select "Build Project". | ||
1258 | If you are not running Juno, select "Build Project" from the | ||
1259 | "Project" menu. | ||
1260 | The console should update and you can note the cross-compiler | ||
1261 | you are using. | ||
1262 | </para> | ||
1263 | </section> | ||
1264 | |||
1265 | <section id='starting-qemu-in-user-space-nfs-mode'> | ||
1266 | <title>Starting QEMU in User-Space NFS Mode</title> | ||
1267 | |||
1268 | <para> | ||
1269 | To start the QEMU emulator from within Eclipse, follow these | ||
1270 | steps: | ||
1271 | <note> | ||
1272 | See the | ||
1273 | "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" | ||
1274 | chapter for more information on using QEMU. | ||
1275 | </note> | ||
1276 | <orderedlist> | ||
1277 | <listitem><para>Expose and select "External Tools" from | ||
1278 | the "Run" menu. | ||
1279 | Your image should appear as a selectable menu item. | ||
1280 | </para></listitem> | ||
1281 | <listitem><para>Select your image from the menu to launch | ||
1282 | the emulator in a new window.</para></listitem> | ||
1283 | <listitem><para>If needed, enter your host root password in | ||
1284 | the shell window at the prompt. | ||
1285 | This sets up a <filename>Tap 0</filename> connection | ||
1286 | needed for running in user-space NFS mode. | ||
1287 | </para></listitem> | ||
1288 | <listitem><para>Wait for QEMU to launch.</para></listitem> | ||
1289 | <listitem><para>Once QEMU launches, you can begin operating | ||
1290 | within that environment. | ||
1291 | For example, you could determine the IP Address | ||
1292 | for the user-space NFS by using the | ||
1293 | <filename>ifconfig</filename> command.</para></listitem> | ||
1294 | </orderedlist> | ||
1295 | </para> | ||
1296 | </section> | ||
1297 | |||
1298 | <section id='deploying-and-debugging-the-application'> | ||
1299 | <title>Deploying and Debugging the Application</title> | ||
1300 | |||
1301 | <para> | ||
1302 | Once the QEMU emulator is running the image, you can deploy | ||
1303 | your application using the Eclipse IDE and then use | ||
1304 | the emulator to perform debugging. | ||
1305 | Follow these steps to deploy the application. | ||
1306 | <orderedlist> | ||
1307 | <listitem><para>Select "Debug Configurations..." from the | ||
1308 | "Run" menu.</para></listitem> | ||
1309 | <listitem><para>In the left area, expand | ||
1310 | <filename>C/C++Remote Application</filename>. | ||
1311 | </para></listitem> | ||
1312 | <listitem><para>Locate your project and select it to bring | ||
1313 | up a new tabbed view in the Debug Configurations Dialog. | ||
1314 | </para></listitem> | ||
1315 | <listitem><para>Enter the absolute path into which you want | ||
1316 | to deploy the application. | ||
1317 | Use the "Remote Absolute File Path for | ||
1318 | C/C++Application:" field. | ||
1319 | For example, enter | ||
1320 | <filename>/usr/bin/<programname></filename>. | ||
1321 | </para></listitem> | ||
1322 | <listitem><para>Click on the "Debugger" tab to see the | ||
1323 | cross-tool debugger you are using.</para></listitem> | ||
1324 | <listitem><para>Click on the "Main" tab.</para></listitem> | ||
1325 | <listitem><para>Create a new connection to the QEMU instance | ||
1326 | by clicking on "new".</para></listitem> | ||
1327 | <listitem><para>Select <filename>TCF</filename>, which means | ||
1328 | Target Communication Framework.</para></listitem> | ||
1329 | <listitem><para>Click "Next".</para></listitem> | ||
1330 | <listitem><para>Clear out the "host name" field and enter | ||
1331 | the IP Address determined earlier.</para></listitem> | ||
1332 | <listitem><para>Click "Finish" to close the | ||
1333 | New Connections Dialog.</para></listitem> | ||
1334 | <listitem><para>Use the drop-down menu now in the | ||
1335 | "Connection" field and pick the IP Address you entered. | ||
1336 | </para></listitem> | ||
1337 | <listitem><para>Click "Run" to bring up a login screen | ||
1338 | and login.</para></listitem> | ||
1339 | <listitem><para>Accept the debug perspective. | ||
1340 | </para></listitem> | ||
1341 | </orderedlist> | ||
1342 | </para> | ||
1343 | </section> | ||
1344 | |||
1345 | <section id='running-user-space-tools'> | ||
1346 | <title>Running User-Space Tools</title> | ||
1347 | |||
1348 | <para> | ||
1349 | As mentioned earlier in the manual, several tools exist that | ||
1350 | enhance your development experience. | ||
1351 | These tools are aids in developing and debugging applications | ||
1352 | and images. | ||
1353 | You can run these user-space tools from within the Eclipse | ||
1354 | IDE through the "YoctoTools" menu. | ||
1355 | </para> | ||
1356 | |||
1357 | <para> | ||
1358 | Once you pick a tool, you need to configure it for the remote | ||
1359 | target. | ||
1360 | Every tool needs to have the connection configured. | ||
1361 | You must select an existing TCF-based RSE connection to the | ||
1362 | remote target. | ||
1363 | If one does not exist, click "New" to create one. | ||
1364 | </para> | ||
1365 | |||
1366 | <para> | ||
1367 | Here are some specifics about the remote tools: | ||
1368 | <itemizedlist> | ||
1369 | <listitem><para><emphasis><filename>OProfile</filename>:</emphasis> | ||
1370 | Selecting this tool causes the | ||
1371 | <filename>oprofile-server</filename> on the remote | ||
1372 | target to launch on the local host machine. | ||
1373 | The <filename>oprofile-viewer</filename> must be | ||
1374 | installed on the local host machine and the | ||
1375 | <filename>oprofile-server</filename> must be installed | ||
1376 | on the remote target, respectively, in order to use. | ||
1377 | You must compile and install the | ||
1378 | <filename>oprofile-viewer</filename> from the source | ||
1379 | code on your local host machine. | ||
1380 | Furthermore, in order to convert the target's sample | ||
1381 | format data into a form that the host can use, you must | ||
1382 | have OProfile version 0.9.4 or greater installed on the | ||
1383 | host.</para> | ||
1384 | <para>You can locate both the viewer and server from | ||
1385 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. | ||
1386 | You can also find more information on setting up and | ||
1387 | using this tool in the | ||
1388 | "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" | ||
1389 | section of the Yocto Project Profiling and Tracing | ||
1390 | Manual. | ||
1391 | <note>The <filename>oprofile-server</filename> is | ||
1392 | installed by default on the | ||
1393 | <filename>core-image-sato-sdk</filename> image.</note> | ||
1394 | </para></listitem> | ||
1395 | <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis> | ||
1396 | Selecting this tool transfers the remote target's | ||
1397 | <filename>Lttng</filename> tracing data back to the | ||
1398 | local host machine and uses the Lttng Eclipse plug-in | ||
1399 | to graphically display the output. | ||
1400 | For information on how to use Lttng to trace an | ||
1401 | application, | ||
1402 | see <ulink url='http://lttng.org/documentation'></ulink> | ||
1403 | and the | ||
1404 | "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" | ||
1405 | section, which is in the Yocto Project Profiling and | ||
1406 | Tracing Manual. | ||
1407 | <note>Do not use | ||
1408 | <filename>Lttng-user space (legacy)</filename> tool. | ||
1409 | This tool no longer has any upstream support.</note> | ||
1410 | </para> | ||
1411 | <para>Before you use the | ||
1412 | <filename>Lttng2.0 ust trace import</filename> tool, | ||
1413 | you need to setup the Lttng Eclipse plug-in and create a | ||
1414 | Tracing project. | ||
1415 | Do the following: | ||
1416 | <orderedlist> | ||
1417 | <listitem><para>Select "Open Perspective" from the | ||
1418 | "Window" menu and then select "Tracing". | ||
1419 | </para></listitem> | ||
1420 | <listitem><para>Click "OK" to change the Eclipse | ||
1421 | perspective into the Tracing perspective. | ||
1422 | </para></listitem> | ||
1423 | <listitem><para>Create a new Tracing project by | ||
1424 | selecting "Project" from the "File -> New" menu. | ||
1425 | </para></listitem> | ||
1426 | <listitem><para>Choose "Tracing Project" from the | ||
1427 | "Tracing" menu. | ||
1428 | </para></listitem> | ||
1429 | <listitem><para>Generate your tracing data on the | ||
1430 | remote target.</para></listitem> | ||
1431 | <listitem><para>Select "Lttng2.0 ust trace import" | ||
1432 | from the "Yocto Project Tools" menu to | ||
1433 | start the data import process.</para></listitem> | ||
1434 | <listitem><para>Specify your remote connection name. | ||
1435 | </para></listitem> | ||
1436 | <listitem><para>For the Ust directory path, specify | ||
1437 | the location of your remote tracing data. | ||
1438 | Make sure the location ends with | ||
1439 | <filename>ust</filename> (e.g. | ||
1440 | <filename>/usr/mysession/ust</filename>). | ||
1441 | </para></listitem> | ||
1442 | <listitem><para>Click "OK" to complete the import | ||
1443 | process. | ||
1444 | The data is now in the local tracing project | ||
1445 | you created.</para></listitem> | ||
1446 | <listitem><para>Right click on the data and then use | ||
1447 | the menu to Select "Generic CTF Trace" from the | ||
1448 | "Trace Type... -> Common Trace Format" menu to | ||
1449 | map the tracing type.</para></listitem> | ||
1450 | <listitem><para>Right click the mouse and select | ||
1451 | "Open" to bring up the Eclipse Lttng Trace | ||
1452 | Viewer so you view the tracing data. | ||
1453 | </para></listitem> | ||
1454 | </orderedlist></para></listitem> | ||
1455 | <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> | ||
1456 | Selecting this tool runs PowerTOP on the remote target | ||
1457 | machine and displays the results in a new view called | ||
1458 | PowerTOP.</para> | ||
1459 | <para>The "Time to gather data(sec):" field is the time | ||
1460 | passed in seconds before data is gathered from the | ||
1461 | remote target for analysis.</para> | ||
1462 | <para>The "show pids in wakeups list:" field corresponds | ||
1463 | to the <filename>-p</filename> argument passed to | ||
1464 | <filename>PowerTOP</filename>.</para></listitem> | ||
1465 | <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> | ||
1466 | LatencyTOP identifies system latency, while | ||
1467 | Perf monitors the system's performance counter | ||
1468 | registers. | ||
1469 | Selecting either of these tools causes an RSE terminal | ||
1470 | view to appear from which you can run the tools. | ||
1471 | Both tools refresh the entire screen to display results | ||
1472 | while they run. | ||
1473 | For more information on setting up and using | ||
1474 | <filename>perf</filename>, see the | ||
1475 | "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" | ||
1476 | section in the Yocto Project Profiling and Tracing | ||
1477 | Manual. | ||
1478 | </para></listitem> | ||
1479 | </itemizedlist> | ||
1480 | </para> | ||
1481 | </section> | ||
1482 | |||
1483 | <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> | ||
1484 | <title>Customizing an Image Using a BitBake Commander Project and Hob</title> | ||
1485 | |||
1486 | <para> | ||
1487 | Within the Eclipse IDE, you can create a Yocto BitBake Commander | ||
1488 | project, edit the <link linkend='metadata'>Metadata</link>, and | ||
1489 | then use | ||
1490 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE. | ||
1491 | </para> | ||
1492 | |||
1493 | <section id='creating-the-yocto-bitbake-commander-project'> | ||
1494 | <title>Creating the Yocto BitBake Commander Project</title> | ||
1495 | |||
1496 | <para> | ||
1497 | To create a Yocto BitBake Commander project, follow these | ||
1498 | steps: | ||
1499 | <orderedlist> | ||
1500 | <listitem><para>Select "Other" from the | ||
1501 | "Window -> Open Perspective" menu | ||
1502 | and then choose "Bitbake Commander". | ||
1503 | </para></listitem> | ||
1504 | <listitem><para>Click "OK" to change the perspective to | ||
1505 | Bitbake Commander.</para></listitem> | ||
1506 | <listitem><para>Select "Project" from the "File -> New" | ||
1507 | menu to create a new Yocto | ||
1508 | Bitbake Commander project.</para></listitem> | ||
1509 | <listitem><para>Choose "New Yocto Project" from the | ||
1510 | "Yocto Project Bitbake Commander" menu and click | ||
1511 | "Next".</para></listitem> | ||
1512 | <listitem><para>Enter the Project Name and choose the | ||
1513 | Project Location. | ||
1514 | The Yocto project's Metadata files will be put under | ||
1515 | the directory | ||
1516 | <filename><replaceable>project_location</replaceable>/<replaceable>project_name</replaceable></filename>. | ||
1517 | If that directory does not exist, you need to check | ||
1518 | the "Clone from Yocto Git Repository" box, which | ||
1519 | would execute a <filename>git clone</filename> | ||
1520 | command to get the project's Metadata files. | ||
1521 | <note> | ||
1522 | Do not specify your BitBake Commander project | ||
1523 | location as your Eclipse workspace. | ||
1524 | Doing so causes an error indicating that the | ||
1525 | current project overlaps the location of | ||
1526 | another project. | ||
1527 | This error occurs even if no such project exits. | ||
1528 | </note></para></listitem> | ||
1529 | <listitem><para>Select <filename>Finish</filename> to | ||
1530 | create the project.</para></listitem> | ||
1531 | </orderedlist> | ||
1532 | </para> | ||
1533 | </section> | ||
1534 | |||
1535 | <section id='editing-the-metadata'> | ||
1536 | <title>Editing the Metadata</title> | ||
1537 | |||
1538 | <para> | ||
1539 | After you create the Yocto Bitbake Commander project, you | ||
1540 | can modify the <link linkend='metadata'>Metadata</link> | ||
1541 | files by opening them in the project. | ||
1542 | When editing recipe files (<filename>.bb</filename> files), | ||
1543 | you can view BitBake variable values and information by | ||
1544 | hovering the mouse pointer over the variable name and | ||
1545 | waiting a few seconds. | ||
1546 | </para> | ||
1547 | |||
1548 | <para> | ||
1549 | To edit the Metadata, follow these steps: | ||
1550 | <orderedlist> | ||
1551 | <listitem><para>Select your Yocto Bitbake Commander | ||
1552 | project.</para></listitem> | ||
1553 | <listitem><para>Select "BitBake Recipe" from the | ||
1554 | "File -> New -> Yocto BitBake Commander" menu | ||
1555 | to open a new recipe wizard.</para></listitem> | ||
1556 | <listitem><para>Point to your source by filling in the | ||
1557 | "SRC_URL" field. | ||
1558 | For example, you can add a recipe to your | ||
1559 | <link linkend='source-directory'>Source Directory</link> | ||
1560 | by defining "SRC_URL" as follows: | ||
1561 | <literallayout class='monospaced'> | ||
1562 | ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz | ||
1563 | </literallayout></para></listitem> | ||
1564 | <listitem><para>Click "Populate" to calculate the | ||
1565 | archive md5, sha256, license checksum values and to | ||
1566 | auto-generate the recipe filename.</para></listitem> | ||
1567 | <listitem><para>Fill in the "Description" field. | ||
1568 | </para></listitem> | ||
1569 | <listitem><para>Be sure values for all required | ||
1570 | fields exist.</para></listitem> | ||
1571 | <listitem><para>Click "Finish".</para></listitem> | ||
1572 | </orderedlist> | ||
1573 | </para> | ||
1574 | </section> | ||
1575 | |||
1576 | <section id='biding-and-customizing-the-image-using-hob'> | ||
1577 | <title>Building and Customizing the Image Using Hob</title> | ||
1578 | |||
1579 | <para> | ||
1580 | To build and customize the image using Hob from within the | ||
1581 | Eclipse IDE, follow these steps: | ||
1582 | <orderedlist> | ||
1583 | <listitem><para>Select your Yocto Bitbake Commander | ||
1584 | project.</para></listitem> | ||
1585 | <listitem><para>Select "Launch Hob" from the "Project" | ||
1586 | menu.</para></listitem> | ||
1587 | <listitem><para>Enter the | ||
1588 | <link linkend='build-directory'>Build Directory</link> | ||
1589 | where you want to put your final images. | ||
1590 | </para></listitem> | ||
1591 | <listitem><para>Click "OK" to launch Hob. | ||
1592 | </para></listitem> | ||
1593 | <listitem><para>Use Hob to customize and build your own | ||
1594 | images. | ||
1595 | For information on Hob, see the | ||
1596 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink> | ||
1597 | on the Yocto Project website.</para></listitem> | ||
1598 | </orderedlist> | ||
1599 | </para> | ||
1600 | </section> | ||
1601 | </section> | ||
1602 | </section> | ||
1603 | |||
1604 | <section id='workflow-using-stand-alone-cross-development-toolchains'> | ||
1605 | <title>Workflow Using Stand-Alone Cross-Development Toolchains</title> | ||
1606 | |||
1607 | <para> | ||
1608 | If you want to develop an application without prior installation | ||
1609 | of the ADT, you still can employ the | ||
1610 | <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>, | ||
1611 | the QEMU emulator, and a number of supported target image files. | ||
1612 | You just need to follow these general steps: | ||
1613 | <orderedlist> | ||
1614 | <listitem><para><emphasis>Install the cross-development | ||
1615 | toolchain for your target hardware:</emphasis> | ||
1616 | For information on how to install the toolchain, see the | ||
1617 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" | ||
1618 | section in the Yocto Project Application Developer's | ||
1619 | Guide.</para></listitem> | ||
1620 | <listitem><para><emphasis>Download the Target Image:</emphasis> | ||
1621 | The Yocto Project supports several target architectures | ||
1622 | and has many pre-built kernel images and root filesystem | ||
1623 | images.</para> | ||
1624 | <para>If you are going to develop your application on | ||
1625 | hardware, go to the | ||
1626 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> | ||
1627 | download area and choose a target machine area | ||
1628 | from which to download the kernel image and root filesystem. | ||
1629 | This download area could have several files in it that | ||
1630 | support development using actual hardware. | ||
1631 | For example, the area might contain | ||
1632 | <filename>.hddimg</filename> files that combine the | ||
1633 | kernel image with the filesystem, boot loaders, and | ||
1634 | so forth. | ||
1635 | Be sure to get the files you need for your particular | ||
1636 | development process.</para> | ||
1637 | <para>If you are going to develop your application and | ||
1638 | then run and test it using the QEMU emulator, go to the | ||
1639 | <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> | ||
1640 | download area. | ||
1641 | From this area, go down into the directory for your | ||
1642 | target architecture (e.g. <filename>qemux86_64</filename> | ||
1643 | for an <trademark class='registered'>Intel</trademark>-based | ||
1644 | 64-bit architecture). | ||
1645 | Download kernel, root filesystem, and any other files you | ||
1646 | need for your process. | ||
1647 | <note>In order to use the root filesystem in QEMU, you | ||
1648 | need to extract it. | ||
1649 | See the | ||
1650 | "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" | ||
1651 | section for information on how to extract the root | ||
1652 | filesystem.</note></para></listitem> | ||
1653 | <listitem><para><emphasis>Develop and Test your | ||
1654 | Application:</emphasis> At this point, you have the tools | ||
1655 | to develop your application. | ||
1656 | If you need to separately install and use the QEMU | ||
1657 | emulator, you can go to | ||
1658 | <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> | ||
1659 | to download and learn about the emulator. | ||
1660 | You can see the | ||
1661 | "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" | ||
1662 | chapter for information on using QEMU within the Yocto | ||
1663 | Project.</para></listitem> | ||
1664 | </orderedlist> | ||
1665 | </para> | ||
1666 | </section> | ||
1667 | </section> | ||
1668 | |||
1669 | <section id="modifying-temporary-source-code"> | ||
1670 | <title>Modifying Temporary Source Code</title> | ||
1671 | |||
1672 | <para> | ||
1673 | You might | ||
1674 | find it helpful during development to modify the temporary source code used by recipes | ||
1675 | to build packages. | ||
1676 | For example, suppose you are developing a patch and you need to experiment a bit | ||
1677 | to figure out your solution. | ||
1678 | After you have initially built the package, you can iteratively tweak the | ||
1679 | source code, which is located in the | ||
1680 | <link linkend='build-directory'>Build Directory</link>, and then | ||
1681 | you can force a re-compile and quickly test your altered code. | ||
1682 | Once you settle on a solution, you can then preserve your changes in the form of | ||
1683 | patches. | ||
1684 | You can accomplish these steps all within either a | ||
1685 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or | ||
1686 | <link linkend='git'>Git</link> workflow. | ||
1687 | </para> | ||
1688 | |||
1689 | <section id='finding-the-temporary-source-code'> | ||
1690 | <title>Finding the Temporary Source Code</title> | ||
1691 | |||
1692 | <para> | ||
1693 | During a build, the unpacked temporary source code used by recipes | ||
1694 | to build packages is available in the Build Directory as | ||
1695 | defined by the | ||
1696 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. | ||
1697 | Below is the default value for the <filename>S</filename> variable as defined in the | ||
1698 | <filename>meta/conf/bitbake.conf</filename> configuration file in the | ||
1699 | <link linkend='source-directory'>Source Directory</link>: | ||
1700 | <literallayout class='monospaced'> | ||
1701 | S = "${WORKDIR}/${BP}" | ||
1702 | </literallayout> | ||
1703 | You should be aware that many recipes override the <filename>S</filename> variable. | ||
1704 | For example, recipes that fetch their source from Git usually set | ||
1705 | <filename>S</filename> to <filename>${WORKDIR}/git</filename>. | ||
1706 | <note> | ||
1707 | The | ||
1708 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> | ||
1709 | represents the base recipe name, which consists of the name and version: | ||
1710 | <literallayout class='monospaced'> | ||
1711 | BP = "${BPN}-${PV}" | ||
1712 | </literallayout> | ||
1713 | </note> | ||
1714 | </para> | ||
1715 | |||
1716 | <para> | ||
1717 | The path to the work directory for the recipe | ||
1718 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) | ||
1719 | is defined as follows: | ||
1720 | <literallayout class='monospaced'> | ||
1721 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | ||
1722 | </literallayout> | ||
1723 | The actual directory depends on several things: | ||
1724 | <itemizedlist> | ||
1725 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: | ||
1726 | The top-level build output directory</listitem> | ||
1727 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: | ||
1728 | The target system identifier</listitem> | ||
1729 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: | ||
1730 | The recipe name</listitem> | ||
1731 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: | ||
1732 | The epoch - (if | ||
1733 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> | ||
1734 | is not specified, which is usually the case for most | ||
1735 | recipes, then <filename>EXTENDPE</filename> is blank)</listitem> | ||
1736 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: | ||
1737 | The recipe version</listitem> | ||
1738 | <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: | ||
1739 | The recipe revision</listitem> | ||
1740 | </itemizedlist> | ||
1741 | </para> | ||
1742 | |||
1743 | <para> | ||
1744 | As an example, assume a Source Directory top-level folder | ||
1745 | name <filename>poky</filename>, a default Build Directory at | ||
1746 | <filename>poky/build</filename>, and a | ||
1747 | <filename>qemux86-poky-linux</filename> machine target | ||
1748 | system. | ||
1749 | Furthermore, suppose your recipe is named | ||
1750 | <filename>foo_1.3.0.bb</filename>. | ||
1751 | In this case, the work directory the build system uses to | ||
1752 | build the package would be as follows: | ||
1753 | <literallayout class='monospaced'> | ||
1754 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | ||
1755 | </literallayout> | ||
1756 | </para> | ||
1757 | |||
1758 | <para> | ||
1759 | Now that you know where to locate the directory that has the temporary source code, | ||
1760 | you can use a Quilt or Git workflow to make your edits, test the changes, | ||
1761 | and preserve the changes in the form of patches. | ||
1762 | </para> | ||
1763 | </section> | ||
1764 | |||
1765 | <section id="using-a-quilt-workflow"> | ||
1766 | <title>Using a Quilt Workflow</title> | ||
1767 | |||
1768 | <para> | ||
1769 | <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> | ||
1770 | is a powerful tool that allows you to capture source code changes without having | ||
1771 | a clean source tree. | ||
1772 | This section outlines the typical workflow you can use to modify temporary source code, | ||
1773 | test changes, and then preserve the changes in the form of a patch all using Quilt. | ||
1774 | </para> | ||
1775 | |||
1776 | <para> | ||
1777 | Follow these general steps: | ||
1778 | <orderedlist> | ||
1779 | <listitem><para><emphasis>Find the Source Code:</emphasis> | ||
1780 | The temporary source code used by the OpenEmbedded build system is kept in the | ||
1781 | Build Directory. | ||
1782 | See the | ||
1783 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | ||
1784 | section to learn how to locate the directory that has the temporary source code for a | ||
1785 | particular package.</para></listitem> | ||
1786 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> | ||
1787 | You need to be in the directory that has the temporary source code. | ||
1788 | That directory is defined by the | ||
1789 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
1790 | variable.</para></listitem> | ||
1791 | <listitem><para><emphasis>Create a New Patch:</emphasis> | ||
1792 | Before modifying source code, you need to create a new patch. | ||
1793 | To create a new patch file, use <filename>quilt new</filename> as below: | ||
1794 | <literallayout class='monospaced'> | ||
1795 | $ quilt new my_changes.patch | ||
1796 | </literallayout></para></listitem> | ||
1797 | <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> | ||
1798 | After creating the patch, you need to notify Quilt about the files | ||
1799 | you plan to edit. | ||
1800 | You notify Quilt by adding the files to the patch you just created: | ||
1801 | <literallayout class='monospaced'> | ||
1802 | $ quilt add file1.c file2.c file3.c | ||
1803 | </literallayout> | ||
1804 | </para></listitem> | ||
1805 | <listitem><para><emphasis>Edit the Files:</emphasis> | ||
1806 | Make your changes in the temporary source code to the files you added | ||
1807 | to the patch.</para></listitem> | ||
1808 | <listitem><para><emphasis>Test Your Changes:</emphasis> | ||
1809 | Once you have modified the source code, the easiest way to | ||
1810 | your changes is by calling the | ||
1811 | <filename>do_compile</filename> task as shown in the | ||
1812 | following example: | ||
1813 | <literallayout class='monospaced'> | ||
1814 | $ bitbake -c compile -f <replaceable>name_of_package</replaceable> | ||
1815 | </literallayout> | ||
1816 | The <filename>-f</filename> or <filename>--force</filename> | ||
1817 | option forces the specified task to execute. | ||
1818 | If you find problems with your code, you can just keep editing and | ||
1819 | re-testing iteratively until things work as expected. | ||
1820 | <note>All the modifications you make to the temporary source code | ||
1821 | disappear once you run the | ||
1822 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink> | ||
1823 | or | ||
1824 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink> | ||
1825 | tasks using BitBake (i.e. | ||
1826 | <filename>bitbake -c clean <replaceable>name_of_package</replaceable></filename> | ||
1827 | and | ||
1828 | <filename>bitbake -c cleanall <replaceable>name_of_package</replaceable></filename>). | ||
1829 | Modifications will also disappear if you use the <filename>rm_work</filename> | ||
1830 | feature as described in the | ||
1831 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
1832 | section of the Yocto Project Quick Start. | ||
1833 | </note></para></listitem> | ||
1834 | <listitem><para><emphasis>Generate the Patch:</emphasis> | ||
1835 | Once your changes work as expected, you need to use Quilt to generate the final patch that | ||
1836 | contains all your modifications. | ||
1837 | <literallayout class='monospaced'> | ||
1838 | $ quilt refresh | ||
1839 | </literallayout> | ||
1840 | At this point, the <filename>my_changes.patch</filename> file has all your edits made | ||
1841 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and | ||
1842 | <filename>file3.c</filename> files.</para> | ||
1843 | <para>You can find the resulting patch file in the <filename>patches/</filename> | ||
1844 | subdirectory of the source (<filename>S</filename>) directory.</para></listitem> | ||
1845 | <listitem><para><emphasis>Copy the Patch File:</emphasis> | ||
1846 | For simplicity, copy the patch file into a directory named <filename>files</filename>, | ||
1847 | which you can create in the same directory that holds the recipe | ||
1848 | (<filename>.bb</filename>) file or the | ||
1849 | append (<filename>.bbappend</filename>) file. | ||
1850 | Placing the patch here guarantees that the OpenEmbedded build system will find | ||
1851 | the patch. | ||
1852 | Next, add the patch into the | ||
1853 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | ||
1854 | of the recipe. | ||
1855 | Here is an example: | ||
1856 | <literallayout class='monospaced'> | ||
1857 | SRC_URI += "file://my_changes.patch" | ||
1858 | </literallayout></para></listitem> | ||
1859 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> | ||
1860 | Finally, don't forget to 'bump' the | ||
1861 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> | ||
1862 | value in the recipe since the resulting packages have changed.</para></listitem> | ||
1863 | </orderedlist> | ||
1864 | </para> </section> | ||
1865 | |||
1866 | <section id='using-a-git-workflow'> | ||
1867 | <title>Using a Git Workflow</title> | ||
1868 | <para> | ||
1869 | Git is an even more powerful tool that allows you to capture source code changes without having | ||
1870 | a clean source tree. | ||
1871 | This section outlines the typical workflow you can use to modify temporary source code, | ||
1872 | test changes, and then preserve the changes in the form of a patch all using Git. | ||
1873 | For general information on Git as it is used in the Yocto Project, see the | ||
1874 | "<link linkend='git'>Git</link>" section. | ||
1875 | </para> | ||
1876 | |||
1877 | <note> | ||
1878 | This workflow uses Git only for its ability to manage local changes to the source code | ||
1879 | and produce patches independent of any version control system used with the Yocto Project. | ||
1880 | </note> | ||
1881 | |||
1882 | <para> | ||
1883 | Follow these general steps: | ||
1884 | <orderedlist> | ||
1885 | <listitem><para><emphasis>Find the Source Code:</emphasis> | ||
1886 | The temporary source code used by the OpenEmbedded build system is kept in the | ||
1887 | Build Directory. | ||
1888 | See the | ||
1889 | "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" | ||
1890 | section to learn how to locate the directory that has the temporary source code for a | ||
1891 | particular package.</para></listitem> | ||
1892 | <listitem><para><emphasis>Change Your Working Directory:</emphasis> | ||
1893 | You need to be in the directory that has the temporary source code. | ||
1894 | That directory is defined by the | ||
1895 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
1896 | variable.</para></listitem> | ||
1897 | <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> | ||
1898 | If the recipe you are working with does not use a Git fetcher, | ||
1899 | you need to set up a Git repository as follows: | ||
1900 | <literallayout class='monospaced'> | ||
1901 | $ git init | ||
1902 | $ git add * | ||
1903 | $ git commit -m "initial revision" | ||
1904 | </literallayout> | ||
1905 | The above Git commands initialize a Git repository that is based on the | ||
1906 | files in your current working directory, stage all the files, and commit | ||
1907 | the files. | ||
1908 | At this point, your Git repository is aware of all the source code files. | ||
1909 | Any edits you now make to files can be committed later and will be tracked by | ||
1910 | Git.</para></listitem> | ||
1911 | <listitem><para><emphasis>Edit the Files:</emphasis> | ||
1912 | Make your changes to the temporary source code.</para></listitem> | ||
1913 | <listitem><para><emphasis>Test Your Changes:</emphasis> | ||
1914 | Once you have modified the source code, the easiest way | ||
1915 | to test your changes is by calling the | ||
1916 | <filename>do_compile</filename> task as shown in the | ||
1917 | following example: | ||
1918 | <literallayout class='monospaced'> | ||
1919 | $ bitbake -c compile -f <replaceable>name_of_package</replaceable> | ||
1920 | </literallayout> | ||
1921 | The <filename>-f</filename> or <filename>--force</filename> | ||
1922 | option forces the specified task to execute. | ||
1923 | If you find problems with your code, you can just keep editing and | ||
1924 | re-testing iteratively until things work as expected. | ||
1925 | <note>All the modifications you make to the temporary source code | ||
1926 | disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>, | ||
1927 | or <filename>-c cleanall</filename> with BitBake for the package. | ||
1928 | Modifications will also disappear if you use the <filename>rm_work</filename> | ||
1929 | feature as described in the | ||
1930 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
1931 | section of the Yocto Project Quick Start. | ||
1932 | </note></para></listitem> | ||
1933 | <listitem><para><emphasis>See the List of Files You Changed:</emphasis> | ||
1934 | Use the <filename>git status</filename> command to see what files you have actually edited. | ||
1935 | The ability to have Git track the files you have changed is an advantage that this | ||
1936 | workflow has over the Quilt workflow. | ||
1937 | Here is the Git command to list your changed files: | ||
1938 | <literallayout class='monospaced'> | ||
1939 | $ git status | ||
1940 | </literallayout></para></listitem> | ||
1941 | <listitem><para><emphasis>Stage the Modified Files:</emphasis> | ||
1942 | Use the <filename>git add</filename> command to stage the changed files so they | ||
1943 | can be committed as follows: | ||
1944 | <literallayout class='monospaced'> | ||
1945 | $ git add file1.c file2.c file3.c | ||
1946 | </literallayout></para></listitem> | ||
1947 | <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> | ||
1948 | Use the <filename>git commit</filename> command to commit the changes to the | ||
1949 | local repository. | ||
1950 | Once you have committed the files, you can use the <filename>git log</filename> | ||
1951 | command to see your changes: | ||
1952 | <literallayout class='monospaced'> | ||
1953 | $ git commit -m "<replaceable>commit-summary-message</replaceable>" | ||
1954 | $ git log | ||
1955 | </literallayout> | ||
1956 | <note>The name of the patch file created in the next step is based on your | ||
1957 | <replaceable>commit-summary-message</replaceable>.</note></para></listitem> | ||
1958 | <listitem><para><emphasis>Generate the Patch:</emphasis> | ||
1959 | Once the changes are committed, use the <filename>git format-patch</filename> | ||
1960 | command to generate a patch file: | ||
1961 | <literallayout class='monospaced'> | ||
1962 | $ git format-patch -1 | ||
1963 | </literallayout> | ||
1964 | Specifying "-1" causes Git to generate the | ||
1965 | patch file for the most recent commit.</para> | ||
1966 | <para>At this point, the patch file has all your edits made | ||
1967 | to the <filename>file1.c</filename>, <filename>file2.c</filename>, and | ||
1968 | <filename>file3.c</filename> files. | ||
1969 | You can find the resulting patch file in the current directory and it | ||
1970 | is named according to the <filename>git commit</filename> summary line. | ||
1971 | The patch file ends with <filename>.patch</filename>.</para></listitem> | ||
1972 | <listitem><para><emphasis>Copy the Patch File:</emphasis> | ||
1973 | For simplicity, copy the patch file into a directory named <filename>files</filename>, | ||
1974 | which you can create in the same directory that holds the recipe | ||
1975 | (<filename>.bb</filename>) file or the | ||
1976 | append (<filename>.bbappend</filename>) file. | ||
1977 | Placing the patch here guarantees that the OpenEmbedded build system will find | ||
1978 | the patch. | ||
1979 | Next, add the patch into the | ||
1980 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> | ||
1981 | of the recipe. | ||
1982 | Here is an example: | ||
1983 | <literallayout class='monospaced'> | ||
1984 | SRC_URI += "file://0001-<replaceable>commit-summary-message</replaceable>.patch" | ||
1985 | </literallayout></para></listitem> | ||
1986 | <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> | ||
1987 | Finally, don't forget to 'bump' the | ||
1988 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> | ||
1989 | value in the recipe since the resulting packages have changed.</para></listitem> | ||
1990 | </orderedlist> | ||
1991 | </para> | ||
1992 | </section> | ||
1993 | </section> | ||
1994 | |||
1995 | <section id='image-development-using-hob'> | ||
1996 | <title>Image Development Using Hob</title> | ||
1997 | |||
1998 | <para> | ||
1999 | The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the | ||
2000 | OpenEmbedded build system, which is based on BitBake. | ||
2001 | You can use the Hob to build custom operating system images within the Yocto Project build environment. | ||
2002 | Hob simply provides a friendly interface over the build system used during development. | ||
2003 | In other words, building images with the Hob lets you take care of common build tasks more easily. | ||
2004 | </para> | ||
2005 | |||
2006 | <para> | ||
2007 | For a better understanding of Hob, see the project page at | ||
2008 | <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink> | ||
2009 | on the Yocto Project website. | ||
2010 | If you follow the "Documentation" link from the Hob page, you will | ||
2011 | find a short introductory training video on Hob. | ||
2012 | The following lists some features of Hob: | ||
2013 | <itemizedlist> | ||
2014 | <listitem><para>You can setup and run Hob using these commands: | ||
2015 | <literallayout class='monospaced'> | ||
2016 | $ source oe-init-build-env | ||
2017 | $ hob | ||
2018 | </literallayout></para></listitem> | ||
2019 | <listitem><para>You can set the | ||
2020 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> | ||
2021 | for which you are building the image.</para></listitem> | ||
2022 | <listitem><para>You can modify various policy settings such as the | ||
2023 | package format with which to build, | ||
2024 | the parallelism BitBake uses, whether or not to build an | ||
2025 | external toolchain, and which host to build against. | ||
2026 | </para></listitem> | ||
2027 | <listitem><para>You can manage | ||
2028 | <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem> | ||
2029 | <listitem><para>You can select a base image and then add extra packages for your custom build. | ||
2030 | </para></listitem> | ||
2031 | <listitem><para>You can launch and monitor the build from within Hob.</para></listitem> | ||
2032 | </itemizedlist> | ||
2033 | </para> | ||
2034 | </section> | ||
2035 | |||
2036 | <section id="platdev-appdev-devshell"> | ||
2037 | <title>Using a Development Shell</title> | ||
2038 | |||
2039 | <para> | ||
2040 | When debugging certain commands or even when just editing packages, | ||
2041 | <filename>devshell</filename> can be a useful tool. | ||
2042 | When you invoke <filename>devshell</filename>, source files are | ||
2043 | extracted into your working directory and patches are applied. | ||
2044 | Then, a new terminal is opened and you are placed in the working directory. | ||
2045 | In the new terminal, all the OpenEmbedded build-related environment variables are | ||
2046 | still defined so you can use commands such as <filename>configure</filename> and | ||
2047 | <filename>make</filename>. | ||
2048 | The commands execute just as if the OpenEmbedded build system were executing them. | ||
2049 | Consequently, working this way can be helpful when debugging a build or preparing | ||
2050 | software to be used with the OpenEmbedded build system. | ||
2051 | </para> | ||
2052 | |||
2053 | <para> | ||
2054 | Following is an example that uses <filename>devshell</filename> on a target named | ||
2055 | <filename>matchbox-desktop</filename>: | ||
2056 | <literallayout class='monospaced'> | ||
2057 | $ bitbake matchbox-desktop -c devshell | ||
2058 | </literallayout> | ||
2059 | </para> | ||
2060 | |||
2061 | <para> | ||
2062 | This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. | ||
2063 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> | ||
2064 | variable controls what type of shell is opened. | ||
2065 | </para> | ||
2066 | |||
2067 | <para> | ||
2068 | For spawned terminals, the following occurs: | ||
2069 | <itemizedlist> | ||
2070 | <listitem><para>The <filename>PATH</filename> variable includes the | ||
2071 | cross-toolchain.</para></listitem> | ||
2072 | <listitem><para>The <filename>pkgconfig</filename> variables find the correct | ||
2073 | <filename>.pc</filename> files.</para></listitem> | ||
2074 | <listitem><para>The <filename>configure</filename> command finds the | ||
2075 | Yocto Project site files as well as any other necessary files.</para></listitem> | ||
2076 | </itemizedlist> | ||
2077 | </para> | ||
2078 | |||
2079 | <para> | ||
2080 | Within this environment, you can run configure or compile | ||
2081 | commands as if they were being run by | ||
2082 | the OpenEmbedded build system itself. | ||
2083 | As noted earlier, the working directory also automatically changes to the | ||
2084 | Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). | ||
2085 | </para> | ||
2086 | |||
2087 | <para> | ||
2088 | When you are finished, you just exit the shell or close the terminal window. | ||
2089 | </para> | ||
2090 | |||
2091 | <note> | ||
2092 | <para> | ||
2093 | It is worth remembering that when using <filename>devshell</filename> | ||
2094 | you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> | ||
2095 | instead of just using <filename>gcc</filename>. | ||
2096 | The same applies to other applications such as <filename>binutils</filename>, | ||
2097 | <filename>libtool</filename> and so forth. | ||
2098 | BitBake sets up environment variables such as <filename>CC</filename> | ||
2099 | to assist applications, such as <filename>make</filename> to find the correct tools. | ||
2100 | </para> | ||
2101 | |||
2102 | <para> | ||
2103 | It is also worth noting that <filename>devshell</filename> still works over | ||
2104 | X11 forwarding and similar situations. | ||
2105 | </para> | ||
2106 | </note> | ||
2107 | </section> | ||
2108 | |||
2109 | </chapter> | ||
2110 | <!-- | ||
2111 | vim: expandtab tw=80 ts=4 | ||
2112 | --> | ||
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml new file mode 100644 index 0000000000..2385187f4d --- /dev/null +++ b/documentation/dev-manual/dev-manual-newbie.xml | |||
@@ -0,0 +1,1692 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='dev-manual-newbie'> | ||
6 | |||
7 | <title>The Yocto Project Open Source Development Environment</title> | ||
8 | |||
9 | <para> | ||
10 | This chapter helps you understand the Yocto Project as an open source development project. | ||
11 | In general, working in an open source environment is very different from working in a | ||
12 | closed, proprietary environment. | ||
13 | Additionally, the Yocto Project uses specific tools and constructs as part of its development | ||
14 | environment. | ||
15 | This chapter specifically addresses open source philosophy, using the | ||
16 | Yocto Project in a team environment, source repositories, Yocto Project | ||
17 | terms, licensing, the open source distributed version control system Git, | ||
18 | workflows, bug tracking, and how to submit changes. | ||
19 | </para> | ||
20 | |||
21 | <section id='open-source-philosophy'> | ||
22 | <title>Open Source Philosophy</title> | ||
23 | |||
24 | <para> | ||
25 | Open source philosophy is characterized by software development directed by peer production | ||
26 | and collaboration through an active community of developers. | ||
27 | Contrast this to the more standard centralized development models used by commercial software | ||
28 | companies where a finite set of developers produces a product for sale using a defined set | ||
29 | of procedures that ultimately result in an end product whose architecture and source material | ||
30 | are closed to the public. | ||
31 | </para> | ||
32 | |||
33 | <para> | ||
34 | Open source projects conceptually have differing concurrent agendas, approaches, and production. | ||
35 | These facets of the development process can come from anyone in the public (community) that has a | ||
36 | stake in the software project. | ||
37 | The open source environment contains new copyright, licensing, domain, and consumer issues | ||
38 | that differ from the more traditional development environment. | ||
39 | In an open source environment, the end product, source material, and documentation are | ||
40 | all available to the public at no cost. | ||
41 | </para> | ||
42 | |||
43 | <para> | ||
44 | A benchmark example of an open source project is the Linux kernel, which was initially conceived | ||
45 | and created by Finnish computer science student Linus Torvalds in 1991. | ||
46 | Conversely, a good example of a non-open source project is the | ||
47 | <trademark class='registered'>Windows</trademark> family of operating | ||
48 | systems developed by <trademark class='registered'>Microsoft</trademark> Corporation. | ||
49 | </para> | ||
50 | |||
51 | <para> | ||
52 | Wikipedia has a good historical description of the Open Source Philosophy | ||
53 | <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. | ||
54 | You can also find helpful information on how to participate in the Linux Community | ||
55 | <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. | ||
56 | </para> | ||
57 | </section> | ||
58 | |||
59 | <section id="usingpoky-changes-collaborate"> | ||
60 | <title>Using the Yocto Project in a Team Environment</title> | ||
61 | |||
62 | <para> | ||
63 | It might not be immediately clear how you can use the Yocto | ||
64 | Project in a team environment, or scale it for a large team of | ||
65 | developers. | ||
66 | One of the strengths of the Yocto Project is that it is extremely | ||
67 | flexible. | ||
68 | Thus, you can adapt it to many different use cases and scenarios. | ||
69 | However, these characteristics can cause a struggle if you are trying | ||
70 | to create a working setup that scales across a large team. | ||
71 | </para> | ||
72 | |||
73 | <para> | ||
74 | To help with these types of situations, this section presents | ||
75 | some of the project's most successful experiences, | ||
76 | practices, solutions, and available technologies that work well. | ||
77 | Keep in mind, the information here is a starting point. | ||
78 | You can build off it and customize it to fit any | ||
79 | particular working environment and set of practices. | ||
80 | </para> | ||
81 | |||
82 | <section id='best-practices-system-configurations'> | ||
83 | <title>System Configurations</title> | ||
84 | |||
85 | <para> | ||
86 | Systems across a large team should meet the needs of | ||
87 | two types of developers: those working on the contents of the | ||
88 | operating system image itself and those developing applications. | ||
89 | Regardless of the type of developer, their workstations must | ||
90 | be both reasonably powerful and run Linux. | ||
91 | </para> | ||
92 | |||
93 | <section id='best-practices-application-development'> | ||
94 | <title>Application Development</title> | ||
95 | |||
96 | <para> | ||
97 | For developers who mainly do application level work | ||
98 | on top of an existing software stack, | ||
99 | here are some practices that work best: | ||
100 | <itemizedlist> | ||
101 | <listitem><para>Use a pre-built toolchain that | ||
102 | contains the software stack itself. | ||
103 | Then, develop the application code on top of the | ||
104 | stack. | ||
105 | This method works well for small numbers of relatively | ||
106 | isolated applications.</para></listitem> | ||
107 | <listitem><para>When possible, use the Yocto Project | ||
108 | plug-in for the <trademark class='trade'>Eclipse</trademark> IDE | ||
109 | and other pieces of Application Development | ||
110 | Technology (ADT). | ||
111 | For more information, see the | ||
112 | "<link linkend='application-development-workflow'>Application | ||
113 | Development Workflow</link>" section as well as the | ||
114 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. | ||
115 | </para></listitem> | ||
116 | <listitem><para>Keep your cross-development toolchains | ||
117 | updated. | ||
118 | You can do this through provisioning either as new | ||
119 | toolchain downloads or as updates through a package | ||
120 | update mechanism using <filename>opkg</filename> | ||
121 | to provide updates to an existing toolchain. | ||
122 | The exact mechanics of how and when to do this are a | ||
123 | question for local policy.</para></listitem> | ||
124 | <listitem><para>Use multiple toolchains installed locally | ||
125 | into different locations to allow development across | ||
126 | versions.</para></listitem> | ||
127 | </itemizedlist> | ||
128 | </para> | ||
129 | </section> | ||
130 | |||
131 | <section id='best-practices-core-system-development'> | ||
132 | <title>Core System Development</title> | ||
133 | |||
134 | <para> | ||
135 | For core system development, it is often best to have the | ||
136 | build system itself available on the developer workstations | ||
137 | so developers can run their own builds and directly | ||
138 | rebuild the software stack. | ||
139 | You should keep the core system unchanged as much as | ||
140 | possible and do your work in layers on top of the core system. | ||
141 | Doing so gives you a greater level of portability when | ||
142 | upgrading to new versions of the core system or Board | ||
143 | Support Packages (BSPs). | ||
144 | You can share layers amongst the developers of a particular | ||
145 | project and contain the policy configuration that defines | ||
146 | the project. | ||
147 | </para> | ||
148 | |||
149 | <para> | ||
150 | Aside from the previous best practices, there exists a number | ||
151 | of tips and tricks that can help speed up core development | ||
152 | projects: | ||
153 | <itemizedlist> | ||
154 | <listitem><para>Use a | ||
155 | <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink> | ||
156 | (sstate) among groups of developers who are on a | ||
157 | fast network. | ||
158 | The best way to share sstate is through a | ||
159 | Network File System (NFS) share. | ||
160 | The first user to build a given component for the | ||
161 | first time contributes that object to the sstate, | ||
162 | while subsequent builds from other developers then | ||
163 | reuse the object rather than rebuild it themselves. | ||
164 | </para> | ||
165 | <para>Although it is possible to use other protocols for the | ||
166 | sstate such as HTTP and FTP, you should avoid these. | ||
167 | Using HTTP limits the sstate to read-only and | ||
168 | FTP provides poor performance. | ||
169 | </para></listitem> | ||
170 | <listitem><para>Have autobuilders contribute to the sstate | ||
171 | pool similarly to how the developer workstations | ||
172 | contribute. | ||
173 | For information, see the | ||
174 | "<link linkend='best-practices-autobuilders'>Autobuilders</link>" | ||
175 | section.</para></listitem> | ||
176 | <listitem><para>Build stand-alone tarballs that contain | ||
177 | "missing" system requirements if for some reason | ||
178 | developer workstations do not meet minimum system | ||
179 | requirements such as latest Python versions, | ||
180 | <filename>chrpath</filename>, or other tools. | ||
181 | You can install and relocate the tarball exactly as you | ||
182 | would the usual cross-development toolchain so that | ||
183 | all developers can meet minimum version requirements | ||
184 | on most distributions.</para></listitem> | ||
185 | <listitem><para>Use a small number of shared, | ||
186 | high performance systems for testing purposes | ||
187 | (e.g. dual, six-core Xeons with 24 Gbytes of RAM | ||
188 | and plenty of disk space). | ||
189 | Developers can use these systems for wider, more | ||
190 | extensive testing while they continue to develop | ||
191 | locally using their primary development system. | ||
192 | </para></listitem> | ||
193 | <listitem><para>Enable the PR Service when package feeds | ||
194 | need to be incremental with continually increasing | ||
195 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink> | ||
196 | values. | ||
197 | Typically, this situation occurs when you use or | ||
198 | publish package feeds and use a shared state. | ||
199 | You should enable the PR Service for all users who | ||
200 | use the shared state pool. | ||
201 | For more information on the PR Service, see the | ||
202 | "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>". | ||
203 | </para></listitem> | ||
204 | </itemizedlist> | ||
205 | </para> | ||
206 | </section> | ||
207 | </section> | ||
208 | |||
209 | <section id='best-practices-source-control-management'> | ||
210 | <title>Source Control Management (SCM)</title> | ||
211 | |||
212 | <para> | ||
213 | Keeping your | ||
214 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | ||
215 | and any software you are developing under the | ||
216 | control of an SCM system that is compatible | ||
217 | with the OpenEmbedded build system is advisable. | ||
218 | Of the SCMs BitBake supports, the | ||
219 | Yocto Project team strongly recommends using | ||
220 | <link linkend='git'>Git</link>. | ||
221 | Git is a distributed system that is easy to backup, | ||
222 | allows you to work remotely, and then connects back to the | ||
223 | infrastructure. | ||
224 | <note> | ||
225 | For information about BitBake, see the | ||
226 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
227 | </note> | ||
228 | </para> | ||
229 | |||
230 | <para> | ||
231 | It is relatively easy to set up Git services and create | ||
232 | infrastructure like | ||
233 | <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, | ||
234 | which is based on server software called | ||
235 | <filename>gitolite</filename> with <filename>cgit</filename> | ||
236 | being used to generate the web interface that lets you view the | ||
237 | repositories. | ||
238 | The <filename>gitolite</filename> software identifies users | ||
239 | using SSH keys and allows branch-based | ||
240 | access controls to repositories that you can control as little | ||
241 | or as much as necessary. | ||
242 | </para> | ||
243 | |||
244 | <note> | ||
245 | The setup of these services is beyond the scope of this manual. | ||
246 | However, sites such as these exist that describe how to perform | ||
247 | setup: | ||
248 | <itemizedlist> | ||
249 | <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: | ||
250 | Describes how to install <filename>gitolite</filename> | ||
251 | on the server.</para></listitem> | ||
252 | <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>: | ||
253 | All topics for <filename>gitolite</filename>. | ||
254 | </para></listitem> | ||
255 | <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: | ||
256 | Documentation on how to create interfaces and frontends | ||
257 | for Git.</para></listitem> | ||
258 | </itemizedlist> | ||
259 | </note> | ||
260 | </section> | ||
261 | |||
262 | <section id='best-practices-autobuilders'> | ||
263 | <title>Autobuilders</title> | ||
264 | |||
265 | <para> | ||
266 | Autobuilders are often the core of a development project. | ||
267 | It is here that changes from individual developers are brought | ||
268 | together and centrally tested and subsequent decisions about | ||
269 | releases can be made. | ||
270 | Autobuilders also allow for "continuous integration" style | ||
271 | testing of software components and regression identification | ||
272 | and tracking. | ||
273 | </para> | ||
274 | |||
275 | <para> | ||
276 | See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" | ||
277 | for more information and links to buildbot. | ||
278 | The Yocto Project team has found this implementation | ||
279 | works well in this role. | ||
280 | A public example of this is the Yocto Project | ||
281 | Autobuilders, which we use to test the overall health of the | ||
282 | project. | ||
283 | </para> | ||
284 | |||
285 | <para> | ||
286 | The features of this system are: | ||
287 | <itemizedlist> | ||
288 | <listitem><para>Highlights when commits break the build. | ||
289 | </para></listitem> | ||
290 | <listitem><para>Populates an sstate cache from which | ||
291 | developers can pull rather than requiring local | ||
292 | builds.</para></listitem> | ||
293 | <listitem><para>Allows commit hook triggers, | ||
294 | which trigger builds when commits are made. | ||
295 | </para></listitem> | ||
296 | <listitem><para>Allows triggering of automated image booting | ||
297 | and testing under the QuickEMUlator (QEMU). | ||
298 | </para></listitem> | ||
299 | <listitem><para>Supports incremental build testing and | ||
300 | from-scratch builds.</para></listitem> | ||
301 | <listitem><para>Shares output that allows developer | ||
302 | testing and historical regression investigation. | ||
303 | </para></listitem> | ||
304 | <listitem><para>Creates output that can be used for releases. | ||
305 | </para></listitem> | ||
306 | <listitem><para>Allows scheduling of builds so that resources | ||
307 | can be used efficiently.</para></listitem> | ||
308 | </itemizedlist> | ||
309 | </para> | ||
310 | </section> | ||
311 | |||
312 | <section id='best-practices-policies-and-change-flow'> | ||
313 | <title>Policies and Change Flow</title> | ||
314 | |||
315 | <para> | ||
316 | The Yocto Project itself uses a hierarchical structure and a | ||
317 | pull model. | ||
318 | Scripts exist to create and send pull requests | ||
319 | (i.e. <filename>create-pull-request</filename> and | ||
320 | <filename>send-pull-request</filename>). | ||
321 | This model is in line with other open source projects where | ||
322 | maintainers are responsible for specific areas of the project | ||
323 | and a single maintainer handles the final "top-of-tree" merges. | ||
324 | </para> | ||
325 | |||
326 | <note> | ||
327 | You can also use a more collective push model. | ||
328 | The <filename>gitolite</filename> software supports both the | ||
329 | push and pull models quite easily. | ||
330 | </note> | ||
331 | |||
332 | <para> | ||
333 | As with any development environment, it is important | ||
334 | to document the policy used as well as any main project | ||
335 | guidelines so they are understood by everyone. | ||
336 | It is also a good idea to have well structured | ||
337 | commit messages, which are usually a part of a project's | ||
338 | guidelines. | ||
339 | Good commit messages are essential when looking back in time and | ||
340 | trying to understand why changes were made. | ||
341 | </para> | ||
342 | |||
343 | <para> | ||
344 | If you discover that changes are needed to the core layer of the | ||
345 | project, it is worth sharing those with the community as soon | ||
346 | as possible. | ||
347 | Chances are if you have discovered the need for changes, someone | ||
348 | else in the community needs them also. | ||
349 | </para> | ||
350 | </section> | ||
351 | |||
352 | <section id='best-practices-summary'> | ||
353 | <title>Summary</title> | ||
354 | |||
355 | <para> | ||
356 | This section summarizes the key recommendations described in the | ||
357 | previous sections: | ||
358 | <itemizedlist> | ||
359 | <listitem><para>Use <link linkend='git'>Git</link> | ||
360 | as the source control system.</para></listitem> | ||
361 | <listitem><para>Maintain your Metadata in layers that make sense | ||
362 | for your situation. | ||
363 | See the "<link linkend='understanding-and-creating-layers'>Understanding | ||
364 | and Creating Layers</link>" section for more information on | ||
365 | layers.</para></listitem> | ||
366 | <listitem><para> | ||
367 | Separate the project's Metadata and code by using | ||
368 | separate Git repositories. | ||
369 | See the | ||
370 | "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>" | ||
371 | section for information on these repositories. | ||
372 | See the | ||
373 | "<link linkend='getting-setup'>Getting Set Up</link>" | ||
374 | section for information on how to set up local Git | ||
375 | repositories for related upstream Yocto Project | ||
376 | Git repositories. | ||
377 | </para></listitem> | ||
378 | <listitem><para>Set up the directory for the shared state cache | ||
379 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) | ||
380 | where it makes sense. | ||
381 | For example, set up the sstate cache on a system used | ||
382 | by developers in the same organization and share the | ||
383 | same source directories on their machines. | ||
384 | </para></listitem> | ||
385 | <listitem><para>Set up an Autobuilder and have it populate the | ||
386 | sstate cache and source directories.</para></listitem> | ||
387 | <listitem><para>The Yocto Project community encourages you | ||
388 | to send patches to the project to fix bugs or add features. | ||
389 | If you do submit patches, follow the project commit | ||
390 | guidelines for writing good commit messages. | ||
391 | See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
392 | section.</para></listitem> | ||
393 | <listitem><para>Send changes to the core sooner than later | ||
394 | as others are likely to run into the same issues. | ||
395 | For some guidance on mailing lists to use, see the list in the | ||
396 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
397 | section. | ||
398 | For a description of the available mailing lists, see the | ||
399 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" | ||
400 | section in the Yocto Project Reference Manual. | ||
401 | </para></listitem> | ||
402 | </itemizedlist> | ||
403 | </para> | ||
404 | </section> | ||
405 | </section> | ||
406 | |||
407 | <section id='yocto-project-repositories'> | ||
408 | <title>Yocto Project Source Repositories</title> | ||
409 | |||
410 | <para> | ||
411 | The Yocto Project team maintains complete source repositories for all | ||
412 | Yocto Project files at | ||
413 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. | ||
414 | This web-based source code browser is organized into categories by | ||
415 | function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and | ||
416 | so forth. | ||
417 | From the interface, you can click on any particular item in the "Name" | ||
418 | column and see the URL at the bottom of the page that you need to clone | ||
419 | a Git repository for that particular item. | ||
420 | Having a local Git repository of the | ||
421 | <link linkend='source-directory'>Source Directory</link>, which is | ||
422 | usually named "poky", allows | ||
423 | you to make changes, contribute to the history, and ultimately enhance | ||
424 | the Yocto Project's tools, Board Support Packages, and so forth. | ||
425 | </para> | ||
426 | |||
427 | <para> | ||
428 | For any supported release of Yocto Project, you can also go to the | ||
429 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and | ||
430 | select the "Downloads" tab and get a released tarball of the | ||
431 | <filename>poky</filename> repository or any supported BSP tarballs. | ||
432 | Unpacking these tarballs gives you a snapshot of the released | ||
433 | files. | ||
434 | <note><title>Notes</title> | ||
435 | <itemizedlist> | ||
436 | <listitem><para> | ||
437 | The recommended method for setting up the Yocto Project | ||
438 | <link linkend='source-directory'>Source Directory</link> | ||
439 | and the files for supported BSPs | ||
440 | (e.g., <filename>meta-intel</filename>) is to use | ||
441 | <link linkend='git'>Git</link> to create a local copy of | ||
442 | the upstream repositories. | ||
443 | </para></listitem> | ||
444 | <listitem><para> | ||
445 | Be sure to always work in matching branches for both | ||
446 | the selected BSP repository and the | ||
447 | <link linkend='source-directory'>Source Directory</link> | ||
448 | (i.e. <filename>poky</filename>) repository. | ||
449 | For example, if you have checked out the "master" branch | ||
450 | of <filename>poky</filename> and you are going to use | ||
451 | <filename>meta-intel</filename>, be sure to checkout the | ||
452 | "master" branch of <filename>meta-intel</filename>. | ||
453 | </para></listitem> | ||
454 | </itemizedlist> | ||
455 | </note> | ||
456 | </para> | ||
457 | |||
458 | <para> | ||
459 | In summary, here is where you can get the project files needed for development: | ||
460 | <itemizedlist> | ||
461 | <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> | ||
462 | This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto | ||
463 | Metadata Layers. | ||
464 | You can create local copies of Git repositories for each of these areas.</para> | ||
465 | <para> | ||
466 | <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> | ||
467 | </para></listitem> | ||
468 | <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> | ||
469 | This is an index of releases such as | ||
470 | the <trademark class='trade'>Eclipse</trademark> | ||
471 | Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains, | ||
472 | and all released versions of Yocto Project in the form of images or tarballs. | ||
473 | Downloading and extracting these files does not produce a local copy of the | ||
474 | Git repository but rather a snapshot of a particular release or image.</para> | ||
475 | <para> | ||
476 | <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" /> | ||
477 | </para></listitem> | ||
478 | <listitem><para><emphasis>"Downloads" page for the | ||
479 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis> | ||
480 | Access this page by going to the website and then selecting | ||
481 | the "Downloads" tab. | ||
482 | This page allows you to download any Yocto Project | ||
483 | release or Board Support Package (BSP) in tarball form. | ||
484 | The tarballs are similar to those found in the | ||
485 | <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para> | ||
486 | <para> | ||
487 | <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> | ||
488 | </para></listitem> | ||
489 | </itemizedlist> | ||
490 | </para> | ||
491 | </section> | ||
492 | |||
493 | <section id='yocto-project-terms'> | ||
494 | <title>Yocto Project Terms</title> | ||
495 | |||
496 | <para> | ||
497 | Following is a list of terms and definitions users new to the Yocto Project development | ||
498 | environment might find helpful. | ||
499 | While some of these terms are universal, the list includes them just in case: | ||
500 | <itemizedlist> | ||
501 | <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to | ||
502 | a recipe file. | ||
503 | Append files are known as BitBake append files and <filename>.bbappend</filename> files. | ||
504 | The OpenEmbedded build system expects every append file to have a corresponding | ||
505 | recipe (<filename>.bb</filename>) file. | ||
506 | Furthermore, the append file and corresponding recipe file | ||
507 | must use the same root filename. | ||
508 | The filenames can differ only in the file type suffix used (e.g. | ||
509 | <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). | ||
510 | </para> | ||
511 | <para>Information in append files extends or overrides the | ||
512 | information in the similarly-named recipe file. | ||
513 | For an example of an append file in use, see the | ||
514 | "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. | ||
515 | <note> | ||
516 | Append files can also use wildcard patterns in their version numbers | ||
517 | so they can be applied to more than one version of the underlying recipe file. | ||
518 | </note> | ||
519 | </para></listitem> | ||
520 | <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> | ||
521 | The task executor and scheduler used by the OpenEmbedded build | ||
522 | system to build images. | ||
523 | For more information on BitBake, see the | ||
524 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
525 | </para></listitem> | ||
526 | <listitem> | ||
527 | <para id='build-directory'><emphasis>Build Directory:</emphasis> | ||
528 | This term refers to the area used by the OpenEmbedded build | ||
529 | system for builds. | ||
530 | The area is created when you <filename>source</filename> the | ||
531 | setup environment script that is found in the Source Directory | ||
532 | (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
533 | or | ||
534 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). | ||
535 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> | ||
536 | variable points to the Build Directory.</para> | ||
537 | |||
538 | <para> | ||
539 | You have a lot of flexibility when creating the Build | ||
540 | Directory. | ||
541 | Following are some examples that show how to create the | ||
542 | directory. | ||
543 | The examples assume your | ||
544 | <link linkend='source-directory'>Source Directory</link> is | ||
545 | named <filename>poky</filename>: | ||
546 | <itemizedlist> | ||
547 | <listitem><para>Create the Build Directory inside your | ||
548 | Source Directory and let the name of the Build | ||
549 | Directory default to <filename>build</filename>: | ||
550 | <literallayout class='monospaced'> | ||
551 | $ cd $HOME/poky | ||
552 | $ source &OE_INIT_FILE; | ||
553 | </literallayout></para></listitem> | ||
554 | <listitem><para>Create the Build Directory inside your | ||
555 | home directory and specifically name it | ||
556 | <filename>test-builds</filename>: | ||
557 | <literallayout class='monospaced'> | ||
558 | $ cd $HOME | ||
559 | $ source poky/&OE_INIT_FILE; test-builds | ||
560 | </literallayout></para></listitem> | ||
561 | <listitem><para> | ||
562 | Provide a directory path and | ||
563 | specifically name the Build Directory. | ||
564 | Any intermediate folders in the pathname must | ||
565 | exist. | ||
566 | This next example creates a Build Directory named | ||
567 | <filename>YP-&POKYVERSION;</filename> | ||
568 | in your home directory within the existing | ||
569 | directory <filename>mybuilds</filename>: | ||
570 | <literallayout class='monospaced'> | ||
571 | $cd $HOME | ||
572 | $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; | ||
573 | </literallayout></para></listitem> | ||
574 | </itemizedlist> | ||
575 | <note> | ||
576 | By default, the Build Directory contains | ||
577 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, | ||
578 | which is a temporary directory the build system uses for | ||
579 | its work. | ||
580 | <filename>TMPDIR</filename> cannot be under NFS. | ||
581 | Thus, by default, the Build Directory cannot be under NFS. | ||
582 | However, if you need the Build Directory to be under NFS, | ||
583 | you can set this up by setting <filename>TMPDIR</filename> | ||
584 | in your <filename>local.conf</filename> file | ||
585 | to use a local drive. | ||
586 | Doing so effectively separates <filename>TMPDIR</filename> | ||
587 | from <filename>TOPDIR</filename>, which is the Build | ||
588 | Directory. | ||
589 | </note> | ||
590 | </para></listitem> | ||
591 | <listitem><para id='build-system-term'><emphasis>Build System:</emphasis> | ||
592 | In the context of the Yocto Project, | ||
593 | this term refers to the OpenEmbedded build system used by the project. | ||
594 | This build system is based on the project known as "Poky." | ||
595 | For some historical information about Poky, see the | ||
596 | <link linkend='poky'>Poky</link> term. | ||
597 | </para></listitem> | ||
598 | <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation | ||
599 | and inheritance so that commonly used patterns can be defined once and then easily used | ||
600 | in multiple recipes. | ||
601 | For reference information on the Yocto Project classes, see the | ||
602 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the | ||
603 | Yocto Project Reference Manual. | ||
604 | Class files end with the <filename>.bbclass</filename> filename extension. | ||
605 | </para></listitem> | ||
606 | <listitem><para><emphasis>Configuration File:</emphasis> | ||
607 | Configuration information in various <filename>.conf</filename> | ||
608 | files provides global definitions of variables. | ||
609 | The <filename>conf/local.conf</filename> configuration file in | ||
610 | the | ||
611 | <link linkend='build-directory'>Build Directory</link> | ||
612 | contains user-defined variables that affect every build. | ||
613 | The <filename>meta-yocto/conf/distro/poky.conf</filename> | ||
614 | configuration file defines Yocto "distro" configuration | ||
615 | variables used only when building with this policy. | ||
616 | Machine configuration files, which | ||
617 | are located throughout the | ||
618 | <link linkend='source-directory'>Source Directory</link>, define | ||
619 | variables for specific hardware and are only used when building | ||
620 | for that target (e.g. the | ||
621 | <filename>machine/beaglebone.conf</filename> configuration | ||
622 | file defines variables for the Texas Instruments ARM Cortex-A8 | ||
623 | development board). | ||
624 | Configuration files end with a <filename>.conf</filename> | ||
625 | filename extension. | ||
626 | </para></listitem> | ||
627 | <listitem><para id='cross-development-toolchain'> | ||
628 | <emphasis>Cross-Development Toolchain:</emphasis> | ||
629 | In general, a cross-development toolchain is a collection of | ||
630 | software development tools and utilities that run on one | ||
631 | architecture and allow you to develop software for a | ||
632 | different, or targeted, architecture. | ||
633 | These toolchains contain cross-compilers, linkers, and | ||
634 | debuggers that are specific to the target architecture. | ||
635 | </para> | ||
636 | |||
637 | <para>The Yocto Project supports two different cross-development | ||
638 | toolchains: | ||
639 | <itemizedlist> | ||
640 | <listitem><para>A toolchain only used by and within | ||
641 | BitBake when building an image for a target | ||
642 | architecture.</para></listitem> | ||
643 | <listitem><para>A relocatable toolchain used outside of | ||
644 | BitBake by developers when developing applications | ||
645 | that will run on a targeted device. | ||
646 | Sometimes this relocatable cross-development | ||
647 | toolchain is referred to as the meta-toolchain. | ||
648 | </para></listitem> | ||
649 | </itemizedlist> | ||
650 | </para> | ||
651 | |||
652 | <para> | ||
653 | Creation of these toolchains is simple and automated. | ||
654 | For information on toolchain concepts as they apply to the | ||
655 | Yocto Project, see the | ||
656 | "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" | ||
657 | section in the Yocto Project Reference Manual. | ||
658 | You can also find more information on using the | ||
659 | relocatable toolchain in the | ||
660 | <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project | ||
661 | Application Developer's Guide</ulink>. | ||
662 | </para></listitem> | ||
663 | <listitem><para><emphasis>Image:</emphasis> | ||
664 | An image is an artifact of the BitBake build process given | ||
665 | a collection of recipes and related Metadata. | ||
666 | Images are the binary output that run on specific hardware or | ||
667 | QEMU and are used for specific use-cases. | ||
668 | For a list of the supported image types that the Yocto Project provides, see the | ||
669 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
670 | chapter in the Yocto Project Reference Manual.</para></listitem> | ||
671 | <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, | ||
672 | a BSP, or an application stack. | ||
673 | For a discussion specifically on BSP Layers, see the | ||
674 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | ||
675 | section in the Yocto Project Board Support Packages (BSP) | ||
676 | Developer's Guide.</para></listitem> | ||
677 | <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis> | ||
678 | A term sometimes used for | ||
679 | <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>. | ||
680 | </para></listitem> | ||
681 | <listitem><para id='metadata'><emphasis>Metadata:</emphasis> | ||
682 | The files that BitBake parses when building an image. | ||
683 | In general, Metadata includes recipes, classes, and | ||
684 | configuration files. | ||
685 | In the context of the kernel ("kernel Metadata"), | ||
686 | it refers to Metadata in the <filename>meta</filename> | ||
687 | branches of the kernel source Git repositories. | ||
688 | </para></listitem> | ||
689 | <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating | ||
690 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project. | ||
691 | This Metadata is found in the <filename>meta</filename> directory of the | ||
692 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | ||
693 | <listitem><para><emphasis>Package:</emphasis> | ||
694 | In the context of the Yocto Project, this term refers to a | ||
695 | recipe's packaged output produced by BitBake (i.e. a | ||
696 | "baked recipe"). | ||
697 | A package is generally the compiled binaries produced from the | ||
698 | recipe's sources. | ||
699 | You "bake" something by running it through BitBake.</para> | ||
700 | <para>It is worth noting that the term "package" can, in general, have subtle | ||
701 | meanings. For example, the packages referred to in the | ||
702 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are | ||
703 | compiled binaries that, when installed, add functionality to your Linux | ||
704 | distribution.</para> | ||
705 | <para>Another point worth noting is that historically within the Yocto Project, | ||
706 | recipes were referred to as packages - thus, the existence of several BitBake | ||
707 | variables that are seemingly mis-named, | ||
708 | (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, | ||
709 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and | ||
710 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). | ||
711 | </para></listitem> | ||
712 | <listitem><para><emphasis>Package Groups:</emphasis> | ||
713 | Arbitrary groups of software Recipes. | ||
714 | You use package groups to hold recipes that, when built, | ||
715 | usually accomplish a single task. | ||
716 | For example, a package group could contain the recipes for a | ||
717 | company’s proprietary or value-add software. | ||
718 | Or, the package group could contain the recipes that enable | ||
719 | graphics. | ||
720 | A package group is really just another recipe. | ||
721 | Because package group files are recipes, they end with the | ||
722 | <filename>.bb</filename> filename extension.</para></listitem> | ||
723 | <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. | ||
724 | In its most general sense, it is an open-source project that was initially developed | ||
725 | by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded | ||
726 | build system becoming a build system for embedded images. | ||
727 | After Intel Corporation acquired OpenedHand, the project poky became the basis for | ||
728 | the Yocto Project's build system.</para> | ||
729 | <para> | ||
730 | Within the Yocto Project source repositories, <filename>poky</filename> | ||
731 | exists as a separate Git repository | ||
732 | that can be cloned to yield a local copy on the host system. | ||
733 | Thus, "poky" can refer to the local copy of the Source Directory used to develop within | ||
734 | the Yocto Project.</para></listitem> | ||
735 | <listitem><para><emphasis>Recipe:</emphasis> | ||
736 | A set of instructions for building packages. | ||
737 | A recipe describes where you get source code, which patches | ||
738 | to apply, how to configure the source, how to compile it and so on. | ||
739 | Recipes also describe dependencies for libraries or for other | ||
740 | recipes. | ||
741 | Recipes represent the logical unit of execution, the software | ||
742 | to build, the images to build, and use the | ||
743 | <filename>.bb</filename> file extension. | ||
744 | </para></listitem> | ||
745 | <listitem> | ||
746 | <para id='source-directory'><emphasis>Source Directory:</emphasis> | ||
747 | This term refers to the directory structure created as a result | ||
748 | of creating a local copy of the <filename>poky</filename> Git | ||
749 | repository <filename>git://git.yoctoproject.org/poky</filename> | ||
750 | or expanding a released <filename>poky</filename> tarball. | ||
751 | <note> | ||
752 | Creating a local copy of the <filename>poky</filename> | ||
753 | Git repository is the recommended method for setting up | ||
754 | your Source Directory. | ||
755 | </note> | ||
756 | Sometimes you might hear the term "poky directory" used to refer | ||
757 | to this directory structure. | ||
758 | <note> | ||
759 | The OpenEmbedded build system does not support file or | ||
760 | directory names that contain spaces. | ||
761 | Be sure that the Source Directory you use does not contain | ||
762 | these types of names. | ||
763 | </note></para> | ||
764 | |||
765 | <para>The Source Directory contains BitBake, Documentation, | ||
766 | Metadata and other files that all support the Yocto Project. | ||
767 | Consequently, you must have the Source Directory in place on | ||
768 | your development system in order to do any development using | ||
769 | the Yocto Project.</para> | ||
770 | |||
771 | <para>When you create a local copy of the Git repository, you | ||
772 | can name the repository anything you like. | ||
773 | Throughout much of the documentation, "poky" | ||
774 | is used as the name of the top-level folder of the local copy of | ||
775 | the poky Git repository. | ||
776 | So, for example, cloning the <filename>poky</filename> Git | ||
777 | repository results in a local Git repository whose top-level | ||
778 | folder is also named "poky".</para> | ||
779 | |||
780 | <para>While it is not recommended that you use tarball expansion | ||
781 | to set up the Source Directory, if you do, the top-level | ||
782 | directory name of the Source Directory is derived from the | ||
783 | Yocto Project release tarball. | ||
784 | For example, downloading and unpacking | ||
785 | <filename>&YOCTO_POKY_TARBALL;</filename> results in a | ||
786 | Source Directory whose root folder is named | ||
787 | <filename>&YOCTO_POKY;</filename>.</para> | ||
788 | |||
789 | <para>It is important to understand the differences between the | ||
790 | Source Directory created by unpacking a released tarball as | ||
791 | compared to cloning | ||
792 | <filename>git://git.yoctoproject.org/poky</filename>. | ||
793 | When you unpack a tarball, you have an exact copy of the files | ||
794 | based on the time of release - a fixed release point. | ||
795 | Any changes you make to your local files in the Source Directory | ||
796 | are on top of the release and will remain local only. | ||
797 | On the other hand, when you clone the <filename>poky</filename> | ||
798 | Git repository, you have an active development repository with | ||
799 | access to the upstream repository's branches and tags. | ||
800 | In this case, any local changes you make to the local | ||
801 | Source Directory can be later applied to active development | ||
802 | branches of the upstream <filename>poky</filename> Git | ||
803 | repository.</para> | ||
804 | |||
805 | <para>For more information on concepts related to Git | ||
806 | repositories, branches, and tags, see the | ||
807 | "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" | ||
808 | section.</para></listitem> | ||
809 | <listitem><para><emphasis>Task:</emphasis> | ||
810 | A unit of execution for BitBake (e.g. | ||
811 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>, | ||
812 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, | ||
813 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>, | ||
814 | and so forth). | ||
815 | </para></listitem> | ||
816 | <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories | ||
817 | that are not local to the development system but located in a master area that is controlled | ||
818 | by the maintainer of the source code. | ||
819 | For example, in order for a developer to work on a particular piece of code, they need to | ||
820 | first get a copy of it from an "upstream" source.</para></listitem> | ||
821 | </itemizedlist> | ||
822 | </para> | ||
823 | </section> | ||
824 | |||
825 | <section id='licensing'> | ||
826 | <title>Licensing</title> | ||
827 | |||
828 | <para> | ||
829 | Because open source projects are open to the public, they have different licensing structures in place. | ||
830 | License evolution for both Open Source and Free Software has an interesting history. | ||
831 | If you are interested in this history, you can find basic information here: | ||
832 | <itemizedlist> | ||
833 | <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> | ||
834 | </para></listitem> | ||
835 | <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license | ||
836 | history</ulink></para></listitem> | ||
837 | </itemizedlist> | ||
838 | </para> | ||
839 | |||
840 | <para> | ||
841 | In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology | ||
842 | (MIT) License. | ||
843 | MIT licensing permits the reuse of software within proprietary software as long as the | ||
844 | license is distributed with that software. | ||
845 | MIT is also compatible with the GNU General Public License (GPL). | ||
846 | Patches to the Yocto Project follow the upstream licensing scheme. | ||
847 | You can find information on the MIT license | ||
848 | <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. | ||
849 | You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'> | ||
850 | here</ulink>. | ||
851 | </para> | ||
852 | |||
853 | <para> | ||
854 | When you build an image using the Yocto Project, the build process uses a | ||
855 | known list of licenses to ensure compliance. | ||
856 | You can find this list in the | ||
857 | <link linkend='source-directory'>Source Directory</link> at | ||
858 | <filename>meta/files/common-licenses</filename>. | ||
859 | Once the build completes, the list of all licenses found and used during that build are | ||
860 | kept in the | ||
861 | <link linkend='build-directory'>Build Directory</link> at | ||
862 | <filename>tmp/deploy/licenses</filename>. | ||
863 | </para> | ||
864 | |||
865 | <para> | ||
866 | If a module requires a license that is not in the base list, the build process | ||
867 | generates a warning during the build. | ||
868 | These tools make it easier for a developer to be certain of the licenses with which | ||
869 | their shipped products must comply. | ||
870 | However, even with these tools it is still up to the developer to resolve potential licensing issues. | ||
871 | </para> | ||
872 | |||
873 | <para> | ||
874 | The base list of licenses used by the build process is a combination of the Software Package | ||
875 | Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. | ||
876 | <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation | ||
877 | that maintains a specification | ||
878 | for a standard format for communicating the components, licenses, and copyrights | ||
879 | associated with a software package. | ||
880 | <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source | ||
881 | Definition and the effort for reviewing and approving licenses that | ||
882 | conform to the Open Source Definition (OSD). | ||
883 | </para> | ||
884 | |||
885 | <para> | ||
886 | You can find a list of the combined SPDX and OSI licenses that the | ||
887 | Yocto Project uses in the | ||
888 | <filename>meta/files/common-licenses</filename> directory in your | ||
889 | <link linkend='source-directory'>Source Directory</link>. | ||
890 | </para> | ||
891 | |||
892 | <para> | ||
893 | For information that can help you maintain compliance with various | ||
894 | open source licensing during the lifecycle of a product created using | ||
895 | the Yocto Project, see the | ||
896 | "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" | ||
897 | section. | ||
898 | </para> | ||
899 | </section> | ||
900 | |||
901 | <section id='git'> | ||
902 | <title>Git</title> | ||
903 | |||
904 | <para> | ||
905 | The Yocto Project makes extensive use of Git, | ||
906 | which is a free, open source distributed version control system. | ||
907 | Git supports distributed development, non-linear development, and can handle large projects. | ||
908 | It is best that you have some fundamental understanding of how Git tracks projects and | ||
909 | how to work with Git if you are going to use the Yocto Project for development. | ||
910 | This section provides a quick overview of how Git works and provides you with a summary | ||
911 | of some essential Git commands. | ||
912 | </para> | ||
913 | |||
914 | <para> | ||
915 | For more information on Git, see | ||
916 | <ulink url='http://git-scm.com/documentation'></ulink>. | ||
917 | If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>. | ||
918 | </para> | ||
919 | |||
920 | <section id='repositories-tags-and-branches'> | ||
921 | <title>Repositories, Tags, and Branches</title> | ||
922 | |||
923 | <para> | ||
924 | As mentioned earlier in the section | ||
925 | "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>", | ||
926 | the Yocto Project maintains source repositories at | ||
927 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. | ||
928 | If you look at this web-interface of the repositories, each item is a separate | ||
929 | Git repository. | ||
930 | </para> | ||
931 | |||
932 | <para> | ||
933 | Git repositories use branching techniques that track content change (not files) | ||
934 | within a project (e.g. a new feature or updated documentation). | ||
935 | Creating a tree-like structure based on project divergence allows for excellent historical | ||
936 | information over the life of a project. | ||
937 | This methodology also allows for an environment from which you can do lots of | ||
938 | local experimentation on projects as you develop changes or new features. | ||
939 | </para> | ||
940 | |||
941 | <para> | ||
942 | A Git repository represents all development efforts for a given project. | ||
943 | For example, the Git repository <filename>poky</filename> contains all changes | ||
944 | and developments for Poky over the course of its entire life. | ||
945 | That means that all changes that make up all releases are captured. | ||
946 | The repository maintains a complete history of changes. | ||
947 | </para> | ||
948 | |||
949 | <para> | ||
950 | You can create a local copy of any repository by "cloning" it with the Git | ||
951 | <filename>clone</filename> command. | ||
952 | When you clone a Git repository, you end up with an identical copy of the | ||
953 | repository on your development system. | ||
954 | Once you have a local copy of a repository, you can take steps to develop locally. | ||
955 | For examples on how to clone Git repositories, see the | ||
956 | "<link linkend='getting-setup'>Getting Set Up</link>" section. | ||
957 | </para> | ||
958 | |||
959 | <para> | ||
960 | It is important to understand that Git tracks content change and | ||
961 | not files. | ||
962 | Git uses "branches" to organize different development efforts. | ||
963 | For example, the <filename>poky</filename> repository has | ||
964 | <filename>denzil</filename>, <filename>danny</filename>, | ||
965 | <filename>dylan</filename>, <filename>dora</filename>, | ||
966 | <filename>daisy</filename>, and <filename>master</filename> branches | ||
967 | among others. | ||
968 | You can see all the branches by going to | ||
969 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | ||
970 | clicking on the | ||
971 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> | ||
972 | link beneath the "Branch" heading. | ||
973 | </para> | ||
974 | |||
975 | <para> | ||
976 | Each of these branches represents a specific area of development. | ||
977 | The <filename>master</filename> branch represents the current or most recent | ||
978 | development. | ||
979 | All other branches represent offshoots of the <filename>master</filename> | ||
980 | branch. | ||
981 | </para> | ||
982 | |||
983 | <para> | ||
984 | When you create a local copy of a Git repository, the copy has the same set | ||
985 | of branches as the original. | ||
986 | This means you can use Git to create a local working area (also called a branch) | ||
987 | that tracks a specific development branch from the source Git repository. | ||
988 | in other words, you can define your local Git environment to work on any development | ||
989 | branch in the repository. | ||
990 | To help illustrate, here is a set of commands that creates a local copy of the | ||
991 | <filename>poky</filename> Git repository and then creates and checks out a local | ||
992 | Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: | ||
993 | <literallayout class='monospaced'> | ||
994 | $ cd ~ | ||
995 | $ git clone git://git.yoctoproject.org/poky | ||
996 | $ cd poky | ||
997 | $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; | ||
998 | </literallayout> | ||
999 | In this example, the name of the top-level directory of your local | ||
1000 | <link linkend='source-directory'>Source Directory</link> | ||
1001 | is "poky" and the name of that local working area (local branch) | ||
1002 | you just created and checked out is "&DISTRO_NAME;". | ||
1003 | The files in your local repository now reflect the same files that | ||
1004 | are in the "&DISTRO_NAME;" development branch of the | ||
1005 | Yocto Project's "poky" upstream repository. | ||
1006 | It is important to understand that when you create and checkout a | ||
1007 | local working branch based on a branch name, | ||
1008 | your local environment matches the "tip" of that development branch | ||
1009 | at the time you created your local branch, which could be | ||
1010 | different from the files at the time of a similarly named release. | ||
1011 | In other words, creating and checking out a local branch based on | ||
1012 | the "&DISTRO_NAME;" branch name is not the same as | ||
1013 | cloning and checking out the "master" branch. | ||
1014 | Keep reading to see how you create a local snapshot of a Yocto | ||
1015 | Project Release. | ||
1016 | </para> | ||
1017 | |||
1018 | <para> | ||
1019 | Git uses "tags" to mark specific changes in a repository. | ||
1020 | Typically, a tag is used to mark a special point such as the final | ||
1021 | change before a project is released. | ||
1022 | You can see the tags used with the <filename>poky</filename> Git | ||
1023 | repository by going to | ||
1024 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and | ||
1025 | clicking on the | ||
1026 | <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> | ||
1027 | link beneath the "Tag" heading. | ||
1028 | </para> | ||
1029 | |||
1030 | <para> | ||
1031 | Some key tags are <filename>dylan-9.0.0</filename>, | ||
1032 | <filename>dora-10.0.0</filename>, <filename>daisy-11.0.0</filename>, | ||
1033 | and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. | ||
1034 | These tags represent Yocto Project releases. | ||
1035 | </para> | ||
1036 | |||
1037 | <para> | ||
1038 | When you create a local copy of the Git repository, you also have access to all the | ||
1039 | tags. | ||
1040 | Similar to branches, you can create and checkout a local working Git branch based | ||
1041 | on a tag name. | ||
1042 | When you do this, you get a snapshot of the Git repository that reflects | ||
1043 | the state of the files when the change was made associated with that tag. | ||
1044 | The most common use is to checkout a working branch that matches a specific | ||
1045 | Yocto Project release. | ||
1046 | Here is an example: | ||
1047 | <literallayout class='monospaced'> | ||
1048 | $ cd ~ | ||
1049 | $ git clone git://git.yoctoproject.org/poky | ||
1050 | $ cd poky | ||
1051 | $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; | ||
1052 | </literallayout> | ||
1053 | In this example, the name of the top-level directory of your local Yocto Project | ||
1054 | Files Git repository is <filename>poky</filename>. | ||
1055 | And, the name of the local branch you have created and checked out is | ||
1056 | <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>. | ||
1057 | The files in your repository now exactly match the Yocto Project &DISTRO; | ||
1058 | Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>). | ||
1059 | It is important to understand that when you create and checkout a local | ||
1060 | working branch based on a tag, your environment matches a specific point | ||
1061 | in time and not the entire development branch. | ||
1062 | </para> | ||
1063 | </section> | ||
1064 | |||
1065 | <section id='basic-commands'> | ||
1066 | <title>Basic Commands</title> | ||
1067 | |||
1068 | <para> | ||
1069 | Git has an extensive set of commands that lets you manage changes and perform | ||
1070 | collaboration over the life of a project. | ||
1071 | Conveniently though, you can manage with a small set of basic operations and workflows | ||
1072 | once you understand the basic philosophy behind Git. | ||
1073 | You do not have to be an expert in Git to be functional. | ||
1074 | A good place to look for instruction on a minimal set of Git commands is | ||
1075 | <ulink url='http://git-scm.com/documentation'>here</ulink>. | ||
1076 | If you need to download Git, you can do so | ||
1077 | <ulink url='http://git-scm.com/download'>here</ulink>. | ||
1078 | </para> | ||
1079 | |||
1080 | <para> | ||
1081 | If you do not know much about Git, you should educate | ||
1082 | yourself by visiting the links previously mentioned. | ||
1083 | </para> | ||
1084 | |||
1085 | <para> | ||
1086 | The following list briefly describes some basic Git operations as a way to get started. | ||
1087 | As with any set of commands, this list (in most cases) simply shows the base command and | ||
1088 | omits the many arguments they support. | ||
1089 | See the Git documentation for complete descriptions and strategies on how to use these commands: | ||
1090 | <itemizedlist> | ||
1091 | <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. | ||
1092 | You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> | ||
1093 | <listitem><para><emphasis><filename>git clone</filename>:</emphasis> | ||
1094 | Creates a local clone of a Git repository. | ||
1095 | During collaboration, this command allows you to create a | ||
1096 | local Git repository that is on equal footing with a fellow | ||
1097 | developer’s Git repository. | ||
1098 | </para></listitem> | ||
1099 | <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents | ||
1100 | to the index that | ||
1101 | Git uses to track changes. | ||
1102 | You must stage all files that have changed before you can commit them.</para></listitem> | ||
1103 | <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents | ||
1104 | the changes you made. | ||
1105 | Commits are used for historical purposes, for determining if a maintainer of a project | ||
1106 | will allow the change, and for ultimately pushing the change from your local Git repository | ||
1107 | into the project’s upstream (or master) repository.</para></listitem> | ||
1108 | <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that | ||
1109 | possibly need to be staged and committed.</para></listitem> | ||
1110 | <listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes | ||
1111 | your working branch. | ||
1112 | This command is analogous to "cd".</para></listitem> | ||
1113 | <listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates | ||
1114 | a working branch on your local machine where you can isolate work. | ||
1115 | It is a good idea to use local branches when adding specific features or changes. | ||
1116 | This way if you do not like what you have done you can easily get rid of the work.</para></listitem> | ||
1117 | <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports | ||
1118 | existing local branches and | ||
1119 | tells you the branch in which you are currently working.</para></listitem> | ||
1120 | <listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis> | ||
1121 | Deletes an existing local branch. | ||
1122 | You need to be in a local branch other than the one you are deleting | ||
1123 | in order to delete <filename><branch-name></filename>.</para></listitem> | ||
1124 | <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information | ||
1125 | from an upstream Git | ||
1126 | repository and places it in your local Git repository. | ||
1127 | You use this command to make sure you are synchronized with the repository | ||
1128 | from which you are basing changes (.e.g. the master branch).</para></listitem> | ||
1129 | <listitem><para><emphasis><filename>git push</filename>:</emphasis> | ||
1130 | Sends all your committed local changes to an upstream Git | ||
1131 | repository (e.g. a contribution repository). | ||
1132 | The maintainer of the project draws from these repositories | ||
1133 | when adding changes to the project’s master repository or | ||
1134 | other development branch. | ||
1135 | </para></listitem> | ||
1136 | <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one | ||
1137 | local branch of your repository with another branch. | ||
1138 | When you create a local Git repository, the default branch is named "master". | ||
1139 | A typical workflow is to create a temporary branch for isolated work, make and commit your | ||
1140 | changes, switch to your local master branch, merge the changes from the temporary branch into the | ||
1141 | local master branch, and then delete the temporary branch.</para></listitem> | ||
1142 | <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific | ||
1143 | commits from one branch into another branch. | ||
1144 | There are times when you might not be able to merge all the changes in one branch with | ||
1145 | another but need to pick out certain ones.</para></listitem> | ||
1146 | <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches | ||
1147 | and changes in your local Git repository. | ||
1148 | This command is a good way to graphically see where things have diverged in your | ||
1149 | local repository.</para></listitem> | ||
1150 | <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the | ||
1151 | repository.</para></listitem> | ||
1152 | <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences | ||
1153 | between your local working files and the same files in the upstream Git repository that your | ||
1154 | branch currently tracks.</para></listitem> | ||
1155 | </itemizedlist> | ||
1156 | </para> | ||
1157 | </section> | ||
1158 | </section> | ||
1159 | |||
1160 | <section id='workflows'> | ||
1161 | <title>Workflows</title> | ||
1162 | |||
1163 | <para> | ||
1164 | This section provides some overview on workflows using Git. | ||
1165 | In particular, the information covers basic practices that describe roles and actions in a | ||
1166 | collaborative development environment. | ||
1167 | Again, if you are familiar with this type of development environment, you might want to just | ||
1168 | skip this section. | ||
1169 | </para> | ||
1170 | |||
1171 | <para> | ||
1172 | The Yocto Project files are maintained using Git in a "master" branch whose Git history | ||
1173 | tracks every change and whose structure provides branches for all diverging functionality. | ||
1174 | Although there is no need to use Git, many open source projects do so. | ||
1175 | For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" | ||
1176 | branch of a given Git repository. | ||
1177 | The "master" branch is the “upstream” repository where the final builds of the project occur. | ||
1178 | The maintainer is responsible for accepting changes from other developers and for | ||
1179 | organizing the underlying branch structure to reflect release strategies and so forth. | ||
1180 | <note>For information on finding out who is responsible for (maintains) | ||
1181 | a particular area of code, see the | ||
1182 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
1183 | section. | ||
1184 | </note> | ||
1185 | </para> | ||
1186 | |||
1187 | <para> | ||
1188 | The project also has an upstream contribution Git repository named | ||
1189 | <filename>poky-contrib</filename>. | ||
1190 | You can see all the branches in this repository using the web interface | ||
1191 | of the | ||
1192 | <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized | ||
1193 | within the "Poky Support" area. | ||
1194 | These branches temporarily hold changes to the project that have been | ||
1195 | submitted or committed by the Yocto Project development team and by | ||
1196 | community members who contribute to the project. | ||
1197 | The maintainer determines if the changes are qualified to be moved | ||
1198 | from the "contrib" branches into the "master" branch of the Git | ||
1199 | repository. | ||
1200 | </para> | ||
1201 | |||
1202 | <para> | ||
1203 | Developers (including contributing community members) create and maintain cloned repositories | ||
1204 | of the upstream "master" branch. | ||
1205 | These repositories are local to their development platforms and are used to develop changes. | ||
1206 | When a developer is satisfied with a particular feature or change, they "push" the changes | ||
1207 | to the appropriate "contrib" repository. | ||
1208 | </para> | ||
1209 | |||
1210 | <para> | ||
1211 | Developers are responsible for keeping their local repository up-to-date with "master". | ||
1212 | They are also responsible for straightening out any conflicts that might arise within files | ||
1213 | that are being worked on simultaneously by more than one person. | ||
1214 | All this work is done locally on the developer’s machines before anything is pushed to a | ||
1215 | "contrib" area and examined at the maintainer’s level. | ||
1216 | </para> | ||
1217 | |||
1218 | <para> | ||
1219 | A somewhat formal method exists by which developers commit changes and push them into the | ||
1220 | "contrib" area and subsequently request that the maintainer include them into "master" | ||
1221 | This process is called “submitting a patch” or "submitting a change." | ||
1222 | For information on submitting patches and changes, see the | ||
1223 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section. | ||
1224 | </para> | ||
1225 | |||
1226 | <para> | ||
1227 | To summarize the environment: a single point of entry exists for | ||
1228 | changes into the project’s "master" branch of the Git repository, | ||
1229 | which is controlled by the project’s maintainer. | ||
1230 | And, a set of developers exist who independently develop, test, and | ||
1231 | submit changes to "contrib" areas for the maintainer to examine. | ||
1232 | The maintainer then chooses which changes are going to become a | ||
1233 | permanent part of the project. | ||
1234 | </para> | ||
1235 | |||
1236 | <para> | ||
1237 | <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> | ||
1238 | </para> | ||
1239 | |||
1240 | <para> | ||
1241 | While each development environment is unique, there are some best practices or methods | ||
1242 | that help development run smoothly. | ||
1243 | The following list describes some of these practices. | ||
1244 | For more information about Git workflows, see the workflow topics in the | ||
1245 | <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. | ||
1246 | <itemizedlist> | ||
1247 | <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit | ||
1248 | small as compared to bundling many disparate changes into a single commit. | ||
1249 | This practice not only keeps things manageable but also allows the maintainer | ||
1250 | to more easily include or refuse changes.</para> | ||
1251 | <para>It is also good practice to leave the repository in a state that allows you to | ||
1252 | still successfully build your project. In other words, do not commit half of a feature, | ||
1253 | then add the other half as a separate, later commit. | ||
1254 | Each commit should take you from one buildable project state to another | ||
1255 | buildable state.</para></listitem> | ||
1256 | <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and | ||
1257 | delete local branches in your working Git repository. | ||
1258 | You can name these branches anything you like. | ||
1259 | It is helpful to give them names associated with the particular feature or change | ||
1260 | on which you are working. | ||
1261 | Once you are done with a feature or change and have merged it | ||
1262 | into your local master branch, simply discard the temporary | ||
1263 | branch.</para></listitem> | ||
1264 | <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename> | ||
1265 | command allows you to take the | ||
1266 | changes from one branch and fold them into another branch. | ||
1267 | This process is especially helpful when more than a single developer might be working | ||
1268 | on different parts of the same feature. | ||
1269 | Merging changes also automatically identifies any collisions or "conflicts" | ||
1270 | that might happen as a result of the same lines of code being altered by two different | ||
1271 | developers.</para></listitem> | ||
1272 | <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should | ||
1273 | use a system where branches indicate varying levels of code readiness. | ||
1274 | For example, you can have a "work" branch to develop in, a "test" branch where the code or | ||
1275 | change is tested, a "stage" branch where changes are ready to be committed, and so forth. | ||
1276 | As your project develops, you can merge code across the branches to reflect ever-increasing | ||
1277 | stable states of the development.</para></listitem> | ||
1278 | <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the | ||
1279 | concept of developers "pushing" local commits to a remote repository, which is | ||
1280 | usually a contribution repository. | ||
1281 | This workflow is also based on developers "pulling" known states of the project down into their | ||
1282 | local development repositories. | ||
1283 | The workflow easily allows you to pull changes submitted by other developers from the | ||
1284 | upstream repository into your work area ensuring that you have the most recent software | ||
1285 | on which to develop. | ||
1286 | The Yocto Project has two scripts named <filename>create-pull-request</filename> and | ||
1287 | <filename>send-pull-request</filename> that ship with the release to facilitate this | ||
1288 | workflow. | ||
1289 | You can find these scripts in the <filename>scripts</filename> | ||
1290 | folder of the | ||
1291 | <link linkend='source-directory'>Source Directory</link>. | ||
1292 | For information on how to use these scripts, see the | ||
1293 | "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section. | ||
1294 | </para></listitem> | ||
1295 | <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the | ||
1296 | maintainer through an email that you have a change (or patch) you would like considered | ||
1297 | for the "master" branch of the Git repository. | ||
1298 | To send this type of change, you format the patch and then send the email using the Git commands | ||
1299 | <filename>git format-patch</filename> and <filename>git send-email</filename>. | ||
1300 | For information on how to use these scripts, see the | ||
1301 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
1302 | section. | ||
1303 | </para></listitem> | ||
1304 | </itemizedlist> | ||
1305 | </para> | ||
1306 | </section> | ||
1307 | |||
1308 | <section id='tracking-bugs'> | ||
1309 | <title>Tracking Bugs</title> | ||
1310 | |||
1311 | <para> | ||
1312 | The Yocto Project uses its own implementation of | ||
1313 | <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs. | ||
1314 | Implementations of Bugzilla work well for group development because they track bugs and code | ||
1315 | changes, can be used to communicate changes and problems with developers, can be used to | ||
1316 | submit and review patches, and can be used to manage quality assurance. | ||
1317 | The home page for the Yocto Project implementation of Bugzilla is | ||
1318 | <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>. | ||
1319 | </para> | ||
1320 | |||
1321 | <para> | ||
1322 | Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself | ||
1323 | such as when discovering an issue with some component of the build system that acts contrary | ||
1324 | to the documentation or your expectations. | ||
1325 | Following is the general procedure for submitting a new bug using the Yocto Project | ||
1326 | Bugzilla. | ||
1327 | You can find more information on defect management, bug tracking, and feature request | ||
1328 | processes all accomplished through the Yocto Project Bugzilla on the wiki page | ||
1329 | <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. | ||
1330 | <orderedlist> | ||
1331 | <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit | ||
1332 | a bug.</para></listitem> | ||
1333 | <listitem><para>When submitting a new bug, be sure to choose the appropriate | ||
1334 | Classification, Product, and Component for which the issue was found. | ||
1335 | Defects for the Yocto Project fall into one of seven classifications: | ||
1336 | Yocto Project Components, Infrastructure, Build System & Metadata, | ||
1337 | Documentation, QA/Testing, Runtime and Hardware. | ||
1338 | Each of these Classifications break down into multiple Products and, in some | ||
1339 | cases, multiple Components.</para></listitem> | ||
1340 | <listitem><para>Use the bug form to choose the correct Hardware and Architecture | ||
1341 | for which the bug applies.</para></listitem> | ||
1342 | <listitem><para>Indicate the Yocto Project version you were using when the issue | ||
1343 | occurred.</para></listitem> | ||
1344 | <listitem><para>Be sure to indicate the Severity of the bug. | ||
1345 | Severity communicates how the bug impacted your work.</para></listitem> | ||
1346 | <listitem><para>Select the appropriate "Documentation change" item | ||
1347 | for the bug. | ||
1348 | Fixing a bug may or may not affect the Yocto Project | ||
1349 | documentation.</para></listitem> | ||
1350 | <listitem><para>Provide a brief summary of the issue. | ||
1351 | Try to limit your summary to just a line or two and be sure to capture the | ||
1352 | essence of the issue.</para></listitem> | ||
1353 | <listitem><para>Provide a detailed description of the issue. | ||
1354 | You should provide as much detail as you can about the context, behavior, output, | ||
1355 | and so forth that surrounds the issue. | ||
1356 | You can even attach supporting files for output from logs by | ||
1357 | using the "Add an attachment" button.</para></listitem> | ||
1358 | <listitem><para>Be sure to copy the appropriate people in the | ||
1359 | "CC List" for the bug. | ||
1360 | See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
1361 | section for information about finding out who is responsible | ||
1362 | for code.</para></listitem> | ||
1363 | <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> | ||
1364 | </orderedlist> | ||
1365 | </para> | ||
1366 | </section> | ||
1367 | |||
1368 | <section id='how-to-submit-a-change'> | ||
1369 | <title>How to Submit a Change</title> | ||
1370 | |||
1371 | <para> | ||
1372 | Contributions to the Yocto Project and OpenEmbedded are very welcome. | ||
1373 | Because the system is extremely configurable and flexible, we recognize that developers | ||
1374 | will want to extend, configure or optimize it for their specific uses. | ||
1375 | You should send patches to the appropriate mailing list so that they | ||
1376 | can be reviewed and merged by the appropriate maintainer. | ||
1377 | </para> | ||
1378 | |||
1379 | <para> | ||
1380 | Before submitting any change, be sure to find out who you should be | ||
1381 | notifying. | ||
1382 | Several methods exist through which you find out who you should be copying | ||
1383 | or notifying: | ||
1384 | <itemizedlist> | ||
1385 | <listitem><para><emphasis>Maintenance File:</emphasis> | ||
1386 | Examine the <filename>maintainers.inc</filename> file, which is | ||
1387 | located in the | ||
1388 | <link linkend='source-directory'>Source Directory</link> | ||
1389 | at <filename>meta-yocto/conf/distro/include</filename>, to | ||
1390 | see who is responsible for code. | ||
1391 | </para></listitem> | ||
1392 | <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis> | ||
1393 | For BSP maintainers of supported BSPs, you can examine | ||
1394 | individual BSP <filename>README</filename> files. | ||
1395 | In addition, some layers (such as the <filename>meta-intel</filename> layer), | ||
1396 | include a <filename>MAINTAINERS</filename> file which contains | ||
1397 | a list of all supported BSP maintainers for that layer. | ||
1398 | </para></listitem> | ||
1399 | <listitem><para><emphasis>Search by File:</emphasis> | ||
1400 | Using <link linkend='git'>Git</link>, you can enter the | ||
1401 | following command to bring up a short list of all commits | ||
1402 | against a specific file: | ||
1403 | <literallayout class='monospaced'> | ||
1404 | git shortlog -- <replaceable>filename</replaceable> | ||
1405 | </literallayout> | ||
1406 | Just provide the name of the file for which you are interested. | ||
1407 | The information returned is not ordered by history but does | ||
1408 | include a list of all committers grouped by name. | ||
1409 | From the list, you can see who is responsible for the bulk of | ||
1410 | the changes against the file. | ||
1411 | </para></listitem> | ||
1412 | </itemizedlist> | ||
1413 | </para> | ||
1414 | |||
1415 | <para> | ||
1416 | For a list of the Yocto Project and related mailing lists, see the | ||
1417 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in | ||
1418 | the Yocto Project Reference Manual. | ||
1419 | </para> | ||
1420 | |||
1421 | <para> | ||
1422 | Here is some guidance on which mailing list to use for what type of change: | ||
1423 | <itemizedlist> | ||
1424 | <listitem><para>For changes to the core | ||
1425 | <link linkend='metadata'>Metadata</link>, send your patch to the | ||
1426 | <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. | ||
1427 | For example, a change to anything under the <filename>meta</filename> or | ||
1428 | <filename>scripts</filename> directories | ||
1429 | should be sent to this mailing list.</para></listitem> | ||
1430 | <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> | ||
1431 | directory), send your patch to the | ||
1432 | <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> | ||
1433 | <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the | ||
1434 | <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> | ||
1435 | <listitem><para>For changes to other layers hosted on | ||
1436 | <filename>yoctoproject.org</filename> (unless the | ||
1437 | layer's documentation specifies otherwise), tools, and Yocto Project | ||
1438 | documentation, use the | ||
1439 | <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem> | ||
1440 | <listitem><para>For additional recipes that do not fit into the core Metadata, | ||
1441 | you should determine which layer the recipe should go into and submit the | ||
1442 | change in the manner recommended by the documentation (e.g. README) supplied | ||
1443 | with the layer. If in doubt, please ask on the | ||
1444 | <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or | ||
1445 | <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> | ||
1446 | mailing lists.</para></listitem> | ||
1447 | </itemizedlist> | ||
1448 | </para> | ||
1449 | |||
1450 | <para> | ||
1451 | When you send a patch, be sure to include a "Signed-off-by:" | ||
1452 | line in the same style as required by the Linux kernel. | ||
1453 | Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 | ||
1454 | as follows: | ||
1455 | <literallayout class='monospaced'> | ||
1456 | Developer's Certificate of Origin 1.1 | ||
1457 | |||
1458 | By making a contribution to this project, I certify that: | ||
1459 | |||
1460 | (a) The contribution was created in whole or in part by me and I | ||
1461 | have the right to submit it under the open source license | ||
1462 | indicated in the file; or | ||
1463 | |||
1464 | (b) The contribution is based upon previous work that, to the best | ||
1465 | of my knowledge, is covered under an appropriate open source | ||
1466 | license and I have the right under that license to submit that | ||
1467 | work with modifications, whether created in whole or in part | ||
1468 | by me, under the same open source license (unless I am | ||
1469 | permitted to submit under a different license), as indicated | ||
1470 | in the file; or | ||
1471 | |||
1472 | (c) The contribution was provided directly to me by some other | ||
1473 | person who certified (a), (b) or (c) and I have not modified | ||
1474 | it. | ||
1475 | |||
1476 | (d) I understand and agree that this project and the contribution | ||
1477 | are public and that a record of the contribution (including all | ||
1478 | personal information I submit with it, including my sign-off) is | ||
1479 | maintained indefinitely and may be redistributed consistent with | ||
1480 | this project or the open source license(s) involved. | ||
1481 | </literallayout> | ||
1482 | </para> | ||
1483 | |||
1484 | <para> | ||
1485 | In a collaborative environment, it is necessary to have some sort of standard | ||
1486 | or method through which you submit changes. | ||
1487 | Otherwise, things could get quite chaotic. | ||
1488 | One general practice to follow is to make small, controlled changes. | ||
1489 | Keeping changes small and isolated aids review, makes merging/rebasing easier | ||
1490 | and keeps the change history clean when anyone needs to refer to it in future. | ||
1491 | </para> | ||
1492 | |||
1493 | <para> | ||
1494 | When you make a commit, you must follow certain standards established by the | ||
1495 | OpenEmbedded and Yocto Project development teams. | ||
1496 | For each commit, you must provide a single-line summary of the change and you | ||
1497 | should almost always provide a more detailed description of what you did (i.e. | ||
1498 | the body of the commit message). | ||
1499 | The only exceptions for not providing a detailed description would be if your | ||
1500 | change is a simple, self-explanatory change that needs no further description | ||
1501 | beyond the summary. | ||
1502 | Here are the guidelines for composing a commit message: | ||
1503 | <itemizedlist> | ||
1504 | <listitem><para>Provide a single-line, short summary of the change. | ||
1505 | This summary is typically viewable in the "shortlist" of changes. | ||
1506 | Thus, providing something short and descriptive that gives the reader | ||
1507 | a summary of the change is useful when viewing a list of many commits. | ||
1508 | This short description should be prefixed by the recipe name (if changing a recipe), or | ||
1509 | else the short form path to the file being changed. | ||
1510 | </para></listitem> | ||
1511 | <listitem><para>For the body of the commit message, provide detailed information | ||
1512 | that describes what you changed, why you made the change, and the approach | ||
1513 | you used. It may also be helpful if you mention how you tested the change. | ||
1514 | Provide as much detail as you can in the body of the commit message. | ||
1515 | </para></listitem> | ||
1516 | <listitem><para> | ||
1517 | If the change addresses a specific bug or issue that is | ||
1518 | associated with a bug-tracking ID, include a reference to that | ||
1519 | ID in your detailed description. | ||
1520 | For example, the Yocto Project uses a specific convention for | ||
1521 | bug references - any commit that addresses a specific bug should | ||
1522 | use the following form for the detailed description: | ||
1523 | <literallayout class='monospaced'> | ||
1524 | Fixes [YOCTO #<replaceable>bug-id</replaceable>] | ||
1525 | |||
1526 | <replaceable>detailed description of change</replaceable> | ||
1527 | </literallayout></para></listitem> | ||
1528 | Where <replaceable>bug-id</replaceable> is replaced with the | ||
1529 | specific bug ID from the Yocto Project Bugzilla instance. | ||
1530 | </itemizedlist> | ||
1531 | </para> | ||
1532 | |||
1533 | <para> | ||
1534 | You can find more guidance on creating well-formed commit messages at this OpenEmbedded | ||
1535 | wiki page: | ||
1536 | <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. | ||
1537 | </para> | ||
1538 | |||
1539 | <para> | ||
1540 | The next two sections describe general instructions for both pushing | ||
1541 | changes upstream and for submitting changes as patches. | ||
1542 | </para> | ||
1543 | |||
1544 | <section id='pushing-a-change-upstream'> | ||
1545 | <title>Using Scripts to Push a Change Upstream and Request a Pull</title> | ||
1546 | |||
1547 | <para> | ||
1548 | The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: | ||
1549 | <itemizedlist> | ||
1550 | <listitem><para>Make your changes in your local Git repository.</para></listitem> | ||
1551 | <listitem><para>Stage your changes by using the <filename>git add</filename> | ||
1552 | command on each file you changed.</para></listitem> | ||
1553 | <listitem><para> | ||
1554 | Commit the change by using the | ||
1555 | <filename>git commit</filename> command. | ||
1556 | Be sure to provide a commit message that follows the | ||
1557 | project’s commit message standards as described earlier. | ||
1558 | </para></listitem> | ||
1559 | <listitem><para> | ||
1560 | Push the change to the upstream "contrib" repository by | ||
1561 | using the <filename>git push</filename> command. | ||
1562 | </para></listitem> | ||
1563 | <listitem><para>Notify the maintainer that you have pushed a change by making a pull | ||
1564 | request. | ||
1565 | The Yocto Project provides two scripts that conveniently let you generate and send | ||
1566 | pull requests to the Yocto Project. | ||
1567 | These scripts are <filename>create-pull-request</filename> and | ||
1568 | <filename>send-pull-request</filename>. | ||
1569 | You can find these scripts in the <filename>scripts</filename> directory | ||
1570 | within the <link linkend='source-directory'>Source Directory</link>.</para> | ||
1571 | <para>Using these scripts correctly formats the requests without introducing any | ||
1572 | whitespace or HTML formatting. | ||
1573 | The maintainer that receives your patches needs to be able to save and apply them | ||
1574 | directly from your emails. | ||
1575 | Using these scripts is the preferred method for sending patches.</para> | ||
1576 | <para>For help on using these scripts, simply provide the | ||
1577 | <filename>-h</filename> argument as follows: | ||
1578 | <literallayout class='monospaced'> | ||
1579 | $ poky/scripts/create-pull-request -h | ||
1580 | $ poky/scripts/send-pull-request -h | ||
1581 | </literallayout></para></listitem> | ||
1582 | </itemizedlist> | ||
1583 | </para> | ||
1584 | |||
1585 | <para> | ||
1586 | You can find general Git information on how to push a change upstream in the | ||
1587 | <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>. | ||
1588 | </para> | ||
1589 | </section> | ||
1590 | |||
1591 | <section id='submitting-a-patch'> | ||
1592 | <title>Using Email to Submit a Patch</title> | ||
1593 | |||
1594 | <para> | ||
1595 | You can submit patches without using the <filename>create-pull-request</filename> and | ||
1596 | <filename>send-pull-request</filename> scripts described in the previous section. | ||
1597 | However, keep in mind, the preferred method is to use the scripts. | ||
1598 | </para> | ||
1599 | |||
1600 | <para> | ||
1601 | Depending on the components changed, you need to submit the email to a specific | ||
1602 | mailing list. | ||
1603 | For some guidance on which mailing list to use, see the list in the | ||
1604 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
1605 | section. | ||
1606 | For a description of the available mailing lists, see the | ||
1607 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" | ||
1608 | section in the Yocto Project Reference Manual. | ||
1609 | </para> | ||
1610 | |||
1611 | <para> | ||
1612 | Here is the general procedure on how to submit a patch through email without using the | ||
1613 | scripts: | ||
1614 | <itemizedlist> | ||
1615 | <listitem><para>Make your changes in your local Git repository.</para></listitem> | ||
1616 | <listitem><para>Stage your changes by using the <filename>git add</filename> | ||
1617 | command on each file you changed.</para></listitem> | ||
1618 | <listitem><para>Commit the change by using the | ||
1619 | <filename>git commit --signoff</filename> command. | ||
1620 | Using the <filename>--signoff</filename> option identifies you as the person | ||
1621 | making the change and also satisfies the Developer's Certificate of | ||
1622 | Origin (DCO) shown earlier.</para> | ||
1623 | <para>When you form a commit, you must follow certain standards established by the | ||
1624 | Yocto Project development team. | ||
1625 | See the earlier section | ||
1626 | "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" | ||
1627 | for Yocto Project commit message standards.</para></listitem> | ||
1628 | <listitem><para>Format the commit into an email message. | ||
1629 | To format commits, use the <filename>git format-patch</filename> command. | ||
1630 | When you provide the command, you must include a revision list or a number of patches | ||
1631 | as part of the command. | ||
1632 | For example, either of these two commands takes your most | ||
1633 | recent single commit and formats it as an email message in | ||
1634 | the current directory: | ||
1635 | <literallayout class='monospaced'> | ||
1636 | $ git format-patch -1 | ||
1637 | </literallayout> | ||
1638 | or | ||
1639 | <literallayout class='monospaced'> | ||
1640 | $ git format-patch HEAD~ | ||
1641 | </literallayout></para> | ||
1642 | <para>After the command is run, the current directory contains a | ||
1643 | numbered <filename>.patch</filename> file for the commit.</para> | ||
1644 | <para>If you provide several commits as part of the command, | ||
1645 | the <filename>git format-patch</filename> command produces a | ||
1646 | series of numbered files in the current directory – one for each commit. | ||
1647 | If you have more than one patch, you should also use the | ||
1648 | <filename>--cover</filename> option with the command, which generates a | ||
1649 | cover letter as the first "patch" in the series. | ||
1650 | You can then edit the cover letter to provide a description for | ||
1651 | the series of patches. | ||
1652 | For information on the <filename>git format-patch</filename> command, | ||
1653 | see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the | ||
1654 | <filename>man git-format-patch</filename> command.</para> | ||
1655 | <note>If you are or will be a frequent contributor to the Yocto Project | ||
1656 | or to OpenEmbedded, you might consider requesting a contrib area and the | ||
1657 | necessary associated rights.</note></listitem> | ||
1658 | <listitem><para>Import the files into your mail client by using the | ||
1659 | <filename>git send-email</filename> command. | ||
1660 | <note>In order to use <filename>git send-email</filename>, you must have the | ||
1661 | the proper Git packages installed. | ||
1662 | For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para> | ||
1663 | <para>The <filename>git send-email</filename> command sends email by using a local | ||
1664 | or remote Mail Transport Agent (MTA) such as | ||
1665 | <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct | ||
1666 | <filename>smtp</filename> configuration in your Git <filename>config</filename> | ||
1667 | file. | ||
1668 | If you are submitting patches through email only, it is very important | ||
1669 | that you submit them without any whitespace or HTML formatting that | ||
1670 | either you or your mailer introduces. | ||
1671 | The maintainer that receives your patches needs to be able to save and | ||
1672 | apply them directly from your emails. | ||
1673 | A good way to verify that what you are sending will be applicable by the | ||
1674 | maintainer is to do a dry run and send them to yourself and then | ||
1675 | save and apply them as the maintainer would.</para> | ||
1676 | <para>The <filename>git send-email</filename> command is the preferred method | ||
1677 | for sending your patches since there is no risk of compromising whitespace | ||
1678 | in the body of the message, which can occur when you use your own mail client. | ||
1679 | The command also has several options that let you | ||
1680 | specify recipients and perform further editing of the email message. | ||
1681 | For information on how to use the <filename>git send-email</filename> command, | ||
1682 | see <filename>GIT-SEND-EMAIL(1)</filename> displayed using | ||
1683 | the <filename>man git-send-email</filename> command. | ||
1684 | </para></listitem> | ||
1685 | </itemizedlist> | ||
1686 | </para> | ||
1687 | </section> | ||
1688 | </section> | ||
1689 | </chapter> | ||
1690 | <!-- | ||
1691 | vim: expandtab tw=80 ts=4 | ||
1692 | --> | ||
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml new file mode 100644 index 0000000000..739fd7104b --- /dev/null +++ b/documentation/dev-manual/dev-manual-qemu.xml | |||
@@ -0,0 +1,419 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='dev-manual-qemu'> | ||
6 | |||
7 | <title>Using the Quick EMUlator (QEMU)</title> | ||
8 | |||
9 | <para> | ||
10 | Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses | ||
11 | as part of its development "tool set". | ||
12 | As such, the information in this chapter is limited to the | ||
13 | Yocto Project integration of QEMU and not QEMU in general. | ||
14 | For official information and documentation on QEMU, see the | ||
15 | following references: | ||
16 | <itemizedlist> | ||
17 | <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis> | ||
18 | The official website for the QEMU Open Source project. | ||
19 | </para></listitem> | ||
20 | <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis> | ||
21 | The QEMU user manual. | ||
22 | </para></listitem> | ||
23 | </itemizedlist> | ||
24 | </para> | ||
25 | |||
26 | <para> | ||
27 | This chapter provides an overview of the Yocto Project's integration of | ||
28 | QEMU, a description of how you use QEMU and its various options, running | ||
29 | under a Network File System (NFS) server, and a few tips and tricks you | ||
30 | might find helpful when using QEMU. | ||
31 | </para> | ||
32 | |||
33 | <section id='qemu-overview'> | ||
34 | <title>Overview</title> | ||
35 | |||
36 | <para> | ||
37 | Within the context of the Yocto Project, QEMU is an | ||
38 | emulator and virtualization machine that allows you to run a complete | ||
39 | image you have built using the Yocto Project as just another task | ||
40 | on your build system. | ||
41 | QEMU is useful for running and testing images and applications on | ||
42 | supported Yocto Project architectures without having actual hardware. | ||
43 | Among other things, the Yocto Project uses QEMU to run automated | ||
44 | Quality Assurance (QA) tests on final images shipped with each | ||
45 | release. | ||
46 | </para> | ||
47 | |||
48 | <para> | ||
49 | QEMU is made available with the Yocto Project a number of ways. | ||
50 | The easiest and recommended method for getting QEMU is to run the | ||
51 | ADT installer. For more information on how to make sure you have | ||
52 | QEMU available, see the | ||
53 | "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>" | ||
54 | section in the Yocto Project Application Developer's Guide. | ||
55 | </para> | ||
56 | </section> | ||
57 | |||
58 | <section id='qemu-running-qemu'> | ||
59 | <title>Running QEMU</title> | ||
60 | |||
61 | <para> | ||
62 | Running QEMU involves having your build environment set up, having the | ||
63 | right artifacts available, and understanding how to use the many | ||
64 | options that are available to you when you start QEMU using the | ||
65 | <filename>runqemu</filename> command. | ||
66 | </para> | ||
67 | |||
68 | <section id='qemu-setting-up-the-environment'> | ||
69 | <title>Setting Up the Environment</title> | ||
70 | |||
71 | <para> | ||
72 | You run QEMU in the same environment from which you run BitBake. | ||
73 | This means you need to source a build environment script (i.e. | ||
74 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
75 | or | ||
76 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). | ||
77 | </para> | ||
78 | </section> | ||
79 | |||
80 | <section id='qemu-using-the-runqemu-command'> | ||
81 | <title>Using the <filename>runqemu</filename> Command</title> | ||
82 | |||
83 | <para> | ||
84 | The basic <filename>runqemu</filename> command syntax is as | ||
85 | follows: | ||
86 | <literallayout class='monospaced'> | ||
87 | $ runqemu [<replaceable>option</replaceable> ] [...] | ||
88 | </literallayout> | ||
89 | Based on what you provide on the command line, | ||
90 | <filename>runqemu</filename> does a good job of figuring out what | ||
91 | you are trying to do. | ||
92 | For example, by default, QEMU looks for the most recently built | ||
93 | image according to the timestamp when it needs to look for an | ||
94 | image. | ||
95 | Minimally, through the use of options, you must provide either | ||
96 | a machine name, a virtual machine image | ||
97 | (<filename>*.vmdk</filename>), or a kernel image | ||
98 | (<filename>*.bin</filename>). | ||
99 | </para> | ||
100 | |||
101 | <para> | ||
102 | Following is a description of <filename>runqemu</filename> | ||
103 | options you can provide on the command line: | ||
104 | <note><title>Tip</title> | ||
105 | If you do provide some "illegal" option combination or perhaps | ||
106 | you do not provide enough in the way of options, | ||
107 | <filename>runqemu</filename> provides appropriate error | ||
108 | messaging to help you correct the problem. | ||
109 | </note> | ||
110 | <itemizedlist> | ||
111 | <listitem><para><replaceable>QEMUARCH</replaceable>: | ||
112 | The QEMU machine architecture, which must be "qemux86", | ||
113 | "qemux86-64", "qemuarm", "qemumips", "qemumipsel", | ||
114 | “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", | ||
115 | or "qemuzynq". | ||
116 | </para></listitem> | ||
117 | <listitem><para><filename><replaceable>VM</replaceable></filename>: | ||
118 | The virtual machine image, which must be a | ||
119 | <filename>.vmdk</filename> file. | ||
120 | Use this option when you want to boot a | ||
121 | <filename>.vmdk</filename> image. | ||
122 | The image filename you provide must contain one of the | ||
123 | following strings: "qemux86-64", "qemux86", "qemuarm", | ||
124 | "qemumips64", "qemumips", "qemuppc", or "qemush4". | ||
125 | </para></listitem> | ||
126 | <listitem><para><replaceable>ROOTFS</replaceable>: | ||
127 | A root filesystem that has one of the following | ||
128 | filetype extensions: "ext2", "ext3", "ext4", "jffs2", | ||
129 | "nfs", or "btrfs". | ||
130 | If the filename you provide for this option uses “nfs”, it | ||
131 | must provide an explicit root filesystem path. | ||
132 | </para></listitem> | ||
133 | <listitem><para><replaceable>KERNEL</replaceable>: | ||
134 | A kernel image, which is a <filename>.bin</filename> file. | ||
135 | When you provide a <filename>.bin</filename> file, | ||
136 | <filename>runqemu</filename> detects it and assumes the | ||
137 | file is a kernel image. | ||
138 | </para></listitem> | ||
139 | <listitem><para><replaceable>MACHINE</replaceable>: | ||
140 | The architecture of the QEMU machine, which must be one | ||
141 | of the following: "qemux86", | ||
142 | "qemux86-64", "qemuarm", "qemumips", "qemumipsel", | ||
143 | “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", | ||
144 | or "qemuzynq". | ||
145 | The <replaceable>MACHINE</replaceable> and | ||
146 | <replaceable>QEMUARCH</replaceable> options are basically | ||
147 | identical. | ||
148 | If you do not provide a <replaceable>MACHINE</replaceable> | ||
149 | option, <filename>runqemu</filename> tries to determine | ||
150 | it based on other options. | ||
151 | </para></listitem> | ||
152 | <listitem><para><filename>ramfs</filename>: | ||
153 | Indicates you are booting an initial RAM disk (initramfs) | ||
154 | image, which means the <filename>FSTYPE</filename> is | ||
155 | <filename>cpio.gz</filename>. | ||
156 | </para></listitem> | ||
157 | <listitem><para><filename>iso</filename>: | ||
158 | Indicates you are booting an ISO image, which means the | ||
159 | <filename>FSTYPE</filename> is | ||
160 | <filename>.iso</filename>. | ||
161 | </para></listitem> | ||
162 | <listitem><para><filename>nographic</filename>: | ||
163 | Disables the video console, which sets the console to | ||
164 | "ttys0". | ||
165 | </para></listitem> | ||
166 | <listitem><para><filename>serial</filename>: | ||
167 | Enables a serial console on | ||
168 | <filename>/dev/ttyS0</filename>. | ||
169 | </para></listitem> | ||
170 | <listitem><para><filename>biosdir</filename>: | ||
171 | Establishes a custom directory for BIOS, VGA BIOS and | ||
172 | keymaps. | ||
173 | </para></listitem> | ||
174 | <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>: | ||
175 | Specifies custom QEMU parameters. | ||
176 | Use this option to pass options other than the simple | ||
177 | "kvm" and "serial" options. | ||
178 | </para></listitem> | ||
179 | <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>: | ||
180 | Specifies custom boot parameters for the kernel. | ||
181 | </para></listitem> | ||
182 | <listitem><para><filename>audio</filename>: | ||
183 | Enables audio in QEMU. | ||
184 | The <replaceable>MACHINE</replaceable> option must be | ||
185 | either "qemux86" or "qemux86-64" in order for audio to be | ||
186 | enabled. | ||
187 | Additionally, the <filename>snd_intel8x0</filename> | ||
188 | or <filename>snd_ens1370</filename> driver must be | ||
189 | installed in linux guest. | ||
190 | </para></listitem> | ||
191 | <listitem><para><filename>slirp</filename>: | ||
192 | Enables "slirp" networking, which is a different way | ||
193 | of networking that does not need root access | ||
194 | but also is not as easy to use or comprehensive | ||
195 | as the default. | ||
196 | </para></listitem> | ||
197 | <listitem><para><filename>kvm</filename>: | ||
198 | Enables KVM when running "qemux86" or "qemux86-64" | ||
199 | QEMU architectures. | ||
200 | For KVM to work, all the following conditions must be met: | ||
201 | <itemizedlist> | ||
202 | <listitem><para> | ||
203 | Your <replaceable>MACHINE</replaceable> must be either | ||
204 | "qemux86" or "qemux86-64". | ||
205 | </para></listitem> | ||
206 | <listitem><para> | ||
207 | Your build host has to have the KVM modules | ||
208 | installed, which are | ||
209 | <filename>/dev/kvm</filename>. | ||
210 | </para></listitem> | ||
211 | <listitem><para> | ||
212 | Your build host has to have virtio net device, which | ||
213 | are <filename>/dev/vhost-net</filename>. | ||
214 | </para></listitem> | ||
215 | <listitem><para> | ||
216 | The build host <filename>/dev/kvm</filename> | ||
217 | directory has to be both writable and readable. | ||
218 | </para></listitem> | ||
219 | <listitem><para> | ||
220 | The build host <filename>/dev/vhost-net</filename> | ||
221 | directory has to be either readable or writable | ||
222 | and “slirp-enabled”. | ||
223 | </para></listitem> | ||
224 | </itemizedlist> | ||
225 | </para></listitem> | ||
226 | <listitem><para><filename>publicvnc</filename>: | ||
227 | Enables a VNC server open to all hosts. | ||
228 | </para></listitem> | ||
229 | </itemizedlist> | ||
230 | </para> | ||
231 | |||
232 | <para> | ||
233 | For further understanding regarding option use with | ||
234 | <filename>runqemu</filename>, consider some examples. | ||
235 | </para> | ||
236 | |||
237 | <para> | ||
238 | This example starts QEMU with | ||
239 | <replaceable>MACHINE</replaceable> set to "qemux86". | ||
240 | Assuming a standard | ||
241 | <link linkend='build-directory'>Build Directory</link>, | ||
242 | <filename>runqemu</filename> automatically finds the | ||
243 | <filename>bzImage-qemux86.bin</filename> image file and | ||
244 | the | ||
245 | <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename> | ||
246 | (assuming the current build created a | ||
247 | <filename>core-image-minimal</filename> image). | ||
248 | <note> | ||
249 | When more than one image with the same name exists, QEMU finds | ||
250 | and uses the most recently built image according to the | ||
251 | timestamp. | ||
252 | </note> | ||
253 | <literallayout class='monospaced'> | ||
254 | $ runqemu qemux86 | ||
255 | </literallayout> | ||
256 | This example produces the exact same results as the | ||
257 | previous example. | ||
258 | This command, however, specifically provides the image | ||
259 | and root filesystem type. | ||
260 | <literallayout class='monospaced'> | ||
261 | $ runqemu qemux86 core-image-minimal ext3 | ||
262 | </literallayout> | ||
263 | This example specifies to boot an initial RAM disk image | ||
264 | and to enable audio in QEMU. | ||
265 | For this case, <filename>runqemu</filename> set the | ||
266 | internal variable <filename>FSTYPE</filename> to | ||
267 | "cpio.gz". | ||
268 | Also, for audio to be enabled, an appropriate driver must | ||
269 | be installed (see the previous description for the | ||
270 | <filename>audio</filename> option for more information). | ||
271 | <literallayout class='monospaced'> | ||
272 | $ runqemu qemux86 ramfs audio | ||
273 | </literallayout> | ||
274 | This example does not provide enough information for | ||
275 | QEMU to launch. | ||
276 | While the command does provide a root filesystem type, it | ||
277 | must also minimally provide a | ||
278 | <replaceable>MACHINE</replaceable>, | ||
279 | <replaceable>KERNEL</replaceable>, or | ||
280 | <replaceable>VM</replaceable> option. | ||
281 | <literallayout class='monospaced'> | ||
282 | $ runqemu ext3 | ||
283 | </literallayout> | ||
284 | This example specifies to boot a virtual machine image | ||
285 | (<filename>.vmdk</filename> file). | ||
286 | From the <filename>.vmdk</filename>, | ||
287 | <filename>runqemu</filename> determines the QEMU | ||
288 | architecture (<replaceable>MACHINE</replaceable>) to be | ||
289 | "qemux86" and the root filesystem type to be "vmdk". | ||
290 | <literallayout class='monospaced'> | ||
291 | $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk | ||
292 | </literallayout> | ||
293 | </para> | ||
294 | </section> | ||
295 | </section> | ||
296 | |||
297 | <section id='qemu-running-under-a-network-file-system-nfs-server'> | ||
298 | <title>Running Under a Network File System (NFS) Server</title> | ||
299 | |||
300 | <para> | ||
301 | One method for running QEMU is to run it on an NFS server. | ||
302 | This is useful when you need to access the same file system from both | ||
303 | the build and the emulated system at the same time. | ||
304 | It is also worth noting that the system does not need root privileges | ||
305 | to run. | ||
306 | It uses a user space NFS server to avoid that. | ||
307 | This section describes how to set up for running QEMU using an NFS | ||
308 | server and then how you can start and stop the server. | ||
309 | </para> | ||
310 | |||
311 | <section id='qemu-setting-up-to-use-nfs'> | ||
312 | <title>Setting Up to Use NFS</title> | ||
313 | |||
314 | <para> | ||
315 | Once you are able to run QEMU in your environment, you can use the | ||
316 | <filename>runqemu-extract-sdk</filename> script, which is located | ||
317 | in the <filename>scripts</filename> directory along with | ||
318 | <filename>runqemu</filename> script. | ||
319 | The <filename>runqemu-extract-sdk</filename> takes a root | ||
320 | file system tarball and extracts it into a location that you | ||
321 | specify. | ||
322 | Then, when you run <filename>runqemu</filename>, you can specify | ||
323 | the location that has the file system to pass it to QEMU. | ||
324 | Here is an example that takes a file system and extracts it to | ||
325 | a directory named <filename>test-nfs</filename>: | ||
326 | <literallayout class='monospaced'> | ||
327 | runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs | ||
328 | </literallayout> | ||
329 | Once you have extracted the file system, you can run | ||
330 | <filename>runqemu</filename> normally with the additional | ||
331 | location of the file system. | ||
332 | You can then also make changes to the files within | ||
333 | <filename>./test-nfs</filename> and see those changes appear in the | ||
334 | image in real time. | ||
335 | Here is an example using the <filename>qemux86</filename> image: | ||
336 | <literallayout class='monospaced'> | ||
337 | runqemu qemux86 ./test-nfs | ||
338 | </literallayout> | ||
339 | </para> | ||
340 | </section> | ||
341 | |||
342 | <section id='qemu-starting-and-stopping-nfs'> | ||
343 | <title>Starting and Stopping NFS</title> | ||
344 | |||
345 | <para> | ||
346 | You can manually start and stop the NFS share using these | ||
347 | commands: | ||
348 | <itemizedlist> | ||
349 | <listitem><para><emphasis><filename>start</filename>:</emphasis> | ||
350 | Starts the NFS share: | ||
351 | <literallayout class='monospaced'> | ||
352 | runqemu-export-rootfs start <replaceable>file-system-location</replaceable> | ||
353 | </literallayout> | ||
354 | </para></listitem> | ||
355 | <listitem><para><emphasis><filename>stop</filename>:</emphasis> | ||
356 | Stops the NFS share: | ||
357 | <literallayout class='monospaced'> | ||
358 | runqemu-export-rootfs stop <replaceable>file-system-location</replaceable> | ||
359 | </literallayout> | ||
360 | </para></listitem> | ||
361 | <listitem><para><emphasis><filename>restart</filename>:</emphasis> | ||
362 | Restarts the NFS share: | ||
363 | <literallayout class='monospaced'> | ||
364 | runqemu-export-rootfs restart <replaceable>file-system-location</replaceable> | ||
365 | </literallayout> | ||
366 | </para></listitem> | ||
367 | </itemizedlist> | ||
368 | </para> | ||
369 | </section> | ||
370 | </section> | ||
371 | |||
372 | <section id='qemu-tips-and-tricks'> | ||
373 | <title>Tips and Tricks</title> | ||
374 | |||
375 | <para> | ||
376 | The following list describes things you can do to make running QEMU | ||
377 | in the context of the Yocto Project a better experience: | ||
378 | <itemizedlist> | ||
379 | <listitem><para><emphasis>Switching Between Consoles:</emphasis> | ||
380 | When booting or running QEMU, you can switch between | ||
381 | supported consoles by using | ||
382 | Ctrl+Alt+<replaceable>number</replaceable>. | ||
383 | For example, Ctrl+Alt+3 switches you to the serial console as | ||
384 | long as that console is enabled. | ||
385 | Being able to switch consoles is helpful, for example, if the | ||
386 | main QEMU console breaks for some reason. | ||
387 | <note> | ||
388 | Usually, "2" gets you to the main console and "3" gets you | ||
389 | to the serial console. | ||
390 | </note> | ||
391 | </para></listitem> | ||
392 | <listitem><para><emphasis>Removing the Splash Screen:</emphasis> | ||
393 | You can remove the splash screen when QEMU is booting by | ||
394 | using Alt+left. | ||
395 | Removing the splash screen allows you to see what is happening | ||
396 | in the background. | ||
397 | </para></listitem> | ||
398 | <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis> | ||
399 | The default QEMU integration captures the cursor within the | ||
400 | main window. | ||
401 | It does this since standard mouse devices only provide relative | ||
402 | input and not absolute coordinates. | ||
403 | You then have to break out of the grab using the "Ctrl+Alt" key | ||
404 | combination. | ||
405 | However, the Yocto Project's integration of QEMU enables the | ||
406 | wacom USB touch pad driver by default to allow input of absolute | ||
407 | coordinates. | ||
408 | This default means that the mouse can enter and leave the | ||
409 | main window without the grab taking effect leading to a better | ||
410 | user experience. | ||
411 | </para></listitem> | ||
412 | </itemizedlist> | ||
413 | </para> | ||
414 | </section> | ||
415 | |||
416 | </chapter> | ||
417 | <!-- | ||
418 | vim: expandtab tw=80 ts=4 | ||
419 | --> | ||
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml new file mode 100644 index 0000000000..61434ff72c --- /dev/null +++ b/documentation/dev-manual/dev-manual-start.xml | |||
@@ -0,0 +1,418 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <chapter id='dev-manual-start'> | ||
6 | |||
7 | <title>Getting Started with the Yocto Project</title> | ||
8 | |||
9 | <para> | ||
10 | This chapter introduces the Yocto Project and gives you an idea of what you need to get started. | ||
11 | You can find enough information to set up your development host and build or use images for | ||
12 | hardware supported by the Yocto Project by reading the | ||
13 | <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. | ||
14 | </para> | ||
15 | |||
16 | <para> | ||
17 | The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides | ||
18 | some higher-level concepts you might want to consider. | ||
19 | </para> | ||
20 | |||
21 | <section id='introducing-the-yocto-project'> | ||
22 | <title>Introducing the Yocto Project</title> | ||
23 | |||
24 | <para> | ||
25 | The Yocto Project is an open-source collaboration project focused on embedded Linux development. | ||
26 | The project currently provides a build system that is | ||
27 | referred to as the | ||
28 | <link linkend='build-system-term'>OpenEmbedded build system</link> | ||
29 | in the Yocto Project documentation. | ||
30 | The Yocto Project provides various ancillary tools for the embedded developer | ||
31 | and also features the Sato reference User Interface, which is optimized for | ||
32 | stylus driven, low-resolution screens. | ||
33 | </para> | ||
34 | |||
35 | <para> | ||
36 | You can use the OpenEmbedded build system, which uses | ||
37 | <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux | ||
38 | images and associated user-space applications for architectures based | ||
39 | on ARM, MIPS, PowerPC, x86 and x86-64. | ||
40 | <note> | ||
41 | By default, using the Yocto Project creates a Poky distribution. | ||
42 | However, you can create your own distribution by providing key | ||
43 | <link linkend='metadata'>Metadata</link>. | ||
44 | See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" | ||
45 | section for more information. | ||
46 | </note> | ||
47 | While the Yocto Project does not provide a strict testing framework, | ||
48 | it does provide or generate for you artifacts that let you perform target-level and | ||
49 | emulated testing and debugging. | ||
50 | Additionally, if you are an <trademark class='trade'>Eclipse</trademark> | ||
51 | IDE user, you can install an Eclipse Yocto Plug-in to allow you to | ||
52 | develop within that familiar environment. | ||
53 | </para> | ||
54 | </section> | ||
55 | |||
56 | <section id='getting-setup'> | ||
57 | <title>Getting Set Up</title> | ||
58 | |||
59 | <para> | ||
60 | Here is what you need to use the Yocto Project: | ||
61 | <itemizedlist> | ||
62 | <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current | ||
63 | Linux-based host system. | ||
64 | You will have the best results with a recent release of Fedora, | ||
65 | openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project | ||
66 | and officially supported. | ||
67 | For a list of the distributions under validation and their status, see the | ||
68 | "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section | ||
69 | in the Yocto Project Reference Manual and the wiki page at | ||
70 | <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> | ||
71 | <para> | ||
72 | You should also have about 50 Gbytes of free disk space for building images. | ||
73 | </para></listitem> | ||
74 | <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system | ||
75 | requires that certain packages exist on your development system (e.g. Python 2.6 or 2.7). | ||
76 | See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" | ||
77 | section in the Yocto Project Quick Start and the | ||
78 | "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" | ||
79 | section in the Yocto Project Reference Manual for the exact | ||
80 | package requirements and the installation commands to install | ||
81 | them for the supported distributions. | ||
82 | </para></listitem> | ||
83 | <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> | ||
84 | You need a release of the Yocto Project locally installed on | ||
85 | your development system. | ||
86 | The documentation refers to this set of locally installed files | ||
87 | as the <link linkend='source-directory'>Source Directory</link>. | ||
88 | You create your Source Directory by using | ||
89 | <link linkend='git'>Git</link> to clone a local copy | ||
90 | of the upstream <filename>poky</filename> repository, | ||
91 | or by downloading and unpacking a tarball of an official | ||
92 | Yocto Project release. | ||
93 | The preferred method is to create a clone of the repository. | ||
94 | </para> | ||
95 | <para>Working from a copy of the upstream repository allows you | ||
96 | to contribute back into the Yocto Project or simply work with | ||
97 | the latest software on a development branch. | ||
98 | Because Git maintains and creates an upstream repository with | ||
99 | a complete history of changes and you are working with a local | ||
100 | clone of that repository, you have access to all the Yocto | ||
101 | Project development branches and tag names used in the upstream | ||
102 | repository.</para> | ||
103 | <note>You can view the Yocto Project Source Repositories at | ||
104 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> | ||
105 | </note> | ||
106 | <para>The following transcript shows how to clone the | ||
107 | <filename>poky</filename> Git repository into the current | ||
108 | working directory. | ||
109 | The command creates the local repository in a directory | ||
110 | named <filename>poky</filename>. | ||
111 | For information on Git used within the Yocto Project, see | ||
112 | the "<link linkend='git'>Git</link>" section. | ||
113 | <literallayout class='monospaced'> | ||
114 | $ git clone git://git.yoctoproject.org/poky | ||
115 | Cloning into 'poky'... | ||
116 | remote: Counting objects: 226790, done. | ||
117 | remote: Compressing objects: 100% (57465/57465), done. | ||
118 | remote: Total 226790 (delta 165212), reused 225887 (delta 164327) | ||
119 | Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done. | ||
120 | Resolving deltas: 100% (165212/165212), done. | ||
121 | </literallayout></para> | ||
122 | <para>For another example of how to set up your own local Git | ||
123 | repositories, see this | ||
124 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> | ||
125 | wiki page</ulink>, which describes how to create local | ||
126 | Git repositories for both | ||
127 | <filename>poky</filename> and <filename>meta-intel</filename>. | ||
128 | </para></listitem> | ||
129 | <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> | ||
130 | If you are going to be making modifications to a supported Yocto Project kernel, you | ||
131 | need to establish local copies of the source. | ||
132 | You can find Git repositories of supported Yocto Project kernels organized under | ||
133 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at | ||
134 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> | ||
135 | <para>This setup can involve creating a bare clone of the Yocto Project kernel and then | ||
136 | copying that cloned repository. | ||
137 | You can create the bare clone and the copy of the bare clone anywhere you like. | ||
138 | For simplicity, it is recommended that you create these structures outside of the | ||
139 | Source Directory, which is usually named <filename>poky</filename>.</para> | ||
140 | <para>As an example, the following transcript shows how to create the bare clone | ||
141 | of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of | ||
142 | that clone. | ||
143 | <note>When you have a local Yocto Project kernel Git repository, you can | ||
144 | reference that repository rather than the upstream Git repository as | ||
145 | part of the <filename>clone</filename> command. | ||
146 | Doing so can speed up the process.</note></para> | ||
147 | <para>In the following example, the bare clone is named | ||
148 | <filename>linux-yocto-3.10.git</filename>, while the | ||
149 | copy is named <filename>my-linux-yocto-3.10-work</filename>: | ||
150 | <literallayout class='monospaced'> | ||
151 | $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git | ||
152 | Cloning into bare repository 'linux-yocto-3.10.git'... | ||
153 | remote: Counting objects: 3364487, done. | ||
154 | remote: Compressing objects: 100% (507178/507178), done. | ||
155 | remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709) | ||
156 | Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done. | ||
157 | Resolving deltas: 100% (2827715/2827715), done. | ||
158 | </literallayout></para> | ||
159 | <para>Now create a clone of the bare clone just created: | ||
160 | <literallayout class='monospaced'> | ||
161 | $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work | ||
162 | Cloning into 'my-linux-yocto-3.10-work'... | ||
163 | done. | ||
164 | </literallayout></para></listitem> | ||
165 | <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis> | ||
166 | The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>: | ||
167 | The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed | ||
168 | only if you are modifying and building the kernel image. | ||
169 | In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) | ||
170 | files that you | ||
171 | edit to point to your locally modified kernel source files and to build the kernel | ||
172 | image. | ||
173 | Pointing to these local files is much more efficient than requiring a download of the | ||
174 | kernel's source files from upstream each time you make changes to the kernel.</para> | ||
175 | <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the | ||
176 | "Yocto Metadata Layers" area of the Yocto Project Source Repositories at | ||
177 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. | ||
178 | It is good practice to create this Git repository inside the Source Directory.</para> | ||
179 | <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git | ||
180 | repository inside the Source Directory, which is named <filename>poky</filename> | ||
181 | in this case: | ||
182 | <literallayout class='monospaced'> | ||
183 | $ cd ~/poky | ||
184 | $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras | ||
185 | Cloning into 'meta-yocto-kernel-extras'... | ||
186 | remote: Counting objects: 727, done. | ||
187 | remote: Compressing objects: 100% (452/452), done. | ||
188 | remote: Total 727 (delta 260), reused 719 (delta 252) | ||
189 | Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done. | ||
190 | Resolving deltas: 100% (260/260), done. | ||
191 | </literallayout></para></listitem> | ||
192 | <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis> | ||
193 | The Yocto Project supports many BSPs, which are maintained in | ||
194 | their own layers or in layers designed to contain several | ||
195 | BSPs. | ||
196 | To get an idea of machine support through BSP layers, you can | ||
197 | look at the | ||
198 | <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink> | ||
199 | for the release.</para> | ||
200 | |||
201 | <para>The Yocto Project uses the following BSP layer naming | ||
202 | scheme: | ||
203 | <literallayout class='monospaced'> | ||
204 | meta-<replaceable>bsp_name</replaceable> | ||
205 | </literallayout> | ||
206 | where <replaceable>bsp_name</replaceable> is the recognized | ||
207 | BSP name. | ||
208 | Here are some examples: | ||
209 | <literallayout class='monospaced'> | ||
210 | meta-crownbay | ||
211 | meta-emenlow | ||
212 | meta-n450 | ||
213 | </literallayout> | ||
214 | See the | ||
215 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | ||
216 | section in the Yocto Project Board Support Package (BSP) | ||
217 | Developer's Guide for more information on BSP Layers.</para> | ||
218 | |||
219 | <para>A useful Git repository released with the Yocto | ||
220 | Project is <filename>meta-intel</filename>, which is a | ||
221 | parent layer that contains many supported | ||
222 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>. | ||
223 | You can locate the <filename>meta-intel</filename> Git | ||
224 | repository in the "Yocto Metadata Layers" area of the Yocto | ||
225 | Project Source Repositories at | ||
226 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> | ||
227 | |||
228 | <para>Using | ||
229 | <link linkend='git'>Git</link> to create a local clone of the | ||
230 | upstream repository can be helpful if you are working with | ||
231 | BSPs. | ||
232 | Typically, you set up the <filename>meta-intel</filename> | ||
233 | Git repository inside the Source Directory. | ||
234 | For example, the following transcript shows the steps to clone | ||
235 | <filename>meta-intel</filename>. | ||
236 | <note> | ||
237 | Be sure to work in the <filename>meta-intel</filename> | ||
238 | branch that matches your | ||
239 | <link linkend='source-directory'>Source Directory</link> | ||
240 | (i.e. <filename>poky</filename>) branch. | ||
241 | For example, if you have checked out the "master" branch | ||
242 | of <filename>poky</filename> and you are going to use | ||
243 | <filename>meta-intel</filename>, be sure to checkout the | ||
244 | "master" branch of <filename>meta-intel</filename>. | ||
245 | </note> | ||
246 | <literallayout class='monospaced'> | ||
247 | $ cd ~/poky | ||
248 | $ git clone git://git.yoctoproject.org/meta-intel.git | ||
249 | Cloning into 'meta-intel'... | ||
250 | remote: Counting objects: 8844, done. | ||
251 | remote: Compressing objects: 100% (2864/2864), done. | ||
252 | remote: Total 8844 (delta 4931), reused 8780 (delta 4867) | ||
253 | Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done. | ||
254 | Resolving deltas: 100% (4931/4931), done. | ||
255 | </literallayout></para> | ||
256 | |||
257 | <para>The same | ||
258 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink> | ||
259 | referenced earlier covers how to set up the | ||
260 | <filename>meta-intel</filename> Git repository. | ||
261 | </para></listitem> | ||
262 | <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing | ||
263 | applications using the Eclipse Integrated Development Environment (IDE), | ||
264 | you will need this plug-in. | ||
265 | See the | ||
266 | "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" | ||
267 | section for more information.</para></listitem> | ||
268 | </itemizedlist> | ||
269 | </para> | ||
270 | </section> | ||
271 | |||
272 | <section id='building-images'> | ||
273 | <title>Building Images</title> | ||
274 | |||
275 | <para> | ||
276 | The build process creates an entire Linux distribution, including the toolchain, from source. | ||
277 | For more information on this topic, see the | ||
278 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" | ||
279 | section in the Yocto Project Quick Start. | ||
280 | </para> | ||
281 | |||
282 | <para> | ||
283 | The build process is as follows: | ||
284 | <orderedlist> | ||
285 | <listitem><para>Make sure you have set up the Source Directory described in the | ||
286 | previous section.</para></listitem> | ||
287 | <listitem><para>Initialize the build environment by sourcing a build | ||
288 | environment script (i.e. | ||
289 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
290 | or | ||
291 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). | ||
292 | </para></listitem> | ||
293 | <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, | ||
294 | which is found in the | ||
295 | <link linkend='build-directory'>Build Directory</link>, | ||
296 | is set up how you want it. | ||
297 | This file defines many aspects of the build environment including | ||
298 | the target machine architecture through the | ||
299 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, | ||
300 | the development machine's processor use through the | ||
301 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and | ||
302 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and | ||
303 | a centralized tarball download directory through the | ||
304 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> | ||
305 | <listitem><para> | ||
306 | Build the image using the <filename>bitbake</filename> command. | ||
307 | If you want information on BitBake, see the | ||
308 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
309 | </para></listitem> | ||
310 | <listitem><para>Run the image either on the actual hardware or using the QEMU | ||
311 | emulator.</para></listitem> | ||
312 | </orderedlist> | ||
313 | </para> | ||
314 | </section> | ||
315 | |||
316 | <section id='using-pre-built-binaries-and-qemu'> | ||
317 | <title>Using Pre-Built Binaries and QEMU</title> | ||
318 | |||
319 | <para> | ||
320 | Another option you have to get started is to use pre-built binaries. | ||
321 | The Yocto Project provides many types of binaries with each release. | ||
322 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
323 | chapter in the Yocto Project Reference Manual | ||
324 | for descriptions of the types of binaries that ship with a Yocto Project | ||
325 | release. | ||
326 | </para> | ||
327 | |||
328 | <para> | ||
329 | Using a pre-built binary is ideal for developing software applications to run on your | ||
330 | target hardware. | ||
331 | To do this, you need to be able to access the appropriate cross-toolchain tarball for | ||
332 | the architecture on which you are developing. | ||
333 | If you are using an SDK type image, the image ships with the complete toolchain native to | ||
334 | the architecture. | ||
335 | If you are not using an SDK type image, you need to separately download and | ||
336 | install the stand-alone Yocto Project cross-toolchain tarball. | ||
337 | </para> | ||
338 | |||
339 | <para> | ||
340 | Regardless of the type of image you are using, you need to download the pre-built kernel | ||
341 | that you will boot in the QEMU emulator and then download and extract the target root | ||
342 | filesystem for your target machine’s architecture. | ||
343 | You can get architecture-specific binaries and file systems from | ||
344 | <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. | ||
345 | You can get installation scripts for stand-alone toolchains from | ||
346 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. | ||
347 | Once you have all your files, you set up the environment to emulate the hardware | ||
348 | by sourcing an environment setup script. | ||
349 | Finally, you start the QEMU emulator. | ||
350 | You can find details on all these steps in the | ||
351 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" | ||
352 | section of the Yocto Project Quick Start. | ||
353 | You can learn more about using QEMU with the Yocto Project in the | ||
354 | "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" | ||
355 | section. | ||
356 | </para> | ||
357 | |||
358 | <para> | ||
359 | Using QEMU to emulate your hardware can result in speed issues | ||
360 | depending on the target and host architecture mix. | ||
361 | For example, using the <filename>qemux86</filename> image in the emulator | ||
362 | on an Intel-based 32-bit (x86) host machine is fast because the target and | ||
363 | host architectures match. | ||
364 | On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based | ||
365 | host can be slower. | ||
366 | But, you still achieve faithful emulation of ARM-specific issues. | ||
367 | </para> | ||
368 | |||
369 | <para> | ||
370 | To speed things up, the QEMU images support using <filename>distcc</filename> | ||
371 | to call a cross-compiler outside the emulated system. | ||
372 | If you used <filename>runqemu</filename> to start QEMU, and the | ||
373 | <filename>distccd</filename> application is present on the host system, any | ||
374 | BitBake cross-compiling toolchain available from the build system is automatically | ||
375 | used from within QEMU simply by calling <filename>distcc</filename>. | ||
376 | You can accomplish this by defining the cross-compiler variable | ||
377 | (e.g. <filename>export CC="distcc"</filename>). | ||
378 | Alternatively, if you are using a suitable SDK image or the appropriate | ||
379 | stand-alone toolchain is present, | ||
380 | the toolchain is also automatically used. | ||
381 | </para> | ||
382 | |||
383 | <note> | ||
384 | Several mechanisms exist that let you connect to the system running on the | ||
385 | QEMU emulator: | ||
386 | <itemizedlist> | ||
387 | <listitem><para>QEMU provides a framebuffer interface that makes standard | ||
388 | consoles available.</para></listitem> | ||
389 | <listitem><para>Generally, headless embedded devices have a serial port. | ||
390 | If so, you can configure the operating system of the running image | ||
391 | to use that port to run a console. | ||
392 | The connection uses standard IP networking.</para></listitem> | ||
393 | <listitem><para> | ||
394 | SSH servers exist in some QEMU images. | ||
395 | The <filename>core-image-sato</filename> QEMU image has a | ||
396 | Dropbear secure shell (SSH) server that runs with the root | ||
397 | password disabled. | ||
398 | The <filename>core-image-full-cmdline</filename> and | ||
399 | <filename>core-image-lsb</filename> QEMU images | ||
400 | have OpenSSH instead of Dropbear. | ||
401 | Including these SSH servers allow you to use standard | ||
402 | <filename>ssh</filename> and <filename>scp</filename> commands. | ||
403 | The <filename>core-image-minimal</filename> QEMU image, | ||
404 | however, contains no SSH server. | ||
405 | </para></listitem> | ||
406 | <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session | ||
407 | using a local copy of the root filesystem on the host. | ||
408 | In order to make this connection, you must extract a root filesystem tarball by using the | ||
409 | <filename>runqemu-extract-sdk</filename> command. | ||
410 | After running the command, you must then point the <filename>runqemu</filename> | ||
411 | script to the extracted directory instead of a root filesystem image file.</para></listitem> | ||
412 | </itemizedlist> | ||
413 | </note> | ||
414 | </section> | ||
415 | </chapter> | ||
416 | <!-- | ||
417 | vim: expandtab tw=80 ts=4 | ||
418 | --> | ||
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml new file mode 100644 index 0000000000..4e498b8201 --- /dev/null +++ b/documentation/dev-manual/dev-manual.xml | |||
@@ -0,0 +1,124 @@ | |||
1 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <book id='dev-manual' lang='en' | ||
6 | xmlns:xi="http://www.w3.org/2003/XInclude" | ||
7 | xmlns="http://docbook.org/ns/docbook" | ||
8 | > | ||
9 | <bookinfo> | ||
10 | |||
11 | <mediaobject> | ||
12 | <imageobject> | ||
13 | <imagedata fileref='figures/dev-title.png' | ||
14 | format='SVG' | ||
15 | align='left' scalefit='1' width='100%'/> | ||
16 | </imageobject> | ||
17 | </mediaobject> | ||
18 | |||
19 | <title> | ||
20 | Yocto Project Development Manual | ||
21 | </title> | ||
22 | |||
23 | <authorgroup> | ||
24 | <author> | ||
25 | <firstname>Scott</firstname> <surname>Rifenbark</surname> | ||
26 | <affiliation> | ||
27 | <orgname>Intel Corporation</orgname> | ||
28 | </affiliation> | ||
29 | <email>scott.m.rifenbark@intel.com</email> | ||
30 | </author> | ||
31 | </authorgroup> | ||
32 | |||
33 | <revhistory> | ||
34 | <revision> | ||
35 | <revnumber>1.1</revnumber> | ||
36 | <date>6 October 2011</date> | ||
37 | <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark> | ||
38 | </revision> | ||
39 | <revision> | ||
40 | <revnumber>1.2</revnumber> | ||
41 | <date>April 2012</date> | ||
42 | <revremark>Released with the Yocto Project 1.2 Release.</revremark> | ||
43 | </revision> | ||
44 | <revision> | ||
45 | <revnumber>1.3</revnumber> | ||
46 | <date>October 2012</date> | ||
47 | <revremark>Released with the Yocto Project 1.3 Release.</revremark> | ||
48 | </revision> | ||
49 | <revision> | ||
50 | <revnumber>1.4</revnumber> | ||
51 | <date>April 2013</date> | ||
52 | <revremark>Released with the Yocto Project 1.4 Release.</revremark> | ||
53 | </revision> | ||
54 | <revision> | ||
55 | <revnumber>1.5</revnumber> | ||
56 | <date>October 2013</date> | ||
57 | <revremark>Released with the Yocto Project 1.5 Release.</revremark> | ||
58 | </revision> | ||
59 | <revision> | ||
60 | <revnumber>1.5.1</revnumber> | ||
61 | <date>January 2014</date> | ||
62 | <revremark>Released with the Yocto Project 1.5.1 Release.</revremark> | ||
63 | </revision> | ||
64 | <revision> | ||
65 | <revnumber>1.6</revnumber> | ||
66 | <date>April 2014</date> | ||
67 | <revremark>Released with the Yocto Project 1.6 Release.</revremark> | ||
68 | </revision> | ||
69 | <revision> | ||
70 | <revnumber>1.7</revnumber> | ||
71 | <date>October 2014</date> | ||
72 | <revremark>Released with the Yocto Project 1.7 Release.</revremark> | ||
73 | </revision> | ||
74 | <revision> | ||
75 | <revnumber>1.7.1</revnumber> | ||
76 | <date>January 2015</date> | ||
77 | <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> | ||
78 | </revision> | ||
79 | <revision> | ||
80 | <revnumber>1.7.2</revnumber> | ||
81 | <date>June 2015</date> | ||
82 | <revremark>Released with the Yocto Project 1.7.2 Release.</revremark> | ||
83 | </revision> | ||
84 | </revhistory> | ||
85 | |||
86 | <copyright> | ||
87 | <year>©RIGHT_YEAR;</year> | ||
88 | <holder>Linux Foundation</holder> | ||
89 | </copyright> | ||
90 | |||
91 | <legalnotice> | ||
92 | <para> | ||
93 | Permission is granted to copy, distribute and/or modify this document under | ||
94 | the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/"> | ||
95 | Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by | ||
96 | Creative Commons. | ||
97 | </para> | ||
98 | |||
99 | <note> | ||
100 | For the latest version of this manual associated with this | ||
101 | Yocto Project release, see the | ||
102 | <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> | ||
103 | from the Yocto Project website. | ||
104 | </note> | ||
105 | </legalnotice> | ||
106 | |||
107 | </bookinfo> | ||
108 | |||
109 | <xi:include href="dev-manual-intro.xml"/> | ||
110 | |||
111 | <xi:include href="dev-manual-start.xml"/> | ||
112 | |||
113 | <xi:include href="dev-manual-newbie.xml"/> | ||
114 | |||
115 | <xi:include href="dev-manual-model.xml"/> | ||
116 | |||
117 | <xi:include href="dev-manual-common-tasks.xml"/> | ||
118 | |||
119 | <xi:include href="dev-manual-qemu.xml"/> | ||
120 | |||
121 | </book> | ||
122 | <!-- | ||
123 | vim: expandtab tw=80 ts=4 | ||
124 | --> | ||
diff --git a/documentation/dev-manual/dev-style.css b/documentation/dev-manual/dev-style.css new file mode 100644 index 0000000000..b900ffc9b2 --- /dev/null +++ b/documentation/dev-manual/dev-style.css | |||
@@ -0,0 +1,984 @@ | |||
1 | /* | ||
2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | ||
3 | |||
4 | Browser wrangling and typographic design by | ||
5 | Oyvind Kolas / pippin@gimp.org | ||
6 | |||
7 | Customised for Poky by | ||
8 | Matthew Allum / mallum@o-hand.com | ||
9 | |||
10 | Thanks to: | ||
11 | Liam R. E. Quin | ||
12 | William Skaggs | ||
13 | Jakub Steiner | ||
14 | |||
15 | Structure | ||
16 | --------- | ||
17 | |||
18 | The stylesheet is divided into the following sections: | ||
19 | |||
20 | Positioning | ||
21 | Margins, paddings, width, font-size, clearing. | ||
22 | Decorations | ||
23 | Borders, style | ||
24 | Colors | ||
25 | Colors | ||
26 | Graphics | ||
27 | Graphical backgrounds | ||
28 | Nasty IE tweaks | ||
29 | Workarounds needed to make it work in internet explorer, | ||
30 | currently makes the stylesheet non validating, but up until | ||
31 | this point it is validating. | ||
32 | Mozilla extensions | ||
33 | Transparency for footer | ||
34 | Rounded corners on boxes | ||
35 | |||
36 | */ | ||
37 | |||
38 | |||
39 | /*************** / | ||
40 | / Positioning / | ||
41 | / ***************/ | ||
42 | |||
43 | body { | ||
44 | font-family: Verdana, Sans, sans-serif; | ||
45 | |||
46 | min-width: 640px; | ||
47 | width: 80%; | ||
48 | margin: 0em auto; | ||
49 | padding: 2em 5em 5em 5em; | ||
50 | color: #333; | ||
51 | } | ||
52 | |||
53 | h1,h2,h3,h4,h5,h6,h7 { | ||
54 | font-family: Arial, Sans; | ||
55 | color: #00557D; | ||
56 | clear: both; | ||
57 | } | ||
58 | |||
59 | h1 { | ||
60 | font-size: 2em; | ||
61 | text-align: left; | ||
62 | padding: 0em 0em 0em 0em; | ||
63 | margin: 2em 0em 0em 0em; | ||
64 | } | ||
65 | |||
66 | h2.subtitle { | ||
67 | margin: 0.10em 0em 3.0em 0em; | ||
68 | padding: 0em 0em 0em 0em; | ||
69 | font-size: 1.8em; | ||
70 | padding-left: 20%; | ||
71 | font-weight: normal; | ||
72 | font-style: italic; | ||
73 | } | ||
74 | |||
75 | h2 { | ||
76 | margin: 2em 0em 0.66em 0em; | ||
77 | padding: 0.5em 0em 0em 0em; | ||
78 | font-size: 1.5em; | ||
79 | font-weight: bold; | ||
80 | } | ||
81 | |||
82 | h3.subtitle { | ||
83 | margin: 0em 0em 1em 0em; | ||
84 | padding: 0em 0em 0em 0em; | ||
85 | font-size: 142.14%; | ||
86 | text-align: right; | ||
87 | } | ||
88 | |||
89 | h3 { | ||
90 | margin: 1em 0em 0.5em 0em; | ||
91 | padding: 1em 0em 0em 0em; | ||
92 | font-size: 140%; | ||
93 | font-weight: bold; | ||
94 | } | ||
95 | |||
96 | h4 { | ||
97 | margin: 1em 0em 0.5em 0em; | ||
98 | padding: 1em 0em 0em 0em; | ||
99 | font-size: 120%; | ||
100 | font-weight: bold; | ||
101 | } | ||
102 | |||
103 | h5 { | ||
104 | margin: 1em 0em 0.5em 0em; | ||
105 | padding: 1em 0em 0em 0em; | ||
106 | font-size: 110%; | ||
107 | font-weight: bold; | ||
108 | } | ||
109 | |||
110 | h6 { | ||
111 | margin: 1em 0em 0em 0em; | ||
112 | padding: 1em 0em 0em 0em; | ||
113 | font-size: 110%; | ||
114 | font-weight: bold; | ||
115 | } | ||
116 | |||
117 | .authorgroup { | ||
118 | background-color: transparent; | ||
119 | background-repeat: no-repeat; | ||
120 | padding-top: 256px; | ||
121 | background-image: url("figures/dev-title.png"); | ||
122 | background-position: left top; | ||
123 | margin-top: -256px; | ||
124 | padding-right: 50px; | ||
125 | margin-left: 0px; | ||
126 | text-align: right; | ||
127 | width: 740px; | ||
128 | } | ||
129 | |||
130 | h3.author { | ||
131 | margin: 0em 0me 0em 0em; | ||
132 | padding: 0em 0em 0em 0em; | ||
133 | font-weight: normal; | ||
134 | font-size: 100%; | ||
135 | color: #333; | ||
136 | clear: both; | ||
137 | } | ||
138 | |||
139 | .author tt.email { | ||
140 | font-size: 66%; | ||
141 | } | ||
142 | |||
143 | .titlepage hr { | ||
144 | width: 0em; | ||
145 | clear: both; | ||
146 | } | ||
147 | |||
148 | .revhistory { | ||
149 | padding-top: 2em; | ||
150 | clear: both; | ||
151 | } | ||
152 | |||
153 | .toc, | ||
154 | .list-of-tables, | ||
155 | .list-of-examples, | ||
156 | .list-of-figures { | ||
157 | padding: 1.33em 0em 2.5em 0em; | ||
158 | color: #00557D; | ||
159 | } | ||
160 | |||
161 | .toc p, | ||
162 | .list-of-tables p, | ||
163 | .list-of-figures p, | ||
164 | .list-of-examples p { | ||
165 | padding: 0em 0em 0em 0em; | ||
166 | padding: 0em 0em 0.3em; | ||
167 | margin: 1.5em 0em 0em 0em; | ||
168 | } | ||
169 | |||
170 | .toc p b, | ||
171 | .list-of-tables p b, | ||
172 | .list-of-figures p b, | ||
173 | .list-of-examples p b{ | ||
174 | font-size: 100.0%; | ||
175 | font-weight: bold; | ||
176 | } | ||
177 | |||
178 | .toc dl, | ||
179 | .list-of-tables dl, | ||
180 | .list-of-figures dl, | ||
181 | .list-of-examples dl { | ||
182 | margin: 0em 0em 0.5em 0em; | ||
183 | padding: 0em 0em 0em 0em; | ||
184 | } | ||
185 | |||
186 | .toc dt { | ||
187 | margin: 0em 0em 0em 0em; | ||
188 | padding: 0em 0em 0em 0em; | ||
189 | } | ||
190 | |||
191 | .toc dd { | ||
192 | margin: 0em 0em 0em 2.6em; | ||
193 | padding: 0em 0em 0em 0em; | ||
194 | } | ||
195 | |||
196 | div.glossary dl, | ||
197 | div.variablelist dl { | ||
198 | } | ||
199 | |||
200 | .glossary dl dt, | ||
201 | .variablelist dl dt, | ||
202 | .variablelist dl dt span.term { | ||
203 | font-weight: normal; | ||
204 | width: 20em; | ||
205 | text-align: right; | ||
206 | } | ||
207 | |||
208 | .variablelist dl dt { | ||
209 | margin-top: 0.5em; | ||
210 | } | ||
211 | |||
212 | .glossary dl dd, | ||
213 | .variablelist dl dd { | ||
214 | margin-top: -1em; | ||
215 | margin-left: 25.5em; | ||
216 | } | ||
217 | |||
218 | .glossary dd p, | ||
219 | .variablelist dd p { | ||
220 | margin-top: 0em; | ||
221 | margin-bottom: 1em; | ||
222 | } | ||
223 | |||
224 | |||
225 | div.calloutlist table td { | ||
226 | padding: 0em 0em 0em 0em; | ||
227 | margin: 0em 0em 0em 0em; | ||
228 | } | ||
229 | |||
230 | div.calloutlist table td p { | ||
231 | margin-top: 0em; | ||
232 | margin-bottom: 1em; | ||
233 | } | ||
234 | |||
235 | div p.copyright { | ||
236 | text-align: left; | ||
237 | } | ||
238 | |||
239 | div.legalnotice p.legalnotice-title { | ||
240 | margin-bottom: 0em; | ||
241 | } | ||
242 | |||
243 | p { | ||
244 | line-height: 1.5em; | ||
245 | margin-top: 0em; | ||
246 | |||
247 | } | ||
248 | |||
249 | dl { | ||
250 | padding-top: 0em; | ||
251 | } | ||
252 | |||
253 | hr { | ||
254 | border: solid 1px; | ||
255 | } | ||
256 | |||
257 | |||
258 | .mediaobject, | ||
259 | .mediaobjectco { | ||
260 | text-align: center; | ||
261 | } | ||
262 | |||
263 | img { | ||
264 | border: none; | ||
265 | } | ||
266 | |||
267 | ul { | ||
268 | padding: 0em 0em 0em 1.5em; | ||
269 | } | ||
270 | |||
271 | ul li { | ||
272 | padding: 0em 0em 0em 0em; | ||
273 | } | ||
274 | |||
275 | ul li p { | ||
276 | text-align: left; | ||
277 | } | ||
278 | |||
279 | table { | ||
280 | width :100%; | ||
281 | } | ||
282 | |||
283 | th { | ||
284 | padding: 0.25em; | ||
285 | text-align: left; | ||
286 | font-weight: normal; | ||
287 | vertical-align: top; | ||
288 | } | ||
289 | |||
290 | td { | ||
291 | padding: 0.25em; | ||
292 | vertical-align: top; | ||
293 | } | ||
294 | |||
295 | p a[id] { | ||
296 | margin: 0px; | ||
297 | padding: 0px; | ||
298 | display: inline; | ||
299 | background-image: none; | ||
300 | } | ||
301 | |||
302 | a { | ||
303 | text-decoration: underline; | ||
304 | color: #444; | ||
305 | } | ||
306 | |||
307 | pre { | ||
308 | overflow: auto; | ||
309 | } | ||
310 | |||
311 | a:hover { | ||
312 | text-decoration: underline; | ||
313 | /*font-weight: bold;*/ | ||
314 | } | ||
315 | |||
316 | /* This style defines how the permalink character | ||
317 | appears by itself and when hovered over with | ||
318 | the mouse. */ | ||
319 | |||
320 | [alt='Permalink'] { color: #eee; } | ||
321 | [alt='Permalink']:hover { color: black; } | ||
322 | |||
323 | |||
324 | div.informalfigure, | ||
325 | div.informalexample, | ||
326 | div.informaltable, | ||
327 | div.figure, | ||
328 | div.table, | ||
329 | div.example { | ||
330 | margin: 1em 0em; | ||
331 | padding: 1em; | ||
332 | page-break-inside: avoid; | ||
333 | } | ||
334 | |||
335 | |||
336 | div.informalfigure p.title b, | ||
337 | div.informalexample p.title b, | ||
338 | div.informaltable p.title b, | ||
339 | div.figure p.title b, | ||
340 | div.example p.title b, | ||
341 | div.table p.title b{ | ||
342 | padding-top: 0em; | ||
343 | margin-top: 0em; | ||
344 | font-size: 100%; | ||
345 | font-weight: normal; | ||
346 | } | ||
347 | |||
348 | .mediaobject .caption, | ||
349 | .mediaobject .caption p { | ||
350 | text-align: center; | ||
351 | font-size: 80%; | ||
352 | padding-top: 0.5em; | ||
353 | padding-bottom: 0.5em; | ||
354 | } | ||
355 | |||
356 | .epigraph { | ||
357 | padding-left: 55%; | ||
358 | margin-bottom: 1em; | ||
359 | } | ||
360 | |||
361 | .epigraph p { | ||
362 | text-align: left; | ||
363 | } | ||
364 | |||
365 | .epigraph .quote { | ||
366 | font-style: italic; | ||
367 | } | ||
368 | .epigraph .attribution { | ||
369 | font-style: normal; | ||
370 | text-align: right; | ||
371 | } | ||
372 | |||
373 | span.application { | ||
374 | font-style: italic; | ||
375 | } | ||
376 | |||
377 | .programlisting { | ||
378 | font-family: monospace; | ||
379 | font-size: 80%; | ||
380 | white-space: pre; | ||
381 | margin: 1.33em 0em; | ||
382 | padding: 1.33em; | ||
383 | } | ||
384 | |||
385 | .tip, | ||
386 | .warning, | ||
387 | .caution, | ||
388 | .note { | ||
389 | margin-top: 1em; | ||
390 | margin-bottom: 1em; | ||
391 | |||
392 | } | ||
393 | |||
394 | /* force full width of table within div */ | ||
395 | .tip table, | ||
396 | .warning table, | ||
397 | .caution table, | ||
398 | .note table { | ||
399 | border: none; | ||
400 | width: 100%; | ||
401 | } | ||
402 | |||
403 | |||
404 | .tip table th, | ||
405 | .warning table th, | ||
406 | .caution table th, | ||
407 | .note table th { | ||
408 | padding: 0.8em 0.0em 0.0em 0.0em; | ||
409 | margin : 0em 0em 0em 0em; | ||
410 | } | ||
411 | |||
412 | .tip p, | ||
413 | .warning p, | ||
414 | .caution p, | ||
415 | .note p { | ||
416 | margin-top: 0.5em; | ||
417 | margin-bottom: 0.5em; | ||
418 | padding-right: 1em; | ||
419 | text-align: left; | ||
420 | } | ||
421 | |||
422 | .acronym { | ||
423 | text-transform: uppercase; | ||
424 | } | ||
425 | |||
426 | b.keycap, | ||
427 | .keycap { | ||
428 | padding: 0.09em 0.3em; | ||
429 | margin: 0em; | ||
430 | } | ||
431 | |||
432 | .itemizedlist li { | ||
433 | clear: none; | ||
434 | } | ||
435 | |||
436 | .filename { | ||
437 | font-size: medium; | ||
438 | font-family: Courier, monospace; | ||
439 | } | ||
440 | |||
441 | |||
442 | div.navheader, div.heading{ | ||
443 | position: absolute; | ||
444 | left: 0em; | ||
445 | top: 0em; | ||
446 | width: 100%; | ||
447 | background-color: #cdf; | ||
448 | width: 100%; | ||
449 | } | ||
450 | |||
451 | div.navfooter, div.footing{ | ||
452 | position: fixed; | ||
453 | left: 0em; | ||
454 | bottom: 0em; | ||
455 | background-color: #eee; | ||
456 | width: 100%; | ||
457 | } | ||
458 | |||
459 | |||
460 | div.navheader td, | ||
461 | div.navfooter td { | ||
462 | font-size: 66%; | ||
463 | } | ||
464 | |||
465 | div.navheader table th { | ||
466 | /*font-family: Georgia, Times, serif;*/ | ||
467 | /*font-size: x-large;*/ | ||
468 | font-size: 80%; | ||
469 | } | ||
470 | |||
471 | div.navheader table { | ||
472 | border-left: 0em; | ||
473 | border-right: 0em; | ||
474 | border-top: 0em; | ||
475 | width: 100%; | ||
476 | } | ||
477 | |||
478 | div.navfooter table { | ||
479 | border-left: 0em; | ||
480 | border-right: 0em; | ||
481 | border-bottom: 0em; | ||
482 | width: 100%; | ||
483 | } | ||
484 | |||
485 | div.navheader table td a, | ||
486 | div.navfooter table td a { | ||
487 | color: #777; | ||
488 | text-decoration: none; | ||
489 | } | ||
490 | |||
491 | /* normal text in the footer */ | ||
492 | div.navfooter table td { | ||
493 | color: black; | ||
494 | } | ||
495 | |||
496 | div.navheader table td a:visited, | ||
497 | div.navfooter table td a:visited { | ||
498 | color: #444; | ||
499 | } | ||
500 | |||
501 | |||
502 | /* links in header and footer */ | ||
503 | div.navheader table td a:hover, | ||
504 | div.navfooter table td a:hover { | ||
505 | text-decoration: underline; | ||
506 | background-color: transparent; | ||
507 | color: #33a; | ||
508 | } | ||
509 | |||
510 | div.navheader hr, | ||
511 | div.navfooter hr { | ||
512 | display: none; | ||
513 | } | ||
514 | |||
515 | |||
516 | .qandaset tr.question td p { | ||
517 | margin: 0em 0em 1em 0em; | ||
518 | padding: 0em 0em 0em 0em; | ||
519 | } | ||
520 | |||
521 | .qandaset tr.answer td p { | ||
522 | margin: 0em 0em 1em 0em; | ||
523 | padding: 0em 0em 0em 0em; | ||
524 | } | ||
525 | .answer td { | ||
526 | padding-bottom: 1.5em; | ||
527 | } | ||
528 | |||
529 | .emphasis { | ||
530 | font-weight: bold; | ||
531 | } | ||
532 | |||
533 | |||
534 | /************* / | ||
535 | / decorations / | ||
536 | / *************/ | ||
537 | |||
538 | .titlepage { | ||
539 | } | ||
540 | |||
541 | .part .title { | ||
542 | } | ||
543 | |||
544 | .subtitle { | ||
545 | border: none; | ||
546 | } | ||
547 | |||
548 | /* | ||
549 | h1 { | ||
550 | border: none; | ||
551 | } | ||
552 | |||
553 | h2 { | ||
554 | border-top: solid 0.2em; | ||
555 | border-bottom: solid 0.06em; | ||
556 | } | ||
557 | |||
558 | h3 { | ||
559 | border-top: 0em; | ||
560 | border-bottom: solid 0.06em; | ||
561 | } | ||
562 | |||
563 | h4 { | ||
564 | border: 0em; | ||
565 | border-bottom: solid 0.06em; | ||
566 | } | ||
567 | |||
568 | h5 { | ||
569 | border: 0em; | ||
570 | } | ||
571 | */ | ||
572 | |||
573 | .programlisting { | ||
574 | border: solid 1px; | ||
575 | } | ||
576 | |||
577 | div.figure, | ||
578 | div.table, | ||
579 | div.informalfigure, | ||
580 | div.informaltable, | ||
581 | div.informalexample, | ||
582 | div.example { | ||
583 | border: 1px solid; | ||
584 | } | ||
585 | |||
586 | |||
587 | |||
588 | .tip, | ||
589 | .warning, | ||
590 | .caution, | ||
591 | .note { | ||
592 | border: 1px solid; | ||
593 | } | ||
594 | |||
595 | .tip table th, | ||
596 | .warning table th, | ||
597 | .caution table th, | ||
598 | .note table th { | ||
599 | border-bottom: 1px solid; | ||
600 | } | ||
601 | |||
602 | .question td { | ||
603 | border-top: 1px solid black; | ||
604 | } | ||
605 | |||
606 | .answer { | ||
607 | } | ||
608 | |||
609 | |||
610 | b.keycap, | ||
611 | .keycap { | ||
612 | border: 1px solid; | ||
613 | } | ||
614 | |||
615 | |||
616 | div.navheader, div.heading{ | ||
617 | border-bottom: 1px solid; | ||
618 | } | ||
619 | |||
620 | |||
621 | div.navfooter, div.footing{ | ||
622 | border-top: 1px solid; | ||
623 | } | ||
624 | |||
625 | /********* / | ||
626 | / colors / | ||
627 | / *********/ | ||
628 | |||
629 | body { | ||
630 | color: #333; | ||
631 | background: white; | ||
632 | } | ||
633 | |||
634 | a { | ||
635 | background: transparent; | ||
636 | } | ||
637 | |||
638 | a:hover { | ||
639 | background-color: #dedede; | ||
640 | } | ||
641 | |||
642 | |||
643 | h1, | ||
644 | h2, | ||
645 | h3, | ||
646 | h4, | ||
647 | h5, | ||
648 | h6, | ||
649 | h7, | ||
650 | h8 { | ||
651 | background-color: transparent; | ||
652 | } | ||
653 | |||
654 | hr { | ||
655 | border-color: #aaa; | ||
656 | } | ||
657 | |||
658 | |||
659 | .tip, .warning, .caution, .note { | ||
660 | border-color: #fff; | ||
661 | } | ||
662 | |||
663 | |||
664 | .tip table th, | ||
665 | .warning table th, | ||
666 | .caution table th, | ||
667 | .note table th { | ||
668 | border-bottom-color: #fff; | ||
669 | } | ||
670 | |||
671 | |||
672 | .warning { | ||
673 | background-color: #f0f0f2; | ||
674 | } | ||
675 | |||
676 | .caution { | ||
677 | background-color: #f0f0f2; | ||
678 | } | ||
679 | |||
680 | .tip { | ||
681 | background-color: #f0f0f2; | ||
682 | } | ||
683 | |||
684 | .note { | ||
685 | background-color: #f0f0f2; | ||
686 | } | ||
687 | |||
688 | .glossary dl dt, | ||
689 | .variablelist dl dt, | ||
690 | .variablelist dl dt span.term { | ||
691 | color: #044; | ||
692 | } | ||
693 | |||
694 | div.figure, | ||
695 | div.table, | ||
696 | div.example, | ||
697 | div.informalfigure, | ||
698 | div.informaltable, | ||
699 | div.informalexample { | ||
700 | border-color: #aaa; | ||
701 | } | ||
702 | |||
703 | pre.programlisting { | ||
704 | color: black; | ||
705 | background-color: #fff; | ||
706 | border-color: #aaa; | ||
707 | border-width: 2px; | ||
708 | } | ||
709 | |||
710 | .guimenu, | ||
711 | .guilabel, | ||
712 | .guimenuitem { | ||
713 | background-color: #eee; | ||
714 | } | ||
715 | |||
716 | |||
717 | b.keycap, | ||
718 | .keycap { | ||
719 | background-color: #eee; | ||
720 | border-color: #999; | ||
721 | } | ||
722 | |||
723 | |||
724 | div.navheader { | ||
725 | border-color: black; | ||
726 | } | ||
727 | |||
728 | |||
729 | div.navfooter { | ||
730 | border-color: black; | ||
731 | } | ||
732 | |||
733 | |||
734 | /*********** / | ||
735 | / graphics / | ||
736 | / ***********/ | ||
737 | |||
738 | /* | ||
739 | body { | ||
740 | background-image: url("images/body_bg.jpg"); | ||
741 | background-attachment: fixed; | ||
742 | } | ||
743 | |||
744 | .navheader, | ||
745 | .note, | ||
746 | .tip { | ||
747 | background-image: url("images/note_bg.jpg"); | ||
748 | background-attachment: fixed; | ||
749 | } | ||
750 | |||
751 | .warning, | ||
752 | .caution { | ||
753 | background-image: url("images/warning_bg.jpg"); | ||
754 | background-attachment: fixed; | ||
755 | } | ||
756 | |||
757 | .figure, | ||
758 | .informalfigure, | ||
759 | .example, | ||
760 | .informalexample, | ||
761 | .table, | ||
762 | .informaltable { | ||
763 | background-image: url("images/figure_bg.jpg"); | ||
764 | background-attachment: fixed; | ||
765 | } | ||
766 | |||
767 | */ | ||
768 | h1, | ||
769 | h2, | ||
770 | h3, | ||
771 | h4, | ||
772 | h5, | ||
773 | h6, | ||
774 | h7{ | ||
775 | } | ||
776 | |||
777 | /* | ||
778 | Example of how to stick an image as part of the title. | ||
779 | |||
780 | div.article .titlepage .title | ||
781 | { | ||
782 | background-image: url("figures/white-on-black.png"); | ||
783 | background-position: center; | ||
784 | background-repeat: repeat-x; | ||
785 | } | ||
786 | */ | ||
787 | |||
788 | div.preface .titlepage .title, | ||
789 | div.colophon .title, | ||
790 | div.chapter .titlepage .title, | ||
791 | div.article .titlepage .title | ||
792 | { | ||
793 | } | ||
794 | |||
795 | div.section div.section .titlepage .title, | ||
796 | div.sect2 .titlepage .title { | ||
797 | background: none; | ||
798 | } | ||
799 | |||
800 | |||
801 | h1.title { | ||
802 | background-color: transparent; | ||
803 | background-repeat: no-repeat; | ||
804 | height: 256px; | ||
805 | text-indent: -9000px; | ||
806 | overflow:hidden; | ||
807 | } | ||
808 | |||
809 | h2.subtitle { | ||
810 | background-color: transparent; | ||
811 | text-indent: -9000px; | ||
812 | overflow:hidden; | ||
813 | width: 0px; | ||
814 | display: none; | ||
815 | } | ||
816 | |||
817 | /*************************************** / | ||
818 | / pippin.gimp.org specific alterations / | ||
819 | / ***************************************/ | ||
820 | |||
821 | /* | ||
822 | div.heading, div.navheader { | ||
823 | color: #777; | ||
824 | font-size: 80%; | ||
825 | padding: 0; | ||
826 | margin: 0; | ||
827 | text-align: left; | ||
828 | position: absolute; | ||
829 | top: 0px; | ||
830 | left: 0px; | ||
831 | width: 100%; | ||
832 | height: 50px; | ||
833 | background: url('/gfx/heading_bg.png') transparent; | ||
834 | background-repeat: repeat-x; | ||
835 | background-attachment: fixed; | ||
836 | border: none; | ||
837 | } | ||
838 | |||
839 | div.heading a { | ||
840 | color: #444; | ||
841 | } | ||
842 | |||
843 | div.footing, div.navfooter { | ||
844 | border: none; | ||
845 | color: #ddd; | ||
846 | font-size: 80%; | ||
847 | text-align:right; | ||
848 | |||
849 | width: 100%; | ||
850 | padding-top: 10px; | ||
851 | position: absolute; | ||
852 | bottom: 0px; | ||
853 | left: 0px; | ||
854 | |||
855 | background: url('/gfx/footing_bg.png') transparent; | ||
856 | } | ||
857 | */ | ||
858 | |||
859 | |||
860 | |||
861 | /****************** / | ||
862 | / nasty ie tweaks / | ||
863 | / ******************/ | ||
864 | |||
865 | /* | ||
866 | div.heading, div.navheader { | ||
867 | width:expression(document.body.clientWidth + "px"); | ||
868 | } | ||
869 | |||
870 | div.footing, div.navfooter { | ||
871 | width:expression(document.body.clientWidth + "px"); | ||
872 | margin-left:expression("-5em"); | ||
873 | } | ||
874 | body { | ||
875 | padding:expression("4em 5em 0em 5em"); | ||
876 | } | ||
877 | */ | ||
878 | |||
879 | /**************************************** / | ||
880 | / mozilla vendor specific css extensions / | ||
881 | / ****************************************/ | ||
882 | /* | ||
883 | div.navfooter, div.footing{ | ||
884 | -moz-opacity: 0.8em; | ||
885 | } | ||
886 | |||
887 | div.figure, | ||
888 | div.table, | ||
889 | div.informalfigure, | ||
890 | div.informaltable, | ||
891 | div.informalexample, | ||
892 | div.example, | ||
893 | .tip, | ||
894 | .warning, | ||
895 | .caution, | ||
896 | .note { | ||
897 | -moz-border-radius: 0.5em; | ||
898 | } | ||
899 | |||
900 | b.keycap, | ||
901 | .keycap { | ||
902 | -moz-border-radius: 0.3em; | ||
903 | } | ||
904 | */ | ||
905 | |||
906 | table tr td table tr td { | ||
907 | display: none; | ||
908 | } | ||
909 | |||
910 | |||
911 | hr { | ||
912 | display: none; | ||
913 | } | ||
914 | |||
915 | table { | ||
916 | border: 0em; | ||
917 | } | ||
918 | |||
919 | .photo { | ||
920 | float: right; | ||
921 | margin-left: 1.5em; | ||
922 | margin-bottom: 1.5em; | ||
923 | margin-top: 0em; | ||
924 | max-width: 17em; | ||
925 | border: 1px solid gray; | ||
926 | padding: 3px; | ||
927 | background: white; | ||
928 | } | ||
929 | .seperator { | ||
930 | padding-top: 2em; | ||
931 | clear: both; | ||
932 | } | ||
933 | |||
934 | #validators { | ||
935 | margin-top: 5em; | ||
936 | text-align: right; | ||
937 | color: #777; | ||
938 | } | ||
939 | @media print { | ||
940 | body { | ||
941 | font-size: 8pt; | ||
942 | } | ||
943 | .noprint { | ||
944 | display: none; | ||
945 | } | ||
946 | } | ||
947 | |||
948 | |||
949 | .tip, | ||
950 | .note { | ||
951 | background: #f0f0f2; | ||
952 | color: #333; | ||
953 | padding: 20px; | ||
954 | margin: 20px; | ||
955 | } | ||
956 | |||
957 | .tip h3, | ||
958 | .note h3 { | ||
959 | padding: 0em; | ||
960 | margin: 0em; | ||
961 | font-size: 2em; | ||
962 | font-weight: bold; | ||
963 | color: #333; | ||
964 | } | ||
965 | |||
966 | .tip a, | ||
967 | .note a { | ||
968 | color: #333; | ||
969 | text-decoration: underline; | ||
970 | } | ||
971 | |||
972 | .footnote { | ||
973 | font-size: small; | ||
974 | color: #333; | ||
975 | } | ||
976 | |||
977 | /* Changes the announcement text */ | ||
978 | .tip h3, | ||
979 | .warning h3, | ||
980 | .caution h3, | ||
981 | .note h3 { | ||
982 | font-size:large; | ||
983 | color: #00557D; | ||
984 | } | ||
diff --git a/documentation/dev-manual/figures/app-dev-flow.png b/documentation/dev-manual/figures/app-dev-flow.png new file mode 100644 index 0000000000..ec93374ee7 --- /dev/null +++ b/documentation/dev-manual/figures/app-dev-flow.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/bsp-dev-flow.png b/documentation/dev-manual/figures/bsp-dev-flow.png new file mode 100644 index 0000000000..540b0abb9f --- /dev/null +++ b/documentation/dev-manual/figures/bsp-dev-flow.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/dev-title.png b/documentation/dev-manual/figures/dev-title.png new file mode 100644 index 0000000000..d3cac4a7e5 --- /dev/null +++ b/documentation/dev-manual/figures/dev-title.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/dev-manual/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 --- /dev/null +++ b/documentation/dev-manual/figures/git-workflow.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/index-downloads.png b/documentation/dev-manual/figures/index-downloads.png new file mode 100644 index 0000000000..41251d5d18 --- /dev/null +++ b/documentation/dev-manual/figures/index-downloads.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png new file mode 100644 index 0000000000..009105d122 --- /dev/null +++ b/documentation/dev-manual/figures/kernel-dev-flow.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png new file mode 100644 index 0000000000..116c0b9bd4 --- /dev/null +++ b/documentation/dev-manual/figures/kernel-overview-1.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png new file mode 100644 index 0000000000..889ff1bf0d --- /dev/null +++ b/documentation/dev-manual/figures/kernel-overview-2-generic.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png new file mode 100644 index 0000000000..c0e960b13b --- /dev/null +++ b/documentation/dev-manual/figures/recipe-workflow.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/source-repos.png b/documentation/dev-manual/figures/source-repos.png new file mode 100644 index 0000000000..65c5f29a43 --- /dev/null +++ b/documentation/dev-manual/figures/source-repos.png | |||
Binary files differ | |||
diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png new file mode 100644 index 0000000000..5770be6883 --- /dev/null +++ b/documentation/dev-manual/figures/yp-download.png | |||
Binary files differ | |||