diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-01-30 13:42:02 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:30 +0000 |
commit | 1f0a763637b5d5dea3ab11d6faeb3d6d0aa3f567 (patch) | |
tree | 2cf9c207f1f368c83c1ada0e4416f98920b948a2 | |
parent | 8a99429c0dc96a09f1089cc8a851119c128a8120 (diff) | |
download | poky-1f0a763637b5d5dea3ab11d6faeb3d6d0aa3f567.tar.gz |
getting-started: Removed "concepts.xml" file
This file was for a deeper concepts chapter. It will go into the
new Yocto Project Concepts Manual. Removing it required deleting the
*.xml file and updating getting-started.xml to not include it in the
build.
(From yocto-docs rev: 2df213c1cdba8f48918e8240de47c1758352807d)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/getting-started/getting-started-concepts.xml | 1929 | ||||
-rw-r--r-- | documentation/getting-started/getting-started.xml | 4 |
2 files changed, 1 insertions, 1932 deletions
diff --git a/documentation/getting-started/getting-started-concepts.xml b/documentation/getting-started/getting-started-concepts.xml deleted file mode 100644 index 02fc9d08d2..0000000000 --- a/documentation/getting-started/getting-started-concepts.xml +++ /dev/null | |||
@@ -1,1929 +0,0 @@ | |||
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='getting-started-concepts'> | ||
6 | <title>Yocto Project Concepts</title> | ||
7 | |||
8 | <para> | ||
9 | This chapter describes concepts for various areas of the Yocto Project. | ||
10 | Currently, topics include Yocto Project components, cross-development | ||
11 | generation, shared state (sstate) cache, runtime dependencies, | ||
12 | Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses. | ||
13 | </para> | ||
14 | |||
15 | <section id='yocto-project-components'> | ||
16 | <title>Yocto Project Components</title> | ||
17 | |||
18 | <para> | ||
19 | The | ||
20 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> | ||
21 | task executor together with various types of configuration files | ||
22 | form the OpenEmbedded Core. | ||
23 | This section overviews these components by describing their use and | ||
24 | how they interact. | ||
25 | </para> | ||
26 | |||
27 | <para> | ||
28 | BitBake handles the parsing and execution of the data files. | ||
29 | The data itself is of various types: | ||
30 | <itemizedlist> | ||
31 | <listitem><para> | ||
32 | <emphasis>Recipes:</emphasis> | ||
33 | Provides details about particular pieces of software. | ||
34 | </para></listitem> | ||
35 | <listitem><para> | ||
36 | <emphasis>Class Data:</emphasis> | ||
37 | Abstracts common build information (e.g. how to build a | ||
38 | Linux kernel). | ||
39 | </para></listitem> | ||
40 | <listitem><para> | ||
41 | <emphasis>Configuration Data:</emphasis> | ||
42 | Defines machine-specific settings, policy decisions, and | ||
43 | so forth. | ||
44 | Configuration data acts as the glue to bind everything | ||
45 | together. | ||
46 | </para></listitem> | ||
47 | </itemizedlist> | ||
48 | </para> | ||
49 | |||
50 | <para> | ||
51 | BitBake knows how to combine multiple data sources together and | ||
52 | refers to each data source as a layer. | ||
53 | For information on layers, see the | ||
54 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" | ||
55 | section of the Yocto Project Development Tasks Manual. | ||
56 | </para> | ||
57 | |||
58 | <para> | ||
59 | Following are some brief details on these core components. | ||
60 | For additional information on how these components interact during | ||
61 | a build, see the | ||
62 | "<link linkend='development-concepts'>Development Concepts</link>" | ||
63 | section. | ||
64 | </para> | ||
65 | |||
66 | <section id='usingpoky-components-bitbake'> | ||
67 | <title>BitBake</title> | ||
68 | |||
69 | <para> | ||
70 | BitBake is the tool at the heart of the OpenEmbedded build | ||
71 | system and is responsible for parsing the | ||
72 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, | ||
73 | generating a list of tasks from it, and then executing those | ||
74 | tasks. | ||
75 | </para> | ||
76 | |||
77 | <para> | ||
78 | This section briefly introduces BitBake. | ||
79 | If you want more information on BitBake, see the | ||
80 | <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. | ||
81 | </para> | ||
82 | |||
83 | <para> | ||
84 | To see a list of the options BitBake supports, use either of | ||
85 | the following commands: | ||
86 | <literallayout class='monospaced'> | ||
87 | $ bitbake -h | ||
88 | $ bitbake --help | ||
89 | </literallayout> | ||
90 | </para> | ||
91 | |||
92 | <para> | ||
93 | The most common usage for BitBake is | ||
94 | <filename>bitbake <replaceable>packagename</replaceable></filename>, | ||
95 | where <filename>packagename</filename> is the name of the | ||
96 | package you want to build (referred to as the "target" in this | ||
97 | manual). | ||
98 | The target often equates to the first part of a recipe's | ||
99 | filename (e.g. "foo" for a recipe named | ||
100 | <filename>foo_1.3.0-r0.bb</filename>). | ||
101 | So, to process the | ||
102 | <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you | ||
103 | might type the following: | ||
104 | <literallayout class='monospaced'> | ||
105 | $ bitbake matchbox-desktop | ||
106 | </literallayout> | ||
107 | Several different versions of | ||
108 | <filename>matchbox-desktop</filename> might exist. | ||
109 | BitBake chooses the one selected by the distribution | ||
110 | configuration. | ||
111 | You can get more details about how BitBake chooses between | ||
112 | different target versions and providers in the | ||
113 | "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>" | ||
114 | section of the BitBake User Manual. | ||
115 | </para> | ||
116 | |||
117 | <para> | ||
118 | BitBake also tries to execute any dependent tasks first. | ||
119 | So for example, before building | ||
120 | <filename>matchbox-desktop</filename>, BitBake would build a | ||
121 | cross compiler and <filename>glibc</filename> if they had not | ||
122 | already been built. | ||
123 | </para> | ||
124 | |||
125 | <para> | ||
126 | A useful BitBake option to consider is the | ||
127 | <filename>-k</filename> or <filename>--continue</filename> | ||
128 | option. | ||
129 | This option instructs BitBake to try and continue processing | ||
130 | the job as long as possible even after encountering an error. | ||
131 | When an error occurs, the target that failed and those that | ||
132 | depend on it cannot be remade. | ||
133 | However, when you use this option other dependencies can | ||
134 | still be processed. | ||
135 | </para> | ||
136 | </section> | ||
137 | |||
138 | <section id='usingpoky-components-metadata'> | ||
139 | <title>Metadata (Recipes)</title> | ||
140 | |||
141 | <para> | ||
142 | Files that have the <filename>.bb</filename> suffix are | ||
143 | "recipes" files. | ||
144 | In general, a recipe contains information about a single piece | ||
145 | of software. | ||
146 | This information includes the location from which to download | ||
147 | the unaltered source, any source patches to be applied to that | ||
148 | source (if needed), which special configuration options to | ||
149 | apply, how to compile the source files, and how to package the | ||
150 | compiled output. | ||
151 | </para> | ||
152 | |||
153 | <para> | ||
154 | The term "package" is sometimes used to refer to recipes. | ||
155 | However, since the word "package" is used for the packaged | ||
156 | output from the OpenEmbedded build system (i.e. | ||
157 | <filename>.ipk</filename> or <filename>.deb</filename> files), | ||
158 | this document avoids using the term "package" when referring | ||
159 | to recipes. | ||
160 | </para> | ||
161 | </section> | ||
162 | |||
163 | <section id='metadata-virtual-providers'> | ||
164 | <title>Metadata (Virtual Providers)</title> | ||
165 | |||
166 | <para> | ||
167 | Prior to the build, if you know that several different recipes | ||
168 | provide the same functionality, you can use a virtual provider | ||
169 | (i.e. <filename>virtual/*</filename>) as a placeholder for the | ||
170 | actual provider. | ||
171 | The actual provider would be determined at build time. | ||
172 | In this case, you should add <filename>virtual/*</filename> | ||
173 | to | ||
174 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, | ||
175 | rather than listing the specified provider. | ||
176 | You would select the actual provider by setting the | ||
177 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> | ||
178 | variable (i.e. | ||
179 | <filename>PREFERRED_PROVIDER_virtual/*</filename>) | ||
180 | in the build's configuration file (e.g. | ||
181 | <filename>poky/build/conf/local.conf</filename>). | ||
182 | <note> | ||
183 | Any recipe that PROVIDES a <filename>virtual/*</filename> | ||
184 | item that is ultimately not selected through | ||
185 | <filename>PREFERRED_PROVIDER</filename> does not get built. | ||
186 | Preventing these recipes from building is usually the | ||
187 | desired behavior since this mechanism's purpose is to | ||
188 | select between mutually exclusive alternative providers. | ||
189 | </note> | ||
190 | </para> | ||
191 | |||
192 | <para> | ||
193 | The following lists specific examples of virtual providers: | ||
194 | <itemizedlist> | ||
195 | <listitem><para> | ||
196 | <filename>virtual/mesa</filename>: | ||
197 | Provides <filename>gbm.pc</filename>. | ||
198 | </para></listitem> | ||
199 | <listitem><para> | ||
200 | <filename>virtual/egl</filename>: | ||
201 | Provides <filename>egl.pc</filename> and possibly | ||
202 | <filename>wayland-egl.pc</filename>. | ||
203 | </para></listitem> | ||
204 | <listitem><para> | ||
205 | <filename>virtual/libgl</filename>: | ||
206 | Provides <filename>gl.pc</filename> (i.e. libGL). | ||
207 | </para></listitem> | ||
208 | <listitem><para> | ||
209 | <filename>virtual/libgles1</filename>: | ||
210 | Provides <filename>glesv1_cm.pc</filename> | ||
211 | (i.e. libGLESv1_CM). | ||
212 | </para></listitem> | ||
213 | <listitem><para> | ||
214 | <filename>virtual/libgles2</filename>: | ||
215 | Provides <filename>glesv2.pc</filename> | ||
216 | (i.e. libGLESv2). | ||
217 | </para></listitem> | ||
218 | </itemizedlist> | ||
219 | </para> | ||
220 | </section> | ||
221 | |||
222 | <section id='usingpoky-components-classes'> | ||
223 | <title>Classes</title> | ||
224 | |||
225 | <para> | ||
226 | Class files (<filename>.bbclass</filename>) contain information | ||
227 | that is useful to share between | ||
228 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> | ||
229 | files. | ||
230 | An example is the | ||
231 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> | ||
232 | class, which contains common settings for any application that | ||
233 | Autotools uses. | ||
234 | The | ||
235 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" | ||
236 | chapter in the Yocto Project Reference Manual provides | ||
237 | details about classes and how to use them. | ||
238 | </para> | ||
239 | </section> | ||
240 | |||
241 | <section id='usingpoky-components-configuration'> | ||
242 | <title>Configuration</title> | ||
243 | |||
244 | <para> | ||
245 | The configuration files (<filename>.conf</filename>) define | ||
246 | various configuration variables that govern the OpenEmbedded | ||
247 | build process. | ||
248 | These files fall into several areas that define machine | ||
249 | configuration options, distribution configuration options, | ||
250 | compiler tuning options, general common configuration options, | ||
251 | and user configuration options in | ||
252 | <filename>local.conf</filename>, which is found in the | ||
253 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. | ||
254 | </para> | ||
255 | </section> | ||
256 | </section> | ||
257 | |||
258 | <section id="cross-development-toolchain-generation"> | ||
259 | <title>Cross-Development Toolchain Generation</title> | ||
260 | |||
261 | <para> | ||
262 | The Yocto Project does most of the work for you when it comes to | ||
263 | creating | ||
264 | <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>. | ||
265 | This section provides some technical background on how | ||
266 | cross-development toolchains are created and used. | ||
267 | For more information on toolchains, you can also see the | ||
268 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
269 | manual. | ||
270 | </para> | ||
271 | |||
272 | <para> | ||
273 | In the Yocto Project development environment, cross-development | ||
274 | toolchains are used to build the image and applications that run | ||
275 | on the target hardware. | ||
276 | With just a few commands, the OpenEmbedded build system creates | ||
277 | these necessary toolchains for you. | ||
278 | </para> | ||
279 | |||
280 | <para> | ||
281 | The following figure shows a high-level build environment regarding | ||
282 | toolchain construction and use. | ||
283 | </para> | ||
284 | |||
285 | <para> | ||
286 | <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" /> | ||
287 | </para> | ||
288 | |||
289 | <para> | ||
290 | Most of the work occurs on the Build Host. | ||
291 | This is the machine used to build images and generally work within the | ||
292 | the Yocto Project environment. | ||
293 | When you run BitBake to create an image, the OpenEmbedded build system | ||
294 | uses the host <filename>gcc</filename> compiler to bootstrap a | ||
295 | cross-compiler named <filename>gcc-cross</filename>. | ||
296 | The <filename>gcc-cross</filename> compiler is what BitBake uses to | ||
297 | compile source files when creating the target image. | ||
298 | You can think of <filename>gcc-cross</filename> simply as an | ||
299 | automatically generated cross-compiler that is used internally within | ||
300 | BitBake only. | ||
301 | <note> | ||
302 | The extensible SDK does not use | ||
303 | <filename>gcc-cross-canadian</filename> since this SDK | ||
304 | ships a copy of the OpenEmbedded build system and the sysroot | ||
305 | within it contains <filename>gcc-cross</filename>. | ||
306 | </note> | ||
307 | </para> | ||
308 | |||
309 | <para> | ||
310 | The chain of events that occurs when <filename>gcc-cross</filename> is | ||
311 | bootstrapped is as follows: | ||
312 | <literallayout class='monospaced'> | ||
313 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
314 | </literallayout> | ||
315 | <itemizedlist> | ||
316 | <listitem><para> | ||
317 | <filename>gcc</filename>: | ||
318 | The build host's GNU Compiler Collection (GCC). | ||
319 | </para></listitem> | ||
320 | <listitem><para> | ||
321 | <filename>binutils-cross</filename>: | ||
322 | The bare minimum binary utilities needed in order to run | ||
323 | the <filename>gcc-cross-initial</filename> phase of the | ||
324 | bootstrap operation. | ||
325 | </para></listitem> | ||
326 | <listitem><para> | ||
327 | <filename>gcc-cross-initial</filename>: | ||
328 | An early stage of the bootstrap process for creating | ||
329 | the cross-compiler. | ||
330 | This stage builds enough of the <filename>gcc-cross</filename>, | ||
331 | the C library, and other pieces needed to finish building the | ||
332 | final cross-compiler in later stages. | ||
333 | This tool is a "native" package (i.e. it is designed to run on | ||
334 | the build host). | ||
335 | </para></listitem> | ||
336 | <listitem><para> | ||
337 | <filename>linux-libc-headers</filename>: | ||
338 | Headers needed for the cross-compiler. | ||
339 | </para></listitem> | ||
340 | <listitem><para> | ||
341 | <filename>glibc-initial</filename>: | ||
342 | An initial version of the Embedded GLIBC needed to bootstrap | ||
343 | <filename>glibc</filename>. | ||
344 | </para></listitem> | ||
345 | <listitem><para> | ||
346 | <filename>gcc-cross</filename>: | ||
347 | The final stage of the bootstrap process for the | ||
348 | cross-compiler. | ||
349 | This stage results in the actual cross-compiler that | ||
350 | BitBake uses when it builds an image for a targeted | ||
351 | device. | ||
352 | <note> | ||
353 | If you are replacing this cross compiler toolchain | ||
354 | with a custom version, you must replace | ||
355 | <filename>gcc-cross</filename>. | ||
356 | </note> | ||
357 | This tool is also a "native" package (i.e. it is | ||
358 | designed to run on the build host). | ||
359 | </para></listitem> | ||
360 | <listitem><para> | ||
361 | <filename>gcc-runtime</filename>: | ||
362 | Runtime libraries resulting from the toolchain bootstrapping | ||
363 | process. | ||
364 | This tool produces a binary that consists of the | ||
365 | runtime libraries need for the targeted device. | ||
366 | </para></listitem> | ||
367 | </itemizedlist> | ||
368 | </para> | ||
369 | |||
370 | <para> | ||
371 | You can use the OpenEmbedded build system to build an installer for | ||
372 | the relocatable SDK used to develop applications. | ||
373 | When you run the installer, it installs the toolchain, which contains | ||
374 | the development tools (e.g., the | ||
375 | <filename>gcc-cross-canadian</filename>), | ||
376 | <filename>binutils-cross-canadian</filename>, and other | ||
377 | <filename>nativesdk-*</filename> tools, | ||
378 | which are tools native to the SDK (i.e. native to | ||
379 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>), | ||
380 | you need to cross-compile and test your software. | ||
381 | The figure shows the commands you use to easily build out this | ||
382 | toolchain. | ||
383 | This cross-development toolchain is built to execute on the | ||
384 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
385 | which might or might not be the same | ||
386 | machine as the Build Host. | ||
387 | <note> | ||
388 | If your target architecture is supported by the Yocto Project, | ||
389 | you can take advantage of pre-built images that ship with the | ||
390 | Yocto Project and already contain cross-development toolchain | ||
391 | installers. | ||
392 | </note> | ||
393 | </para> | ||
394 | |||
395 | <para> | ||
396 | Here is the bootstrap process for the relocatable toolchain: | ||
397 | <literallayout class='monospaced'> | ||
398 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | ||
399 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
400 | </literallayout> | ||
401 | <itemizedlist> | ||
402 | <listitem><para> | ||
403 | <filename>gcc</filename>: | ||
404 | The build host's GNU Compiler Collection (GCC). | ||
405 | </para></listitem> | ||
406 | <listitem><para> | ||
407 | <filename>binutils-crosssdk</filename>: | ||
408 | The bare minimum binary utilities needed in order to run | ||
409 | the <filename>gcc-crosssdk-initial</filename> phase of the | ||
410 | bootstrap operation. | ||
411 | </para></listitem> | ||
412 | <listitem><para> | ||
413 | <filename>gcc-crosssdk-initial</filename>: | ||
414 | An early stage of the bootstrap process for creating | ||
415 | the cross-compiler. | ||
416 | This stage builds enough of the | ||
417 | <filename>gcc-crosssdk</filename> and supporting pieces so that | ||
418 | the final stage of the bootstrap process can produce the | ||
419 | finished cross-compiler. | ||
420 | This tool is a "native" binary that runs on the build host. | ||
421 | </para></listitem> | ||
422 | <listitem><para> | ||
423 | <filename>linux-libc-headers</filename>: | ||
424 | Headers needed for the cross-compiler. | ||
425 | </para></listitem> | ||
426 | <listitem><para> | ||
427 | <filename>glibc-initial</filename>: | ||
428 | An initial version of the Embedded GLIBC needed to bootstrap | ||
429 | <filename>nativesdk-glibc</filename>. | ||
430 | </para></listitem> | ||
431 | <listitem><para> | ||
432 | <filename>nativesdk-glibc</filename>: | ||
433 | The Embedded GLIBC needed to bootstrap the | ||
434 | <filename>gcc-crosssdk</filename>. | ||
435 | </para></listitem> | ||
436 | <listitem><para> | ||
437 | <filename>gcc-crosssdk</filename>: | ||
438 | The final stage of the bootstrap process for the | ||
439 | relocatable cross-compiler. | ||
440 | The <filename>gcc-crosssdk</filename> is a transitory compiler | ||
441 | and never leaves the build host. | ||
442 | Its purpose is to help in the bootstrap process to create the | ||
443 | eventual relocatable <filename>gcc-cross-canadian</filename> | ||
444 | compiler, which is relocatable. | ||
445 | This tool is also a "native" package (i.e. it is | ||
446 | designed to run on the build host). | ||
447 | </para></listitem> | ||
448 | <listitem><para> | ||
449 | <filename>gcc-cross-canadian</filename>: | ||
450 | The final relocatable cross-compiler. | ||
451 | When run on the | ||
452 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>, | ||
453 | this tool | ||
454 | produces executable code that runs on the target device. | ||
455 | Only one cross-canadian compiler is produced per architecture | ||
456 | since they can be targeted at different processor optimizations | ||
457 | using configurations passed to the compiler through the | ||
458 | compile commands. | ||
459 | This circumvents the need for multiple compilers and thus | ||
460 | reduces the size of the toolchains. | ||
461 | </para></listitem> | ||
462 | </itemizedlist> | ||
463 | </para> | ||
464 | |||
465 | <note> | ||
466 | For information on advantages gained when building a | ||
467 | cross-development toolchain installer, see the | ||
468 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" | ||
469 | section in the Yocto Project Application Development and the | ||
470 | Extensible Software Development Kit (eSDK) manual. | ||
471 | </note> | ||
472 | </section> | ||
473 | |||
474 | |||
475 | |||
476 | |||
477 | <section id="shared-state-cache"> | ||
478 | <title>Shared State Cache</title> | ||
479 | |||
480 | <para> | ||
481 | By design, the OpenEmbedded build system builds everything from | ||
482 | scratch unless BitBake can determine that parts do not need to be | ||
483 | rebuilt. | ||
484 | Fundamentally, building from scratch is attractive as it means all | ||
485 | parts are built fresh and there is no possibility of stale data | ||
486 | causing problems. | ||
487 | When developers hit problems, they typically default back to | ||
488 | building from scratch so they know the state of things from the | ||
489 | start. | ||
490 | </para> | ||
491 | |||
492 | <para> | ||
493 | Building an image from scratch is both an advantage and a | ||
494 | disadvantage to the process. | ||
495 | As mentioned in the previous paragraph, building from scratch | ||
496 | ensures that everything is current and starts from a known state. | ||
497 | However, building from scratch also takes much longer as it | ||
498 | generally means rebuilding things that do not necessarily need | ||
499 | to be rebuilt. | ||
500 | </para> | ||
501 | |||
502 | <para> | ||
503 | The Yocto Project implements shared state code that supports | ||
504 | incremental builds. | ||
505 | The implementation of the shared state code answers the following | ||
506 | questions that were fundamental roadblocks within the OpenEmbedded | ||
507 | incremental build support system: | ||
508 | <itemizedlist> | ||
509 | <listitem><para> | ||
510 | What pieces of the system have changed and what pieces have | ||
511 | not changed? | ||
512 | </para></listitem> | ||
513 | <listitem><para> | ||
514 | How are changed pieces of software removed and replaced? | ||
515 | </para></listitem> | ||
516 | <listitem><para> | ||
517 | How are pre-built components that do not need to be rebuilt | ||
518 | from scratch used when they are available? | ||
519 | </para></listitem> | ||
520 | </itemizedlist> | ||
521 | </para> | ||
522 | |||
523 | <para> | ||
524 | For the first question, the build system detects changes in the | ||
525 | "inputs" to a given task by creating a checksum (or signature) of | ||
526 | the task's inputs. | ||
527 | If the checksum changes, the system assumes the inputs have changed | ||
528 | and the task needs to be rerun. | ||
529 | For the second question, the shared state (sstate) code tracks | ||
530 | which tasks add which output to the build process. | ||
531 | This means the output from a given task can be removed, upgraded | ||
532 | or otherwise manipulated. | ||
533 | The third question is partly addressed by the solution for the | ||
534 | second question assuming the build system can fetch the sstate | ||
535 | objects from remote locations and install them if they are deemed | ||
536 | to be valid. | ||
537 | <note> | ||
538 | The OpenEmbedded build system does not maintain | ||
539 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
540 | information as part of the shared state packages. | ||
541 | Consequently, considerations exist that affect maintaining | ||
542 | shared state feeds. | ||
543 | For information on how the OpenEmbedded build system | ||
544 | works with packages and can track incrementing | ||
545 | <filename>PR</filename> information, see the | ||
546 | "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" | ||
547 | section in the Yocto Project Development Tasks Manual. | ||
548 | </note> | ||
549 | </para> | ||
550 | |||
551 | <para> | ||
552 | The rest of this section goes into detail about the overall | ||
553 | incremental build architecture, the checksums (signatures), shared | ||
554 | state, and some tips and tricks. | ||
555 | </para> | ||
556 | |||
557 | <section id='overall-architecture'> | ||
558 | <title>Overall Architecture</title> | ||
559 | |||
560 | <para> | ||
561 | When determining what parts of the system need to be built, | ||
562 | BitBake works on a per-task basis rather than a per-recipe | ||
563 | basis. | ||
564 | You might wonder why using a per-task basis is preferred over | ||
565 | a per-recipe basis. | ||
566 | To help explain, consider having the IPK packaging backend | ||
567 | enabled and then switching to DEB. | ||
568 | In this case, the | ||
569 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
570 | and | ||
571 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
572 | task outputs are still valid. | ||
573 | However, with a per-recipe approach, the build would not | ||
574 | include the <filename>.deb</filename> files. | ||
575 | Consequently, you would have to invalidate the whole build and | ||
576 | rerun it. | ||
577 | Rerunning everything is not the best solution. | ||
578 | Also, in this case, the core must be "taught" much about | ||
579 | specific tasks. | ||
580 | This methodology does not scale well and does not allow users | ||
581 | to easily add new tasks in layers or as external recipes | ||
582 | without touching the packaged-staging core. | ||
583 | </para> | ||
584 | </section> | ||
585 | |||
586 | <section id='overview-checksums'> | ||
587 | <title>Checksums (Signatures)</title> | ||
588 | |||
589 | <para> | ||
590 | The shared state code uses a checksum, which is a unique | ||
591 | signature of a task's inputs, to determine if a task needs to | ||
592 | be run again. | ||
593 | Because it is a change in a task's inputs that triggers a | ||
594 | rerun, the process needs to detect all the inputs to a given | ||
595 | task. | ||
596 | For shell tasks, this turns out to be fairly easy because | ||
597 | the build process generates a "run" shell script for each task | ||
598 | and it is possible to create a checksum that gives you a good | ||
599 | idea of when the task's data changes. | ||
600 | </para> | ||
601 | |||
602 | <para> | ||
603 | To complicate the problem, there are things that should not be | ||
604 | included in the checksum. | ||
605 | First, there is the actual specific build path of a given | ||
606 | task - the | ||
607 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
608 | It does not matter if the work directory changes because it | ||
609 | should not affect the output for target packages. | ||
610 | Also, the build process has the objective of making native | ||
611 | or cross packages relocatable. | ||
612 | <note> | ||
613 | Both native and cross packages run on the build host. | ||
614 | However, cross packages generate output for the target | ||
615 | architecture. | ||
616 | </note> | ||
617 | The checksum therefore needs to exclude | ||
618 | <filename>WORKDIR</filename>. | ||
619 | The simplistic approach for excluding the work directory is to | ||
620 | set <filename>WORKDIR</filename> to some fixed value and | ||
621 | create the checksum for the "run" script. | ||
622 | </para> | ||
623 | |||
624 | <para> | ||
625 | Another problem results from the "run" scripts containing | ||
626 | functions that might or might not get called. | ||
627 | The incremental build solution contains code that figures out | ||
628 | dependencies between shell functions. | ||
629 | This code is used to prune the "run" scripts down to the | ||
630 | minimum set, thereby alleviating this problem and making the | ||
631 | "run" scripts much more readable as a bonus. | ||
632 | </para> | ||
633 | |||
634 | <para> | ||
635 | So far we have solutions for shell scripts. | ||
636 | What about Python tasks? | ||
637 | The same approach applies even though these tasks are more | ||
638 | difficult. | ||
639 | The process needs to figure out what variables a Python | ||
640 | function accesses and what functions it calls. | ||
641 | Again, the incremental build solution contains code that first | ||
642 | figures out the variable and function dependencies, and then | ||
643 | creates a checksum for the data used as the input to the task. | ||
644 | </para> | ||
645 | |||
646 | <para> | ||
647 | Like the <filename>WORKDIR</filename> case, situations exist | ||
648 | where dependencies should be ignored. | ||
649 | For these cases, you can instruct the build process to | ||
650 | ignore a dependency by using a line like the following: | ||
651 | <literallayout class='monospaced'> | ||
652 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" | ||
653 | </literallayout> | ||
654 | This example ensures that the | ||
655 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></ulink> | ||
656 | variable does not depend on the value of | ||
657 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, | ||
658 | even if it does reference it. | ||
659 | </para> | ||
660 | |||
661 | <para> | ||
662 | Equally, there are cases where we need to add dependencies | ||
663 | BitBake is not able to find. | ||
664 | You can accomplish this by using a line like the following: | ||
665 | <literallayout class='monospaced'> | ||
666 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
667 | </literallayout> | ||
668 | This example explicitly adds the <filename>MACHINE</filename> | ||
669 | variable as a dependency for | ||
670 | <filename>PACKAGE_ARCHS</filename>. | ||
671 | </para> | ||
672 | |||
673 | <para> | ||
674 | Consider a case with in-line Python, for example, where | ||
675 | BitBake is not able to figure out dependencies. | ||
676 | When running in debug mode (i.e. using | ||
677 | <filename>-DDD</filename>), BitBake produces output when it | ||
678 | discovers something for which it cannot figure out dependencies. | ||
679 | The Yocto Project team has currently not managed to cover | ||
680 | those dependencies in detail and is aware of the need to fix | ||
681 | this situation. | ||
682 | </para> | ||
683 | |||
684 | <para> | ||
685 | Thus far, this section has limited discussion to the direct | ||
686 | inputs into a task. | ||
687 | Information based on direct inputs is referred to as the | ||
688 | "basehash" in the code. | ||
689 | However, there is still the question of a task's indirect | ||
690 | inputs - the things that were already built and present in the | ||
691 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. | ||
692 | The checksum (or signature) for a particular task needs to add | ||
693 | the hashes of all the tasks on which the particular task | ||
694 | depends. | ||
695 | Choosing which dependencies to add is a policy decision. | ||
696 | However, the effect is to generate a master checksum that | ||
697 | combines the basehash and the hashes of the task's | ||
698 | dependencies. | ||
699 | </para> | ||
700 | |||
701 | <para> | ||
702 | At the code level, there are a variety of ways both the | ||
703 | basehash and the dependent task hashes can be influenced. | ||
704 | Within the BitBake configuration file, we can give BitBake | ||
705 | some extra information to help it construct the basehash. | ||
706 | The following statement effectively results in a list of | ||
707 | global variable dependency excludes - variables never | ||
708 | included in any checksum: | ||
709 | <literallayout class='monospaced'> | ||
710 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ | ||
711 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ | ||
712 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ | ||
713 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ | ||
714 | CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" | ||
715 | </literallayout> | ||
716 | The previous example excludes | ||
717 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> | ||
718 | since that variable is actually constructed as a path within | ||
719 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, | ||
720 | which is on the whitelist. | ||
721 | </para> | ||
722 | |||
723 | <para> | ||
724 | The rules for deciding which hashes of dependent tasks to | ||
725 | include through dependency chains are more complex and are | ||
726 | generally accomplished with a Python function. | ||
727 | The code in <filename>meta/lib/oe/sstatesig.py</filename> shows | ||
728 | two examples of this and also illustrates how you can insert | ||
729 | your own policy into the system if so desired. | ||
730 | This file defines the two basic signature generators | ||
731 | <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink> | ||
732 | uses: "OEBasic" and "OEBasicHash". | ||
733 | By default, there is a dummy "noop" signature handler enabled | ||
734 | in BitBake. | ||
735 | This means that behavior is unchanged from previous versions. | ||
736 | OE-Core uses the "OEBasicHash" signature handler by default | ||
737 | through this setting in the <filename>bitbake.conf</filename> | ||
738 | file: | ||
739 | <literallayout class='monospaced'> | ||
740 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | ||
741 | </literallayout> | ||
742 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> | ||
743 | is the same as the "OEBasic" version but adds the task hash to | ||
744 | the stamp files. | ||
745 | This results in any | ||
746 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> | ||
747 | change that changes the task hash, automatically | ||
748 | causing the task to be run again. | ||
749 | This removes the need to bump | ||
750 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> | ||
751 | values, and changes to Metadata automatically ripple across | ||
752 | the build. | ||
753 | </para> | ||
754 | |||
755 | <para> | ||
756 | It is also worth noting that the end result of these | ||
757 | signature generators is to make some dependency and hash | ||
758 | information available to the build. | ||
759 | This information includes: | ||
760 | <itemizedlist> | ||
761 | <listitem><para> | ||
762 | <filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>: | ||
763 | The base hashes for each task in the recipe. | ||
764 | </para></listitem> | ||
765 | <listitem><para> | ||
766 | <filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: | ||
767 | The base hashes for each dependent task. | ||
768 | </para></listitem> | ||
769 | <listitem><para> | ||
770 | <filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: | ||
771 | The task dependencies for each task. | ||
772 | </para></listitem> | ||
773 | <listitem><para> | ||
774 | <filename>BB_TASKHASH</filename>: | ||
775 | The hash of the currently running task. | ||
776 | </para></listitem> | ||
777 | </itemizedlist> | ||
778 | </para> | ||
779 | </section> | ||
780 | |||
781 | <section id='shared-state'> | ||
782 | <title>Shared State</title> | ||
783 | |||
784 | <para> | ||
785 | Checksums and dependencies, as discussed in the previous | ||
786 | section, solve half the problem of supporting a shared state. | ||
787 | The other part of the problem is being able to use checksum | ||
788 | information during the build and being able to reuse or rebuild | ||
789 | specific components. | ||
790 | </para> | ||
791 | |||
792 | <para> | ||
793 | The | ||
794 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink> | ||
795 | class is a relatively generic implementation of how to | ||
796 | "capture" a snapshot of a given task. | ||
797 | The idea is that the build process does not care about the | ||
798 | source of a task's output. | ||
799 | Output could be freshly built or it could be downloaded and | ||
800 | unpacked from somewhere - the build process does not need to | ||
801 | worry about its origin. | ||
802 | </para> | ||
803 | |||
804 | <para> | ||
805 | There are two types of output, one is just about creating a | ||
806 | directory in | ||
807 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
808 | A good example is the output of either | ||
809 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> | ||
810 | or | ||
811 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>. | ||
812 | The other type of output occurs when a set of data is merged | ||
813 | into a shared directory tree such as the sysroot. | ||
814 | </para> | ||
815 | |||
816 | <para> | ||
817 | The Yocto Project team has tried to keep the details of the | ||
818 | implementation hidden in <filename>sstate</filename> class. | ||
819 | From a user's perspective, adding shared state wrapping to a task | ||
820 | is as simple as this | ||
821 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink> | ||
822 | example taken from the | ||
823 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink> | ||
824 | class: | ||
825 | <literallayout class='monospaced'> | ||
826 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
827 | SSTATETASKS += "do_deploy" | ||
828 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | ||
829 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" | ||
830 | |||
831 | python do_deploy_setscene () { | ||
832 | sstate_setscene(d) | ||
833 | } | ||
834 | addtask do_deploy_setscene | ||
835 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" | ||
836 | </literallayout> | ||
837 | The following list explains the previous example: | ||
838 | <itemizedlist> | ||
839 | <listitem><para> | ||
840 | Adding "do_deploy" to <filename>SSTATETASKS</filename> | ||
841 | adds some required sstate-related processing, which is | ||
842 | implemented in the | ||
843 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink> | ||
844 | class, to before and after the | ||
845 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink> | ||
846 | task. | ||
847 | </para></listitem> | ||
848 | <listitem><para> | ||
849 | The | ||
850 | <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename> | ||
851 | declares that <filename>do_deploy</filename> places its | ||
852 | output in <filename>${DEPLOYDIR}</filename> when run | ||
853 | normally (i.e. when not using the sstate cache). | ||
854 | This output becomes the input to the shared state cache. | ||
855 | </para></listitem> | ||
856 | <listitem><para> | ||
857 | The | ||
858 | <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename> | ||
859 | line causes the contents of the shared state cache to be | ||
860 | copied to <filename>${DEPLOY_DIR_IMAGE}</filename>. | ||
861 | <note> | ||
862 | If <filename>do_deploy</filename> is not already in | ||
863 | the shared state cache or if its input checksum | ||
864 | (signature) has changed from when the output was | ||
865 | cached, the task will be run to populate the shared | ||
866 | state cache, after which the contents of the shared | ||
867 | state cache is copied to | ||
868 | <filename>${DEPLOY_DIR_IMAGE}</filename>. | ||
869 | If <filename>do_deploy</filename> is in the shared | ||
870 | state cache and its signature indicates that the | ||
871 | cached output is still valid (i.e. if no | ||
872 | relevant task inputs have changed), then the | ||
873 | contents of the shared state cache will be copied | ||
874 | directly to | ||
875 | <filename>${DEPLOY_DIR_IMAGE}</filename> by the | ||
876 | <filename>do_deploy_setscene</filename> task | ||
877 | instead, skipping the | ||
878 | <filename>do_deploy</filename> task. | ||
879 | </note> | ||
880 | </para></listitem> | ||
881 | <listitem><para> | ||
882 | The following task definition is glue logic needed to | ||
883 | make the previous settings effective: | ||
884 | <literallayout class='monospaced'> | ||
885 | python do_deploy_setscene () { | ||
886 | sstate_setscene(d) | ||
887 | } | ||
888 | addtask do_deploy_setscene | ||
889 | </literallayout> | ||
890 | <filename>sstate_setscene()</filename> takes the flags | ||
891 | above as input and accelerates the | ||
892 | <filename>do_deploy</filename> task through the | ||
893 | shared state cache if possible. | ||
894 | If the task was accelerated, | ||
895 | <filename>sstate_setscene()</filename> returns True. | ||
896 | Otherwise, it returns False, and the normal | ||
897 | <filename>do_deploy</filename> task runs. | ||
898 | For more information, see the | ||
899 | "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>" | ||
900 | section in the BitBake User Manual. | ||
901 | </para></listitem> | ||
902 | <listitem><para> | ||
903 | The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename> | ||
904 | line creates <filename>${DEPLOYDIR}</filename> and | ||
905 | <filename>${B}</filename> before the | ||
906 | <filename>do_deploy</filename> task runs, and also sets | ||
907 | the current working directory of | ||
908 | <filename>do_deploy</filename> to | ||
909 | <filename>${B}</filename>. | ||
910 | For more information, see the | ||
911 | "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" | ||
912 | section in the BitBake User Manual. | ||
913 | <note> | ||
914 | In cases where | ||
915 | <filename>sstate-inputdirs</filename> and | ||
916 | <filename>sstate-outputdirs</filename> would be the | ||
917 | same, you can use | ||
918 | <filename>sstate-plaindirs</filename>. | ||
919 | For example, to preserve the | ||
920 | <filename>${PKGD}</filename> and | ||
921 | <filename>${PKGDEST}</filename> output from the | ||
922 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
923 | task, use the following: | ||
924 | <literallayout class='monospaced'> | ||
925 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | ||
926 | </literallayout> | ||
927 | </note> | ||
928 | </para></listitem> | ||
929 | <listitem><para> | ||
930 | <filename>sstate-inputdirs</filename> and | ||
931 | <filename>sstate-outputdirs</filename> can also be used | ||
932 | with multiple directories. | ||
933 | For example, the following declares | ||
934 | <filename>PKGDESTWORK</filename> and | ||
935 | <filename>SHLIBWORK</filename> as shared state | ||
936 | input directories, which populates the shared state | ||
937 | cache, and <filename>PKGDATA_DIR</filename> and | ||
938 | <filename>SHLIBSDIR</filename> as the corresponding | ||
939 | shared state output directories: | ||
940 | <literallayout class='monospaced'> | ||
941 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
942 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
943 | </literallayout> | ||
944 | </para></listitem> | ||
945 | <listitem><para> | ||
946 | These methods also include the ability to take a | ||
947 | lockfile when manipulating shared state directory | ||
948 | structures, for cases where file additions or removals | ||
949 | are sensitive: | ||
950 | <literallayout class='monospaced'> | ||
951 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
952 | </literallayout> | ||
953 | </para></listitem> | ||
954 | </itemizedlist> | ||
955 | </para> | ||
956 | |||
957 | <para> | ||
958 | Behind the scenes, the shared state code works by looking in | ||
959 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink> | ||
960 | and | ||
961 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink> | ||
962 | for shared state files. | ||
963 | Here is an example: | ||
964 | <literallayout class='monospaced'> | ||
965 | SSTATE_MIRRORS ?= "\ | ||
966 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
967 | file://.* file:///some/local/dir/sstate/PATH" | ||
968 | </literallayout> | ||
969 | <note> | ||
970 | The shared state directory | ||
971 | (<filename>SSTATE_DIR</filename>) is organized into | ||
972 | two-character subdirectories, where the subdirectory | ||
973 | names are based on the first two characters of the hash. | ||
974 | If the shared state directory structure for a mirror has the | ||
975 | same structure as <filename>SSTATE_DIR</filename>, you must | ||
976 | specify "PATH" as part of the URI to enable the build system | ||
977 | to map to the appropriate subdirectory. | ||
978 | </note> | ||
979 | </para> | ||
980 | |||
981 | <para> | ||
982 | The shared state package validity can be detected just by | ||
983 | looking at the filename since the filename contains the task | ||
984 | checksum (or signature) as described earlier in this section. | ||
985 | If a valid shared state package is found, the build process | ||
986 | downloads it and uses it to accelerate the task. | ||
987 | </para> | ||
988 | |||
989 | <para> | ||
990 | The build processes use the <filename>*_setscene</filename> | ||
991 | tasks for the task acceleration phase. | ||
992 | BitBake goes through this phase before the main execution | ||
993 | code and tries to accelerate any tasks for which it can find | ||
994 | shared state packages. | ||
995 | If a shared state package for a task is available, the | ||
996 | shared state package is used. | ||
997 | This means the task and any tasks on which it is dependent | ||
998 | are not executed. | ||
999 | </para> | ||
1000 | |||
1001 | <para> | ||
1002 | As a real world example, the aim is when building an IPK-based | ||
1003 | image, only the | ||
1004 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink> | ||
1005 | tasks would have their shared state packages fetched and | ||
1006 | extracted. | ||
1007 | Since the sysroot is not used, it would never get extracted. | ||
1008 | This is another reason why a task-based approach is preferred | ||
1009 | over a recipe-based approach, which would have to install the | ||
1010 | output from every task. | ||
1011 | </para> | ||
1012 | </section> | ||
1013 | |||
1014 | <section id='tips-and-tricks'> | ||
1015 | <title>Tips and Tricks</title> | ||
1016 | |||
1017 | <para> | ||
1018 | The code in the build system that supports incremental builds | ||
1019 | is not simple code. | ||
1020 | This section presents some tips and tricks that help you work | ||
1021 | around issues related to shared state code. | ||
1022 | </para> | ||
1023 | |||
1024 | <section id='overview-debugging'> | ||
1025 | <title>Debugging</title> | ||
1026 | |||
1027 | <para> | ||
1028 | Seeing what metadata went into creating the input signature | ||
1029 | of a shared state (sstate) task can be a useful debugging | ||
1030 | aid. | ||
1031 | This information is available in signature information | ||
1032 | (<filename>siginfo</filename>) files in | ||
1033 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>. | ||
1034 | For information on how to view and interpret information in | ||
1035 | <filename>siginfo</filename> files, see the | ||
1036 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>" | ||
1037 | section in the Yocto Project Development Tasks Manual. | ||
1038 | </para> | ||
1039 | </section> | ||
1040 | |||
1041 | <section id='invalidating-shared-state'> | ||
1042 | <title>Invalidating Shared State</title> | ||
1043 | |||
1044 | <para> | ||
1045 | The OpenEmbedded build system uses checksums and shared | ||
1046 | state cache to avoid unnecessarily rebuilding tasks. | ||
1047 | Collectively, this scheme is known as "shared state code." | ||
1048 | </para> | ||
1049 | |||
1050 | <para> | ||
1051 | As with all schemes, this one has some drawbacks. | ||
1052 | It is possible that you could make implicit changes to your | ||
1053 | code that the checksum calculations do not take into | ||
1054 | account. | ||
1055 | These implicit changes affect a task's output but do not | ||
1056 | trigger the shared state code into rebuilding a recipe. | ||
1057 | Consider an example during which a tool changes its output. | ||
1058 | Assume that the output of <filename>rpmdeps</filename> | ||
1059 | changes. | ||
1060 | The result of the change should be that all the | ||
1061 | <filename>package</filename> and | ||
1062 | <filename>package_write_rpm</filename> shared state cache | ||
1063 | items become invalid. | ||
1064 | However, because the change to the output is | ||
1065 | external to the code and therefore implicit, | ||
1066 | the associated shared state cache items do not become | ||
1067 | invalidated. | ||
1068 | In this case, the build process uses the cached items | ||
1069 | rather than running the task again. | ||
1070 | Obviously, these types of implicit changes can cause | ||
1071 | problems. | ||
1072 | </para> | ||
1073 | |||
1074 | <para> | ||
1075 | To avoid these problems during the build, you need to | ||
1076 | understand the effects of any changes you make. | ||
1077 | Realize that changes you make directly to a function | ||
1078 | are automatically factored into the checksum calculation. | ||
1079 | Thus, these explicit changes invalidate the associated | ||
1080 | area of shared state cache. | ||
1081 | However, you need to be aware of any implicit changes that | ||
1082 | are not obvious changes to the code and could affect | ||
1083 | the output of a given task. | ||
1084 | </para> | ||
1085 | |||
1086 | <para> | ||
1087 | When you identify an implicit change, you can easily | ||
1088 | take steps to invalidate the cache and force the tasks | ||
1089 | to run. | ||
1090 | The steps you can take are as simple as changing a | ||
1091 | function's comments in the source code. | ||
1092 | For example, to invalidate package shared state files, | ||
1093 | change the comment statements of | ||
1094 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
1095 | or the comments of one of the functions it calls. | ||
1096 | Even though the change is purely cosmetic, it causes the | ||
1097 | checksum to be recalculated and forces the OpenEmbedded | ||
1098 | build system to run the task again. | ||
1099 | <note> | ||
1100 | For an example of a commit that makes a cosmetic | ||
1101 | change to invalidate shared state, see this | ||
1102 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>. | ||
1103 | </note> | ||
1104 | </para> | ||
1105 | </section> | ||
1106 | </section> | ||
1107 | </section> | ||
1108 | |||
1109 | <section id='automatically-added-runtime-dependencies'> | ||
1110 | <title>Automatically Added Runtime Dependencies</title> | ||
1111 | |||
1112 | <para> | ||
1113 | The OpenEmbedded build system automatically adds common types of | ||
1114 | runtime dependencies between packages, which means that you do not | ||
1115 | need to explicitly declare the packages using | ||
1116 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
1117 | Three automatic mechanisms exist (<filename>shlibdeps</filename>, | ||
1118 | <filename>pcdeps</filename>, and <filename>depchains</filename>) | ||
1119 | that handle shared libraries, package configuration (pkg-config) | ||
1120 | modules, and <filename>-dev</filename> and | ||
1121 | <filename>-dbg</filename> packages, respectively. | ||
1122 | For other types of runtime dependencies, you must manually declare | ||
1123 | the dependencies. | ||
1124 | <itemizedlist> | ||
1125 | <listitem><para> | ||
1126 | <filename>shlibdeps</filename>: | ||
1127 | During the | ||
1128 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
1129 | task of each recipe, all shared libraries installed by the | ||
1130 | recipe are located. | ||
1131 | For each shared library, the package that contains the | ||
1132 | shared library is registered as providing the shared | ||
1133 | library. | ||
1134 | More specifically, the package is registered as providing | ||
1135 | the | ||
1136 | <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink> | ||
1137 | of the library. | ||
1138 | The resulting shared-library-to-package mapping | ||
1139 | is saved globally in | ||
1140 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
1141 | by the | ||
1142 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1143 | task.</para> | ||
1144 | |||
1145 | <para>Simultaneously, all executables and shared libraries | ||
1146 | installed by the recipe are inspected to see what shared | ||
1147 | libraries they link against. | ||
1148 | For each shared library dependency that is found, | ||
1149 | <filename>PKGDATA_DIR</filename> is queried to | ||
1150 | see if some package (likely from a different recipe) | ||
1151 | contains the shared library. | ||
1152 | If such a package is found, a runtime dependency is added | ||
1153 | from the package that depends on the shared library to the | ||
1154 | package that contains the library.</para> | ||
1155 | |||
1156 | <para>The automatically added runtime dependency also | ||
1157 | includes a version restriction. | ||
1158 | This version restriction specifies that at least the | ||
1159 | current version of the package that provides the shared | ||
1160 | library must be used, as if | ||
1161 | "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)" | ||
1162 | had been added to | ||
1163 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>. | ||
1164 | This forces an upgrade of the package containing the shared | ||
1165 | library when installing the package that depends on the | ||
1166 | library, if needed.</para> | ||
1167 | |||
1168 | <para>If you want to avoid a package being registered as | ||
1169 | providing a particular shared library (e.g. because the library | ||
1170 | is for internal use only), then add the library to | ||
1171 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink> | ||
1172 | inside the package's recipe. | ||
1173 | </para></listitem> | ||
1174 | <listitem><para> | ||
1175 | <filename>pcdeps</filename>: | ||
1176 | During the | ||
1177 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> | ||
1178 | task of each recipe, all pkg-config modules | ||
1179 | (<filename>*.pc</filename> files) installed by the recipe | ||
1180 | are located. | ||
1181 | For each module, the package that contains the module is | ||
1182 | registered as providing the module. | ||
1183 | The resulting module-to-package mapping is saved globally in | ||
1184 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> | ||
1185 | by the | ||
1186 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1187 | task.</para> | ||
1188 | |||
1189 | <para>Simultaneously, all pkg-config modules installed by | ||
1190 | the recipe are inspected to see what other pkg-config | ||
1191 | modules they depend on. | ||
1192 | A module is seen as depending on another module if it | ||
1193 | contains a "Requires:" line that specifies the other module. | ||
1194 | For each module dependency, | ||
1195 | <filename>PKGDATA_DIR</filename> is queried to see if some | ||
1196 | package contains the module. | ||
1197 | If such a package is found, a runtime dependency is added | ||
1198 | from the package that depends on the module to the package | ||
1199 | that contains the module. | ||
1200 | <note> | ||
1201 | The <filename>pcdeps</filename> mechanism most often | ||
1202 | infers dependencies between <filename>-dev</filename> | ||
1203 | packages. | ||
1204 | </note> | ||
1205 | </para></listitem> | ||
1206 | <listitem><para> | ||
1207 | <filename>depchains</filename>: | ||
1208 | If a package <filename>foo</filename> depends on a package | ||
1209 | <filename>bar</filename>, then <filename>foo-dev</filename> | ||
1210 | and <filename>foo-dbg</filename> are also made to depend on | ||
1211 | <filename>bar-dev</filename> and | ||
1212 | <filename>bar-dbg</filename>, respectively. | ||
1213 | Taking the <filename>-dev</filename> packages as an | ||
1214 | example, the <filename>bar-dev</filename> package might | ||
1215 | provide headers and shared library symlinks needed by | ||
1216 | <filename>foo-dev</filename>, which shows the need | ||
1217 | for a dependency between the packages.</para> | ||
1218 | |||
1219 | <para>The dependencies added by | ||
1220 | <filename>depchains</filename> are in the form of | ||
1221 | <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>. | ||
1222 | <note> | ||
1223 | By default, <filename>foo-dev</filename> also has an | ||
1224 | <filename>RDEPENDS</filename>-style dependency on | ||
1225 | <filename>foo</filename>, because the default value of | ||
1226 | <filename>RDEPENDS_${PN}-dev</filename> (set in | ||
1227 | <filename>bitbake.conf</filename>) includes | ||
1228 | "${PN}". | ||
1229 | </note></para> | ||
1230 | |||
1231 | <para>To ensure that the dependency chain is never broken, | ||
1232 | <filename>-dev</filename> and <filename>-dbg</filename> | ||
1233 | packages are always generated by default, even if the | ||
1234 | packages turn out to be empty. | ||
1235 | See the | ||
1236 | <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink> | ||
1237 | variable for more information. | ||
1238 | </para></listitem> | ||
1239 | </itemizedlist> | ||
1240 | </para> | ||
1241 | |||
1242 | <para> | ||
1243 | The <filename>do_package</filename> task depends on the | ||
1244 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink> | ||
1245 | task of each recipe in | ||
1246 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> | ||
1247 | through use of a | ||
1248 | <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> | ||
1249 | declaration, which guarantees that the required | ||
1250 | shared-library/module-to-package mapping information will be available | ||
1251 | when needed as long as <filename>DEPENDS</filename> has been | ||
1252 | correctly set. | ||
1253 | </para> | ||
1254 | </section> | ||
1255 | |||
1256 | <section id='fakeroot-and-pseudo'> | ||
1257 | <title>Fakeroot and Pseudo</title> | ||
1258 | |||
1259 | <para> | ||
1260 | Some tasks are easier to implement when allowed to perform certain | ||
1261 | operations that are normally reserved for the root user (e.g. | ||
1262 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>, | ||
1263 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write*</filename></ulink>, | ||
1264 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>, | ||
1265 | and | ||
1266 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image*</filename></ulink>). | ||
1267 | For example, the <filename>do_install</filename> task benefits | ||
1268 | from being able to set the UID and GID of installed files to | ||
1269 | arbitrary values. | ||
1270 | </para> | ||
1271 | |||
1272 | <para> | ||
1273 | One approach to allowing tasks to perform root-only operations | ||
1274 | would be to require BitBake to run as root. | ||
1275 | However, this method is cumbersome and has security issues. | ||
1276 | The approach that is actually used is to run tasks that benefit | ||
1277 | from root privileges in a "fake" root environment. | ||
1278 | Within this environment, the task and its child processes believe | ||
1279 | that they are running as the root user, and see an internally | ||
1280 | consistent view of the filesystem. | ||
1281 | As long as generating the final output (e.g. a package or an image) | ||
1282 | does not require root privileges, the fact that some earlier | ||
1283 | steps ran in a fake root environment does not cause problems. | ||
1284 | </para> | ||
1285 | |||
1286 | <para> | ||
1287 | The capability to run tasks in a fake root environment is known as | ||
1288 | "<ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>", | ||
1289 | which is derived from the BitBake keyword/variable | ||
1290 | flag that requests a fake root environment for a task. | ||
1291 | </para> | ||
1292 | |||
1293 | <para> | ||
1294 | In the OpenEmbedded build system, the program that implements | ||
1295 | fakeroot is known as Pseudo. | ||
1296 | Pseudo overrides system calls by using the environment variable | ||
1297 | <filename>LD_PRELOAD</filename>, which results in the illusion | ||
1298 | of running as root. | ||
1299 | To keep track of "fake" file ownership and permissions resulting | ||
1300 | from operations that require root permissions, Pseudo uses | ||
1301 | an SQLite 3 database. | ||
1302 | This database is stored in | ||
1303 | <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/pseudo/files.db</filename> | ||
1304 | for individual recipes. | ||
1305 | Storing the database in a file as opposed to in memory | ||
1306 | gives persistence between tasks and builds, which is not | ||
1307 | accomplished using fakeroot. | ||
1308 | <note><title>Caution</title> | ||
1309 | If you add your own task that manipulates the same files or | ||
1310 | directories as a fakeroot task, then that task also needs to | ||
1311 | run under fakeroot. | ||
1312 | Otherwise, the task cannot run root-only operations, and | ||
1313 | cannot see the fake file ownership and permissions set by the | ||
1314 | other task. | ||
1315 | You need to also add a dependency on | ||
1316 | <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, | ||
1317 | giving the following: | ||
1318 | <literallayout class='monospaced'> | ||
1319 | fakeroot do_mytask () { | ||
1320 | ... | ||
1321 | } | ||
1322 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | ||
1323 | </literallayout> | ||
1324 | </note> | ||
1325 | For more information, see the | ||
1326 | <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> | ||
1327 | variables in the BitBake User Manual. | ||
1328 | You can also reference the | ||
1329 | "<ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>" | ||
1330 | and | ||
1331 | "<ulink url='https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot'>Why Not Fakeroot?</ulink>" | ||
1332 | articles for background information on Pseudo. | ||
1333 | </para> | ||
1334 | </section> | ||
1335 | |||
1336 | <section id="wayland"> | ||
1337 | <title>Wayland</title> | ||
1338 | |||
1339 | <para> | ||
1340 | <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink> | ||
1341 | is a computer display server protocol that | ||
1342 | provides a method for compositing window managers to communicate | ||
1343 | directly with applications and video hardware and expects them to | ||
1344 | communicate with input hardware using other libraries. | ||
1345 | Using Wayland with supporting targets can result in better control | ||
1346 | over graphics frame rendering than an application might otherwise | ||
1347 | achieve. | ||
1348 | </para> | ||
1349 | |||
1350 | <para> | ||
1351 | The Yocto Project provides the Wayland protocol libraries and the | ||
1352 | reference | ||
1353 | <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink> | ||
1354 | compositor as part of its release. | ||
1355 | This section describes what you need to do to implement Wayland and | ||
1356 | use the compositor when building an image for a supporting target. | ||
1357 | </para> | ||
1358 | |||
1359 | <section id="wayland-support"> | ||
1360 | <title>Support</title> | ||
1361 | |||
1362 | <para> | ||
1363 | The Wayland protocol libraries and the reference Weston | ||
1364 | compositor ship as integrated packages in the | ||
1365 | <filename>meta</filename> layer of the | ||
1366 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
1367 | Specifically, you can find the recipes that build both Wayland | ||
1368 | and Weston at | ||
1369 | <filename>meta/recipes-graphics/wayland</filename>. | ||
1370 | </para> | ||
1371 | |||
1372 | <para> | ||
1373 | You can build both the Wayland and Weston packages for use only | ||
1374 | with targets that accept the | ||
1375 | <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>, | ||
1376 | which is also known as Mesa DRI. | ||
1377 | This implies that you cannot build and use the packages if your | ||
1378 | target uses, for example, the | ||
1379 | <trademark class='registered'>Intel</trademark> Embedded Media | ||
1380 | and Graphics Driver | ||
1381 | (<trademark class='registered'>Intel</trademark> EMGD) that | ||
1382 | overrides Mesa DRI. | ||
1383 | <note> | ||
1384 | Due to lack of EGL support, Weston 1.0.3 will not run | ||
1385 | directly on the emulated QEMU hardware. | ||
1386 | However, this version of Weston will run under X emulation | ||
1387 | without issues. | ||
1388 | </note> | ||
1389 | </para> | ||
1390 | </section> | ||
1391 | |||
1392 | <section id="enabling-wayland-in-an-image"> | ||
1393 | <title>Enabling Wayland in an Image</title> | ||
1394 | |||
1395 | <para> | ||
1396 | To enable Wayland, you need to enable it to be built and enable | ||
1397 | it to be included in the image. | ||
1398 | </para> | ||
1399 | |||
1400 | <section id="enable-building"> | ||
1401 | <title>Building</title> | ||
1402 | |||
1403 | <para> | ||
1404 | To cause Mesa to build the <filename>wayland-egl</filename> | ||
1405 | platform and Weston to build Wayland with Kernel Mode | ||
1406 | Setting | ||
1407 | (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>) | ||
1408 | support, include the "wayland" flag in the | ||
1409 | <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink> | ||
1410 | statement in your <filename>local.conf</filename> file: | ||
1411 | <literallayout class='monospaced'> | ||
1412 | DISTRO_FEATURES_append = " wayland" | ||
1413 | </literallayout> | ||
1414 | <note> | ||
1415 | If X11 has been enabled elsewhere, Weston will build | ||
1416 | Wayland with X11 support | ||
1417 | </note> | ||
1418 | </para> | ||
1419 | </section> | ||
1420 | |||
1421 | <section id="enable-installation-in-an-image"> | ||
1422 | <title>Installing</title> | ||
1423 | |||
1424 | <para> | ||
1425 | To install the Wayland feature into an image, you must | ||
1426 | include the following | ||
1427 | <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink> | ||
1428 | statement in your <filename>local.conf</filename> file: | ||
1429 | <literallayout class='monospaced'> | ||
1430 | CORE_IMAGE_EXTRA_INSTALL += "wayland weston" | ||
1431 | </literallayout> | ||
1432 | </para> | ||
1433 | </section> | ||
1434 | </section> | ||
1435 | |||
1436 | <section id="running-weston"> | ||
1437 | <title>Running Weston</title> | ||
1438 | |||
1439 | <para> | ||
1440 | To run Weston inside X11, enabling it as described earlier and | ||
1441 | building a Sato image is sufficient. | ||
1442 | If you are running your image under Sato, a Weston Launcher | ||
1443 | appears in the "Utility" category. | ||
1444 | </para> | ||
1445 | |||
1446 | <para> | ||
1447 | Alternatively, you can run Weston through the command-line | ||
1448 | interpretor (CLI), which is better suited for development work. | ||
1449 | To run Weston under the CLI, you need to do the following after | ||
1450 | your image is built: | ||
1451 | <orderedlist> | ||
1452 | <listitem><para> | ||
1453 | Run these commands to export | ||
1454 | <filename>XDG_RUNTIME_DIR</filename>: | ||
1455 | <literallayout class='monospaced'> | ||
1456 | mkdir -p /tmp/$USER-weston | ||
1457 | chmod 0700 /tmp/$USER-weston | ||
1458 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | ||
1459 | </literallayout> | ||
1460 | </para></listitem> | ||
1461 | <listitem><para> | ||
1462 | Launch Weston in the shell: | ||
1463 | <literallayout class='monospaced'> | ||
1464 | weston | ||
1465 | </literallayout></para></listitem> | ||
1466 | </orderedlist> | ||
1467 | </para> | ||
1468 | </section> | ||
1469 | </section> | ||
1470 | |||
1471 | <section id="overview-licenses"> | ||
1472 | <title>Licenses</title> | ||
1473 | |||
1474 | <para> | ||
1475 | This section describes the mechanism by which the OpenEmbedded | ||
1476 | build system tracks changes to licensing text. | ||
1477 | The section also describes how to enable commercially licensed | ||
1478 | recipes, which by default are disabled. | ||
1479 | </para> | ||
1480 | |||
1481 | <para> | ||
1482 | For information that can help you maintain compliance with | ||
1483 | various open source licensing during the lifecycle of the product, | ||
1484 | see the | ||
1485 | "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" | ||
1486 | section in the Yocto Project Development Tasks Manual. | ||
1487 | </para> | ||
1488 | |||
1489 | <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> | ||
1490 | <title>Tracking License Changes</title> | ||
1491 | |||
1492 | <para> | ||
1493 | The license of an upstream project might change in the future. | ||
1494 | In order to prevent these changes going unnoticed, the | ||
1495 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> | ||
1496 | variable tracks changes to the license text. The checksums are | ||
1497 | validated at the end of the configure step, and if the | ||
1498 | checksums do not match, the build will fail. | ||
1499 | </para> | ||
1500 | |||
1501 | <section id="usingpoky-specifying-LIC_FILES_CHKSUM"> | ||
1502 | <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title> | ||
1503 | |||
1504 | <para> | ||
1505 | The <filename>LIC_FILES_CHKSUM</filename> | ||
1506 | variable contains checksums of the license text in the | ||
1507 | source code for the recipe. | ||
1508 | Following is an example of how to specify | ||
1509 | <filename>LIC_FILES_CHKSUM</filename>: | ||
1510 | <literallayout class='monospaced'> | ||
1511 | LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ | ||
1512 | file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ | ||
1513 | file://licfile2.txt;endline=50;md5=zzzz \ | ||
1514 | ..." | ||
1515 | </literallayout> | ||
1516 | <note><title>Notes</title> | ||
1517 | <itemizedlist> | ||
1518 | <listitem><para> | ||
1519 | When using "beginline" and "endline", realize | ||
1520 | that line numbering begins with one and not | ||
1521 | zero. | ||
1522 | Also, the included lines are inclusive (i.e. | ||
1523 | lines five through and including 29 in the | ||
1524 | previous example for | ||
1525 | <filename>licfile1.txt</filename>). | ||
1526 | </para></listitem> | ||
1527 | <listitem><para> | ||
1528 | When a license check fails, the selected license | ||
1529 | text is included as part of the QA message. | ||
1530 | Using this output, you can determine the exact | ||
1531 | start and finish for the needed license text. | ||
1532 | </para></listitem> | ||
1533 | </itemizedlist> | ||
1534 | </note> | ||
1535 | </para> | ||
1536 | |||
1537 | <para> | ||
1538 | The build system uses the | ||
1539 | <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> | ||
1540 | variable as the default directory when searching files | ||
1541 | listed in <filename>LIC_FILES_CHKSUM</filename>. | ||
1542 | The previous example employs the default directory. | ||
1543 | </para> | ||
1544 | |||
1545 | <para> | ||
1546 | Consider this next example: | ||
1547 | <literallayout class='monospaced'> | ||
1548 | LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ | ||
1549 | md5=bb14ed3c4cda583abc85401304b5cd4e" | ||
1550 | LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" | ||
1551 | </literallayout> | ||
1552 | </para> | ||
1553 | |||
1554 | <para> | ||
1555 | The first line locates a file in | ||
1556 | <filename>${S}/src/ls.c</filename> and isolates lines five | ||
1557 | through 16 as license text. | ||
1558 | The second line refers to a file in | ||
1559 | <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>. | ||
1560 | </para> | ||
1561 | |||
1562 | <para> | ||
1563 | Note that <filename>LIC_FILES_CHKSUM</filename> variable is | ||
1564 | mandatory for all recipes, unless the | ||
1565 | <filename>LICENSE</filename> variable is set to "CLOSED". | ||
1566 | </para> | ||
1567 | </section> | ||
1568 | |||
1569 | <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> | ||
1570 | <title>Explanation of Syntax</title> | ||
1571 | |||
1572 | <para> | ||
1573 | As mentioned in the previous section, the | ||
1574 | <filename>LIC_FILES_CHKSUM</filename> variable lists all | ||
1575 | the important files that contain the license text for the | ||
1576 | source code. | ||
1577 | It is possible to specify a checksum for an entire file, | ||
1578 | or a specific section of a file (specified by beginning and | ||
1579 | ending line numbers with the "beginline" and "endline" | ||
1580 | parameters, respectively). | ||
1581 | The latter is useful for source files with a license | ||
1582 | notice header, README documents, and so forth. | ||
1583 | If you do not use the "beginline" parameter, then it is | ||
1584 | assumed that the text begins on the first line of the file. | ||
1585 | Similarly, if you do not use the "endline" parameter, | ||
1586 | it is assumed that the license text ends with the last | ||
1587 | line of the file. | ||
1588 | </para> | ||
1589 | |||
1590 | <para> | ||
1591 | The "md5" parameter stores the md5 checksum of the license | ||
1592 | text. | ||
1593 | If the license text changes in any way as compared to | ||
1594 | this parameter then a mismatch occurs. | ||
1595 | This mismatch triggers a build failure and notifies | ||
1596 | the developer. | ||
1597 | Notification allows the developer to review and address | ||
1598 | the license text changes. | ||
1599 | Also note that if a mismatch occurs during the build, | ||
1600 | the correct md5 checksum is placed in the build log and | ||
1601 | can be easily copied to the recipe. | ||
1602 | </para> | ||
1603 | |||
1604 | <para> | ||
1605 | There is no limit to how many files you can specify using | ||
1606 | the <filename>LIC_FILES_CHKSUM</filename> variable. | ||
1607 | Generally, however, every project requires a few | ||
1608 | specifications for license tracking. | ||
1609 | Many projects have a "COPYING" file that stores the | ||
1610 | license information for all the source code files. | ||
1611 | This practice allows you to just track the "COPYING" | ||
1612 | file as long as it is kept up to date. | ||
1613 | <note><title>Tips</title> | ||
1614 | <itemizedlist> | ||
1615 | <listitem><para> | ||
1616 | If you specify an empty or invalid "md5" | ||
1617 | parameter, BitBake returns an md5 mis-match | ||
1618 | error and displays the correct "md5" parameter | ||
1619 | value during the build. | ||
1620 | The correct parameter is also captured in | ||
1621 | the build log. | ||
1622 | </para></listitem> | ||
1623 | <listitem><para> | ||
1624 | If the whole file contains only license text, | ||
1625 | you do not need to use the "beginline" and | ||
1626 | "endline" parameters. | ||
1627 | </para></listitem> | ||
1628 | </itemizedlist> | ||
1629 | </note> | ||
1630 | </para> | ||
1631 | </section> | ||
1632 | </section> | ||
1633 | |||
1634 | <section id="enabling-commercially-licensed-recipes"> | ||
1635 | <title>Enabling Commercially Licensed Recipes</title> | ||
1636 | |||
1637 | <para> | ||
1638 | By default, the OpenEmbedded build system disables | ||
1639 | components that have commercial or other special licensing | ||
1640 | requirements. | ||
1641 | Such requirements are defined on a | ||
1642 | recipe-by-recipe basis through the | ||
1643 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
1644 | variable definition in the affected recipe. | ||
1645 | For instance, the | ||
1646 | <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | ||
1647 | recipe contains the following statement: | ||
1648 | <literallayout class='monospaced'> | ||
1649 | LICENSE_FLAGS = "commercial" | ||
1650 | </literallayout> | ||
1651 | Here is a slightly more complicated example that contains both | ||
1652 | an explicit recipe name and version (after variable expansion): | ||
1653 | <literallayout class='monospaced'> | ||
1654 | LICENSE_FLAGS = "license_${PN}_${PV}" | ||
1655 | </literallayout> | ||
1656 | In order for a component restricted by a | ||
1657 | <filename>LICENSE_FLAGS</filename> definition to be enabled and | ||
1658 | included in an image, it needs to have a matching entry in the | ||
1659 | global | ||
1660 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink> | ||
1661 | variable, which is a variable typically defined in your | ||
1662 | <filename>local.conf</filename> file. | ||
1663 | For example, to enable the | ||
1664 | <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename> | ||
1665 | package, you could add either the string | ||
1666 | "commercial_gst-plugins-ugly" or the more general string | ||
1667 | "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>. | ||
1668 | See the | ||
1669 | "<link linkend='license-flag-matching'>License Flag Matching</link>" | ||
1670 | section for a full | ||
1671 | explanation of how <filename>LICENSE_FLAGS</filename> matching | ||
1672 | works. | ||
1673 | Here is the example: | ||
1674 | <literallayout class='monospaced'> | ||
1675 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" | ||
1676 | </literallayout> | ||
1677 | Likewise, to additionally enable the package built from the | ||
1678 | recipe containing | ||
1679 | <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, | ||
1680 | and assuming that the actual recipe name was | ||
1681 | <filename>emgd_1.10.bb</filename>, the following string would | ||
1682 | enable that package as well as the original | ||
1683 | <filename>gst-plugins-ugly</filename> package: | ||
1684 | <literallayout class='monospaced'> | ||
1685 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" | ||
1686 | </literallayout> | ||
1687 | As a convenience, you do not need to specify the complete | ||
1688 | license string in the whitelist for every package. | ||
1689 | You can use an abbreviated form, which consists | ||
1690 | of just the first portion or portions of the license | ||
1691 | string before the initial underscore character or characters. | ||
1692 | A partial string will match any license that contains the | ||
1693 | given string as the first portion of its license. | ||
1694 | For example, the following whitelist string will also match | ||
1695 | both of the packages previously mentioned as well as any other | ||
1696 | packages that have licenses starting with "commercial" or | ||
1697 | "license". | ||
1698 | <literallayout class='monospaced'> | ||
1699 | LICENSE_FLAGS_WHITELIST = "commercial license" | ||
1700 | </literallayout> | ||
1701 | </para> | ||
1702 | |||
1703 | <section id="license-flag-matching"> | ||
1704 | <title>License Flag Matching</title> | ||
1705 | |||
1706 | <para> | ||
1707 | License flag matching allows you to control what recipes | ||
1708 | the OpenEmbedded build system includes in the build. | ||
1709 | Fundamentally, the build system attempts to match | ||
1710 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
1711 | strings found in recipes against | ||
1712 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink> | ||
1713 | strings found in the whitelist. | ||
1714 | A match causes the build system to include a recipe in the | ||
1715 | build, while failure to find a match causes the build | ||
1716 | system to exclude a recipe. | ||
1717 | </para> | ||
1718 | |||
1719 | <para> | ||
1720 | In general, license flag matching is simple. | ||
1721 | However, understanding some concepts will help you | ||
1722 | correctly and effectively use matching. | ||
1723 | </para> | ||
1724 | |||
1725 | <para> | ||
1726 | Before a flag | ||
1727 | defined by a particular recipe is tested against the | ||
1728 | contents of the whitelist, the expanded string | ||
1729 | <filename>_${PN}</filename> is appended to the flag. | ||
1730 | This expansion makes each | ||
1731 | <filename>LICENSE_FLAGS</filename> value recipe-specific. | ||
1732 | After expansion, the string is then matched against the | ||
1733 | whitelist. | ||
1734 | Thus, specifying | ||
1735 | <filename>LICENSE_FLAGS = "commercial"</filename> | ||
1736 | in recipe "foo", for example, results in the string | ||
1737 | <filename>"commercial_foo"</filename>. | ||
1738 | And, to create a match, that string must appear in the | ||
1739 | whitelist. | ||
1740 | </para> | ||
1741 | |||
1742 | <para> | ||
1743 | Judicious use of the <filename>LICENSE_FLAGS</filename> | ||
1744 | strings and the contents of the | ||
1745 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable | ||
1746 | allows you a lot of flexibility for including or excluding | ||
1747 | recipes based on licensing. | ||
1748 | For example, you can broaden the matching capabilities by | ||
1749 | using license flags string subsets in the whitelist. | ||
1750 | <note> | ||
1751 | When using a string subset, be sure to use the part of | ||
1752 | the expanded string that precedes the appended | ||
1753 | underscore character (e.g. | ||
1754 | <filename>usethispart_1.3</filename>, | ||
1755 | <filename>usethispart_1.4</filename>, and so forth). | ||
1756 | </note> | ||
1757 | For example, simply specifying the string "commercial" in | ||
1758 | the whitelist matches any expanded | ||
1759 | <filename>LICENSE_FLAGS</filename> definition that starts | ||
1760 | with the string "commercial" such as "commercial_foo" and | ||
1761 | "commercial_bar", which are the strings the build system | ||
1762 | automatically generates for hypothetical recipes named | ||
1763 | "foo" and "bar" assuming those recipes simply specify the | ||
1764 | following: | ||
1765 | <literallayout class='monospaced'> | ||
1766 | LICENSE_FLAGS = "commercial" | ||
1767 | </literallayout> | ||
1768 | Thus, you can choose to exhaustively | ||
1769 | enumerate each license flag in the whitelist and | ||
1770 | allow only specific recipes into the image, or | ||
1771 | you can use a string subset that causes a broader range of | ||
1772 | matches to allow a range of recipes into the image. | ||
1773 | </para> | ||
1774 | |||
1775 | <para> | ||
1776 | This scheme works even if the | ||
1777 | <filename>LICENSE_FLAGS</filename> string already | ||
1778 | has <filename>_${PN}</filename> appended. | ||
1779 | For example, the build system turns the license flag | ||
1780 | "commercial_1.2_foo" into "commercial_1.2_foo_foo" and | ||
1781 | would match both the general "commercial" and the specific | ||
1782 | "commercial_1.2_foo" strings found in the whitelist, as | ||
1783 | expected. | ||
1784 | </para> | ||
1785 | |||
1786 | <para> | ||
1787 | Here are some other scenarios: | ||
1788 | <itemizedlist> | ||
1789 | <listitem><para> | ||
1790 | You can specify a versioned string in the recipe | ||
1791 | such as "commercial_foo_1.2" in a "foo" recipe. | ||
1792 | The build system expands this string to | ||
1793 | "commercial_foo_1.2_foo". | ||
1794 | Combine this license flag with a whitelist that has | ||
1795 | the string "commercial" and you match the flag | ||
1796 | along with any other flag that starts with the | ||
1797 | string "commercial". | ||
1798 | </para></listitem> | ||
1799 | <listitem><para> | ||
1800 | Under the same circumstances, you can use | ||
1801 | "commercial_foo" in the whitelist and the build | ||
1802 | system not only matches "commercial_foo_1.2" but | ||
1803 | also matches any license flag with the string | ||
1804 | "commercial_foo", regardless of the version. | ||
1805 | </para></listitem> | ||
1806 | <listitem><para> | ||
1807 | You can be very specific and use both the | ||
1808 | package and version parts in the whitelist (e.g. | ||
1809 | "commercial_foo_1.2") to specifically match a | ||
1810 | versioned recipe. | ||
1811 | </para></listitem> | ||
1812 | </itemizedlist> | ||
1813 | </para> | ||
1814 | </section> | ||
1815 | |||
1816 | <section id="other-variables-related-to-commercial-licenses"> | ||
1817 | <title>Other Variables Related to Commercial Licenses</title> | ||
1818 | |||
1819 | <para> | ||
1820 | Other helpful variables related to commercial | ||
1821 | license handling exist and are defined in the | ||
1822 | <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file: | ||
1823 | <literallayout class='monospaced'> | ||
1824 | COMMERCIAL_AUDIO_PLUGINS ?= "" | ||
1825 | COMMERCIAL_VIDEO_PLUGINS ?= "" | ||
1826 | </literallayout> | ||
1827 | If you want to enable these components, you can do so by | ||
1828 | making sure you have statements similar to the following | ||
1829 | in your <filename>local.conf</filename> configuration file: | ||
1830 | <literallayout class='monospaced'> | ||
1831 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | ||
1832 | gst-plugins-ugly-mpegaudioparse" | ||
1833 | COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ | ||
1834 | gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" | ||
1835 | LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" | ||
1836 | </literallayout> | ||
1837 | Of course, you could also create a matching whitelist | ||
1838 | for those components using the more general "commercial" | ||
1839 | in the whitelist, but that would also enable all the | ||
1840 | other packages with | ||
1841 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> | ||
1842 | containing "commercial", which you may or may not want: | ||
1843 | <literallayout class='monospaced'> | ||
1844 | LICENSE_FLAGS_WHITELIST = "commercial" | ||
1845 | </literallayout> | ||
1846 | </para> | ||
1847 | |||
1848 | <para> | ||
1849 | Specifying audio and video plug-ins as part of the | ||
1850 | <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and | ||
1851 | <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements | ||
1852 | (along with the enabling | ||
1853 | <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the | ||
1854 | plug-ins or components into built images, thus adding | ||
1855 | support for media formats or components. | ||
1856 | </para> | ||
1857 | </section> | ||
1858 | </section> | ||
1859 | </section> | ||
1860 | |||
1861 | <section id='x32'> | ||
1862 | <title>x32 psABI</title> | ||
1863 | |||
1864 | <para> | ||
1865 | x32 processor-specific Application Binary Interface | ||
1866 | (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>) | ||
1867 | is a native 32-bit processor-specific ABI for | ||
1868 | <trademark class='registered'>Intel</trademark> 64 (x86-64) | ||
1869 | architectures. | ||
1870 | An ABI defines the calling conventions between functions in a | ||
1871 | processing environment. | ||
1872 | The interface determines what registers are used and what the sizes are | ||
1873 | for various C data types. | ||
1874 | </para> | ||
1875 | |||
1876 | <para> | ||
1877 | Some processing environments prefer using 32-bit applications even | ||
1878 | when running on Intel 64-bit platforms. | ||
1879 | Consider the i386 psABI, which is a very old 32-bit ABI for Intel | ||
1880 | 64-bit platforms. | ||
1881 | The i386 psABI does not provide efficient use and access of the | ||
1882 | Intel 64-bit processor resources, leaving the system underutilized. | ||
1883 | Now consider the x86_64 psABI. | ||
1884 | This ABI is newer and uses 64-bits for data sizes and program | ||
1885 | pointers. | ||
1886 | The extra bits increase the footprint size of the programs, | ||
1887 | libraries, and also increases the memory and file system size | ||
1888 | requirements. | ||
1889 | Executing under the x32 psABI enables user programs to utilize CPU | ||
1890 | and system resources more efficiently while keeping the memory | ||
1891 | footprint of the applications low. | ||
1892 | Extra bits are used for registers but not for addressing mechanisms. | ||
1893 | </para> | ||
1894 | |||
1895 | <para> | ||
1896 | The Yocto Project supports the final specifications of x32 psABI | ||
1897 | as follows: | ||
1898 | <itemizedlist> | ||
1899 | <listitem><para> | ||
1900 | You can create packages and images in x32 psABI format on | ||
1901 | x86_64 architecture targets. | ||
1902 | </para></listitem> | ||
1903 | <listitem><para> | ||
1904 | You can successfully build recipes with the x32 toolchain. | ||
1905 | </para></listitem> | ||
1906 | <listitem><para> | ||
1907 | You can create and boot | ||
1908 | <filename>core-image-minimal</filename> and | ||
1909 | <filename>core-image-sato</filename> images. | ||
1910 | </para></listitem> | ||
1911 | <listitem><para> | ||
1912 | RPM Package Manager (RPM) support exists for x32 binaries. | ||
1913 | </para></listitem> | ||
1914 | <listitem><para> | ||
1915 | Support for large images exists. | ||
1916 | </para></listitem> | ||
1917 | </itemizedlist> | ||
1918 | </para> | ||
1919 | |||
1920 | <para> | ||
1921 | For steps on how to use x32 psABI, see the | ||
1922 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-x32-psabi'>Using x32 psABI</ulink>" | ||
1923 | section in the Yocto Project Development Tasks Manual. | ||
1924 | </para> | ||
1925 | </section> | ||
1926 | </chapter> | ||
1927 | <!-- | ||
1928 | vim: expandtab tw=80 ts=4 | ||
1929 | --> | ||
diff --git a/documentation/getting-started/getting-started.xml b/documentation/getting-started/getting-started.xml index 930a202e1a..9249bb5732 100644 --- a/documentation/getting-started/getting-started.xml +++ b/documentation/getting-started/getting-started.xml | |||
@@ -54,7 +54,7 @@ | |||
54 | <itemizedlist> | 54 | <itemizedlist> |
55 | <listitem><para> | 55 | <listitem><para> |
56 | This version of the | 56 | This version of the |
57 | <emphasis>Yocto Project Overview Manual</emphasis> | 57 | <emphasis>Getting Started With Yocto Project Manual</emphasis> |
58 | is for the &YOCTO_DOC_VERSION; release of the | 58 | is for the &YOCTO_DOC_VERSION; release of the |
59 | Yocto Project. | 59 | Yocto Project. |
60 | To be sure you have the latest version of the manual | 60 | To be sure you have the latest version of the manual |
@@ -86,8 +86,6 @@ | |||
86 | 86 | ||
87 | <xi:include href="getting-started-development-environment.xml"/> | 87 | <xi:include href="getting-started-development-environment.xml"/> |
88 | 88 | ||
89 | <xi:include href="getting-started-concepts.xml"/> | ||
90 | |||
91 | </book> | 89 | </book> |
92 | <!-- | 90 | <!-- |
93 | vim: expandtab tw=80 ts=4 | 91 | vim: expandtab tw=80 ts=4 |