summaryrefslogtreecommitdiffstats
path: root/documentation/overview-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/overview-manual')
-rw-r--r--documentation/overview-manual/figures/YP-flow-diagram.pngbin190715 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/analysis-for-package-splitting.pngbin63291 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/configuration-compile-autoreconf.pngbin46080 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/cross-development-toolchains.pngbin59275 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/git-workflow.pngbin26586 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/image-generation.pngbin112991 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/images.pngbin22926 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/index-downloads.pngbin36362 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/layer-input.pngbin45856 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/overview-title.pngbin12547 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/package-feeds.pngbin30112 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/patching.pngbin42523 -> 0 bytes
-rwxr-xr-xdocumentation/overview-manual/figures/sdk-generation.pngbin115643 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/sdk.pngbin67478 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/source-fetching.pngbin38860 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/source-input.pngbin39872 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/source-repos.pngbin298757 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/user-configuration.pngbin74109 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/yocto-environment-ref.pngbin83206 -> 0 bytes
-rw-r--r--documentation/overview-manual/figures/yp-download.pngbin230971 -> 0 bytes
-rw-r--r--documentation/overview-manual/overview-concepts.xml1929
-rw-r--r--documentation/overview-manual/overview-development-environment.xml2890
-rw-r--r--documentation/overview-manual/overview-manual-customization.xsl27
-rw-r--r--documentation/overview-manual/overview-manual-eclipse-customization.xsl35
-rw-r--r--documentation/overview-manual/overview-manual-intro.xml103
-rw-r--r--documentation/overview-manual/overview-manual.xml94
-rw-r--r--documentation/overview-manual/overview-style.css988
27 files changed, 0 insertions, 6066 deletions
diff --git a/documentation/overview-manual/figures/YP-flow-diagram.png b/documentation/overview-manual/figures/YP-flow-diagram.png
deleted file mode 100644
index 8264410504..0000000000
--- a/documentation/overview-manual/figures/YP-flow-diagram.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/analysis-for-package-splitting.png b/documentation/overview-manual/figures/analysis-for-package-splitting.png
deleted file mode 100644
index 04f2794ea9..0000000000
--- a/documentation/overview-manual/figures/analysis-for-package-splitting.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/configuration-compile-autoreconf.png b/documentation/overview-manual/figures/configuration-compile-autoreconf.png
deleted file mode 100644
index a07464f04c..0000000000
--- a/documentation/overview-manual/figures/configuration-compile-autoreconf.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/cross-development-toolchains.png b/documentation/overview-manual/figures/cross-development-toolchains.png
deleted file mode 100644
index d36670a198..0000000000
--- a/documentation/overview-manual/figures/cross-development-toolchains.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/git-workflow.png b/documentation/overview-manual/figures/git-workflow.png
deleted file mode 100644
index e401330a12..0000000000
--- a/documentation/overview-manual/figures/git-workflow.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/image-generation.png b/documentation/overview-manual/figures/image-generation.png
deleted file mode 100644
index 71a48dc6f4..0000000000
--- a/documentation/overview-manual/figures/image-generation.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/images.png b/documentation/overview-manual/figures/images.png
deleted file mode 100644
index d99eac1fbf..0000000000
--- a/documentation/overview-manual/figures/images.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/index-downloads.png b/documentation/overview-manual/figures/index-downloads.png
deleted file mode 100644
index 96303b8781..0000000000
--- a/documentation/overview-manual/figures/index-downloads.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/layer-input.png b/documentation/overview-manual/figures/layer-input.png
deleted file mode 100644
index 0a4f2e74f3..0000000000
--- a/documentation/overview-manual/figures/layer-input.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/overview-title.png b/documentation/overview-manual/figures/overview-title.png
deleted file mode 100644
index c5ec87242e..0000000000
--- a/documentation/overview-manual/figures/overview-title.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/package-feeds.png b/documentation/overview-manual/figures/package-feeds.png
deleted file mode 100644
index 37c9c32506..0000000000
--- a/documentation/overview-manual/figures/package-feeds.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/patching.png b/documentation/overview-manual/figures/patching.png
deleted file mode 100644
index 8ecd018502..0000000000
--- a/documentation/overview-manual/figures/patching.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/sdk-generation.png b/documentation/overview-manual/figures/sdk-generation.png
deleted file mode 100755
index adbe1f4acf..0000000000
--- a/documentation/overview-manual/figures/sdk-generation.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/sdk.png b/documentation/overview-manual/figures/sdk.png
deleted file mode 100644
index 5c36b7548b..0000000000
--- a/documentation/overview-manual/figures/sdk.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/source-fetching.png b/documentation/overview-manual/figures/source-fetching.png
deleted file mode 100644
index 26aefb50c2..0000000000
--- a/documentation/overview-manual/figures/source-fetching.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/source-input.png b/documentation/overview-manual/figures/source-input.png
deleted file mode 100644
index f7515058ef..0000000000
--- a/documentation/overview-manual/figures/source-input.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/source-repos.png b/documentation/overview-manual/figures/source-repos.png
deleted file mode 100644
index 603300b6d2..0000000000
--- a/documentation/overview-manual/figures/source-repos.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/user-configuration.png b/documentation/overview-manual/figures/user-configuration.png
deleted file mode 100644
index c298401fc3..0000000000
--- a/documentation/overview-manual/figures/user-configuration.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/yocto-environment-ref.png b/documentation/overview-manual/figures/yocto-environment-ref.png
deleted file mode 100644
index 650c6c8030..0000000000
--- a/documentation/overview-manual/figures/yocto-environment-ref.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/figures/yp-download.png b/documentation/overview-manual/figures/yp-download.png
deleted file mode 100644
index 5770be6883..0000000000
--- a/documentation/overview-manual/figures/yp-download.png
+++ /dev/null
Binary files differ
diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml
deleted file mode 100644
index 59741d2e35..0000000000
--- a/documentation/overview-manual/overview-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='overview-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<!--
1928vim: expandtab tw=80 ts=4
1929-->
diff --git a/documentation/overview-manual/overview-development-environment.xml b/documentation/overview-manual/overview-development-environment.xml
deleted file mode 100644
index 7d177cecca..0000000000
--- a/documentation/overview-manual/overview-development-environment.xml
+++ /dev/null
@@ -1,2890 +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='overview-development-environment'>
6<title>The Yocto Project Development Environment</title>
7
8<para>
9 This chapter takes a look at the Yocto Project development
10 environment and also provides a detailed look at what goes on during
11 development in that environment.
12 The chapter provides Yocto Project Development environment concepts that
13 help you understand how work is accomplished in an open source environment,
14 which is very different as compared to work accomplished in a closed,
15 proprietary environment.
16</para>
17
18<para>
19 Specifically, this chapter addresses open source philosophy, workflows,
20 Git, source repositories, licensing, recipe syntax, and development
21 syntax.
22</para>
23
24<section id='yp-intro'>
25 <title>Introduction</title>
26
27 <para>
28 The Yocto Project is an open-source collaboration project whose
29 focus is for developers of embedded Linux systems.
30 Among other things, the Yocto Project uses an
31 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
32 The build system, which is based on the OpenEmbedded (OE) project and
33 uses the
34 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> tool,
35 constructs complete Linux images for architectures based on ARM, MIPS,
36 PowerPC, x86 and x86-64.
37 <note>
38 Historically, the OpenEmbedded build system, which is the
39 combination of BitBake and OE components, formed a reference
40 build host that was known as
41 "<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>"
42 (<emphasis>Pah</emphasis>-kee).
43 The term "Poky", as used throughout the Yocto Project Documentation
44 set, can have different meanings.
45 </note>
46 The Yocto Project provides various ancillary tools for the embedded
47 developer and also features the Sato reference User Interface, which
48 is optimized for stylus-driven, low-resolution screens.
49 </para>
50
51 <mediaobject>
52 <imageobject>
53 <imagedata fileref="figures/YP-flow-diagram.png"
54 format="PNG" align='center' width="8in"/>
55 </imageobject>
56 </mediaobject>
57
58 <para>
59 Here are some highlights for the Yocto Project:
60 </para>
61
62 <itemizedlist>
63 <listitem><para>
64 Provides a recent Linux kernel along with a set of system
65 commands and libraries suitable for the embedded
66 environment.
67 </para></listitem>
68 <listitem><para>
69 Makes available system components such as X11, GTK+, Qt,
70 Clutter, and SDL (among others) so you can create a rich user
71 experience on devices that have display hardware.
72 For devices that do not have a display or where you wish to
73 use alternative UI frameworks, these components need not be
74 installed.
75 </para></listitem>
76 <listitem><para>
77 Creates a focused and stable core compatible with the
78 OpenEmbedded project with which you can easily and reliably
79 build and develop.
80 </para></listitem>
81 <listitem><para>
82 Fully supports a wide range of hardware and device emulation
83 through the Quick EMUlator (QEMU).
84 </para></listitem>
85 <listitem><para>
86 Provides a layer mechanism that allows you to easily extend
87 the system, make customizations, and keep them organized.
88 </para></listitem>
89 </itemizedlist>
90
91 <para>
92 You can use the Yocto Project to generate images for many kinds
93 of devices.
94 As mentioned earlier, the Yocto Project supports creation of
95 reference images that you can boot within and emulate using QEMU.
96 The standard example machines target QEMU full-system
97 emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and
98 PowerPC architectures.
99 Beyond emulation, you can use the layer mechanism to extend
100 support to just about any platform that Linux can run on and that
101 a toolchain can target.
102 </para>
103
104 <para>
105 Another Yocto Project feature is the Sato reference User
106 Interface.
107 This optional UI that is based on GTK+ is intended for devices with
108 restricted screen sizes and is included as part of the
109 OpenEmbedded Core layer so that developers can test parts of the
110 software stack.
111 </para>
112
113 <para>
114 While the Yocto Project does not provide a strict testing framework,
115 it does provide or generate for you artifacts that let you perform
116 target-level and emulated testing and debugging.
117 Additionally, if you are an
118 <trademark class='trade'>Eclipse</trademark> IDE user, you can
119 install an Eclipse Yocto Plug-in to allow you to develop within that
120 familiar environment.
121 </para>
122
123 <para>
124 By default, using the Yocto Project to build an image creates a Poky
125 distribution.
126 However, you can create your own distribution by providing key
127 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>.
128 A good example is Angstrom, which has had a distribution
129 based on the Yocto Project since its inception.
130 Other examples include commercial distributions like
131 <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
132 <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
133 <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
134 and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
135 See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
136 section in the Yocto Project Development Tasks Manual for more
137 information.
138 </para>
139</section>
140
141<section id='open-source-philosophy'>
142 <title>Open Source Philosophy</title>
143
144 <para>
145 Open source philosophy is characterized by software development
146 directed by peer production and collaboration through an active
147 community of developers.
148 Contrast this to the more standard centralized development models
149 used by commercial software companies where a finite set of developers
150 produces a product for sale using a defined set of procedures that
151 ultimately result in an end product whose architecture and source
152 material are closed to the public.
153 </para>
154
155 <para>
156 Open source projects conceptually have differing concurrent agendas,
157 approaches, and production.
158 These facets of the development process can come from anyone in the
159 public (community) that has a stake in the software project.
160 The open source environment contains new copyright, licensing, domain,
161 and consumer issues that differ from the more traditional development
162 environment.
163 In an open source environment, the end product, source material,
164 and documentation are all available to the public at no cost.
165 </para>
166
167 <para>
168 A benchmark example of an open source project is the Linux kernel,
169 which was initially conceived and created by Finnish computer science
170 student Linus Torvalds in 1991.
171 Conversely, a good example of a non-open source project is the
172 <trademark class='registered'>Windows</trademark> family of operating
173 systems developed by
174 <trademark class='registered'>Microsoft</trademark> Corporation.
175 </para>
176
177 <para>
178 Wikipedia has a good historical description of the Open Source
179 Philosophy
180 <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
181 You can also find helpful information on how to participate in the
182 Linux Community
183 <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
184 </para>
185</section>
186
187<section id='workflows'>
188 <title>Workflows</title>
189
190 <para>
191 This section provides workflow concepts using the Yocto Project and
192 Git.
193 In particular, the information covers basic practices that describe
194 roles and actions in a collaborative development environment.
195 <note>
196 If you are familiar with this type of development environment, you
197 might not want to read this section.
198 </note>
199 </para>
200
201 <para>
202 The Yocto Project files are maintained using Git in "master"
203 branches whose Git histories track every change and whose structures
204 provides branches for all diverging functionality.
205 Although there is no need to use Git, many open source projects do so.
206 <para>
207
208 </para>
209 For the Yocto Project, a key individual called the "maintainer" is
210 responsible for the "master" branch of a given Git repository.
211 The "master" branch is the “upstream” repository from which final or
212 most recent builds of the project occur.
213 The maintainer is responsible for accepting changes from other
214 developers and for organizing the underlying branch structure to
215 reflect release strategies and so forth.
216 <note>For information on finding out who is responsible for (maintains)
217 a particular area of code, see the
218 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
219 section of the Yocto Project Development Tasks Manual.
220 </note>
221 </para>
222
223 <para>
224 The Yocto Project <filename>poky</filename> Git repository also has an
225 upstream contribution Git repository named
226 <filename>poky-contrib</filename>.
227 You can see all the branches in this repository using the web interface
228 of the
229 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
230 within the "Poky Support" area.
231 These branches temporarily hold changes to the project that have been
232 submitted or committed by the Yocto Project development team and by
233 community members who contribute to the project.
234 The maintainer determines if the changes are qualified to be moved
235 from the "contrib" branches into the "master" branch of the Git
236 repository.
237 </para>
238
239 <para>
240 Developers (including contributing community members) create and
241 maintain cloned repositories of the upstream "master" branch.
242 The cloned repositories are local to their development platforms and
243 are used to develop changes.
244 When a developer is satisfied with a particular feature or change,
245 they "push" the changes to the appropriate "contrib" repository.
246 </para>
247
248 <para>
249 Developers are responsible for keeping their local repository
250 up-to-date with "master".
251 They are also responsible for straightening out any conflicts that
252 might arise within files that are being worked on simultaneously by
253 more than one person.
254 All this work is done locally on the developer’s machine before
255 anything is pushed to a "contrib" area and examined at the maintainer’s
256 level.
257 </para>
258
259 <para>
260 A somewhat formal method exists by which developers commit changes
261 and push them into the "contrib" area and subsequently request that
262 the maintainer include them into "master".
263 This process is called “submitting a patch” or "submitting a change."
264 For information on submitting patches and changes, see the
265 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
266 section in the Yocto Project Development Tasks Manual.
267 </para>
268
269 <para>
270 To summarize the development workflow: a single point of entry
271 exists for changes into the project’s "master" branch of the
272 Git repository, which is controlled by the project’s maintainer.
273 And, a set of developers exist who independently develop, test, and
274 submit changes to "contrib" areas for the maintainer to examine.
275 The maintainer then chooses which changes are going to become a
276 permanent part of the project.
277 </para>
278
279 <para>
280 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
281 </para>
282
283 <para>
284 While each development environment is unique, there are some best
285 practices or methods that help development run smoothly.
286 The following list describes some of these practices.
287 For more information about Git workflows, see the workflow topics in
288 the
289 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
290 <itemizedlist>
291 <listitem><para>
292 <emphasis>Make Small Changes:</emphasis>
293 It is best to keep the changes you commit small as compared to
294 bundling many disparate changes into a single commit.
295 This practice not only keeps things manageable but also allows
296 the maintainer to more easily include or refuse changes.</para>
297
298 <para>It is also good practice to leave the repository in a
299 state that allows you to still successfully build your project.
300 In other words, do not commit half of a feature,
301 then add the other half as a separate, later commit.
302 Each commit should take you from one buildable project state
303 to another buildable state.
304 </para></listitem>
305 <listitem><para>
306 <emphasis>Use Branches Liberally:</emphasis>
307 It is very easy to create, use, and delete local branches in
308 your working Git repository.
309 You can name these branches anything you like.
310 It is helpful to give them names associated with the particular
311 feature or change on which you are working.
312 Once you are done with a feature or change and have merged it
313 into your local master branch, simply discard the temporary
314 branch.
315 </para></listitem>
316 <listitem><para>
317 <emphasis>Merge Changes:</emphasis>
318 The <filename>git merge</filename> command allows you to take
319 the changes from one branch and fold them into another branch.
320 This process is especially helpful when more than a single
321 developer might be working on different parts of the same
322 feature.
323 Merging changes also automatically identifies any collisions
324 or "conflicts" that might happen as a result of the same lines
325 of code being altered by two different developers.
326 </para></listitem>
327 <listitem><para>
328 <emphasis>Manage Branches:</emphasis>
329 Because branches are easy to use, you should use a system
330 where branches indicate varying levels of code readiness.
331 For example, you can have a "work" branch to develop in, a
332 "test" branch where the code or change is tested, a "stage"
333 branch where changes are ready to be committed, and so forth.
334 As your project develops, you can merge code across the
335 branches to reflect ever-increasing stable states of the
336 development.
337 </para></listitem>
338 <listitem><para>
339 <emphasis>Use Push and Pull:</emphasis>
340 The push-pull workflow is based on the concept of developers
341 "pushing" local commits to a remote repository, which is
342 usually a contribution repository.
343 This workflow is also based on developers "pulling" known
344 states of the project down into their local development
345 repositories.
346 The workflow easily allows you to pull changes submitted by
347 other developers from the upstream repository into your
348 work area ensuring that you have the most recent software
349 on which to develop.
350 The Yocto Project has two scripts named
351 <filename>create-pull-request</filename> and
352 <filename>send-pull-request</filename> that ship with the
353 release to facilitate this workflow.
354 You can find these scripts in the <filename>scripts</filename>
355 folder of the
356 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
357 For information on how to use these scripts, see the
358 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
359 section in the Yocto Project Development Tasks Manual.
360 </para></listitem>
361 <listitem><para>
362 <emphasis>Patch Workflow:</emphasis>
363 This workflow allows you to notify the maintainer through an
364 email that you have a change (or patch) you would like
365 considered for the "master" branch of the Git repository.
366 To send this type of change, you format the patch and then
367 send the email using the Git commands
368 <filename>git format-patch</filename> and
369 <filename>git send-email</filename>.
370 For information on how to use these scripts, see the
371 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
372 section in the Yocto Project Development Tasks Manual.
373 </para></listitem>
374 </itemizedlist>
375 </para>
376</section>
377
378<section id='git'>
379 <title>Git</title>
380
381 <para>
382 The Yocto Project makes extensive use of Git, which is a
383 free, open source distributed version control system.
384 Git supports distributed development, non-linear development,
385 and can handle large projects.
386 It is best that you have some fundamental understanding
387 of how Git tracks projects and how to work with Git if
388 you are going to use the Yocto Project for development.
389 This section provides a quick overview of how Git works and
390 provides you with a summary of some essential Git commands.
391 <note><title>Notes</title>
392 <itemizedlist>
393 <listitem><para>
394 For more information on Git, see
395 <ulink url='http://git-scm.com/documentation'></ulink>.
396 </para></listitem>
397 <listitem><para>
398 If you need to download Git, it is recommended that you add
399 Git to your system through your distribution's "software
400 store" (e.g. for Ubuntu, use the Ubuntu Software feature).
401 For the Git download page, see
402 <ulink url='http://git-scm.com/download'></ulink>.
403 </para></listitem>
404 <listitem><para>
405 For examples beyond the limited few in this section on how
406 to use Git with the Yocto Project, see the
407 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
408 section in the Yocto Project Development Tasks Manual.
409 </para></listitem>
410 </itemizedlist>
411 </note>
412 </para>
413
414 <section id='repositories-tags-and-branches'>
415 <title>Repositories, Tags, and Branches</title>
416
417 <para>
418 As mentioned briefly in the previous section and also in the
419 "<link linkend='workflows'>Workflows</link>" section,
420 the Yocto Project maintains source repositories at
421 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
422 If you look at this web-interface of the repositories, each item
423 is a separate Git repository.
424 </para>
425
426 <para>
427 Git repositories use branching techniques that track content
428 change (not files) within a project (e.g. a new feature or updated
429 documentation).
430 Creating a tree-like structure based on project divergence allows
431 for excellent historical information over the life of a project.
432 This methodology also allows for an environment from which you can
433 do lots of local experimentation on projects as you develop
434 changes or new features.
435 </para>
436
437 <para>
438 A Git repository represents all development efforts for a given
439 project.
440 For example, the Git repository <filename>poky</filename> contains
441 all changes and developments for Poky over the course of its
442 entire life.
443 That means that all changes that make up all releases are captured.
444 The repository maintains a complete history of changes.
445 </para>
446
447 <para>
448 You can create a local copy of any repository by "cloning" it
449 with the <filename>git clone</filename> command.
450 When you clone a Git repository, you end up with an identical
451 copy of the repository on your development system.
452 Once you have a local copy of a repository, you can take steps to
453 develop locally.
454 For examples on how to clone Git repositories, see the
455 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
456 section in the Yocto Project Development Tasks Manual.
457 </para>
458
459 <para>
460 It is important to understand that Git tracks content change and
461 not files.
462 Git uses "branches" to organize different development efforts.
463 For example, the <filename>poky</filename> repository has
464 several branches that include the current "&DISTRO_NAME_NO_CAP;"
465 branch, the "master" branch, and many branches for past
466 Yocto Project releases.
467 You can see all the branches by going to
468 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
469 clicking on the
470 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
471 link beneath the "Branch" heading.
472 </para>
473
474 <para>
475 Each of these branches represents a specific area of development.
476 The "master" branch represents the current or most recent
477 development.
478 All other branches represent offshoots of the "master" branch.
479 </para>
480
481 <para>
482 When you create a local copy of a Git repository, the copy has
483 the same set of branches as the original.
484 This means you can use Git to create a local working area
485 (also called a branch) that tracks a specific development branch
486 from the upstream source Git repository.
487 in other words, you can define your local Git environment to
488 work on any development branch in the repository.
489 To help illustrate, consider the following example Git commands:
490 <literallayout class='monospaced'>
491 $ cd ~
492 $ git clone git://git.yoctoproject.org/poky
493 $ cd poky
494 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
495 </literallayout>
496 In the previous example after moving to the home directory, the
497 <filename>git clone</filename> command creates a
498 local copy of the upstream <filename>poky</filename> Git repository.
499 By default, Git checks out the "master" branch for your work.
500 After changing the working directory to the new local repository
501 (i.e. <filename>poky</filename>), the
502 <filename>git checkout</filename> command creates
503 and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which
504 tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.
505 Changes you make while in this branch would ultimately affect
506 the upstream "&DISTRO_NAME_NO_CAP;" branch of the
507 <filename>poky</filename> repository.
508 </para>
509
510 <para>
511 It is important to understand that when you create and checkout a
512 local working branch based on a branch name,
513 your local environment matches the "tip" of that particular
514 development branch at the time you created your local branch,
515 which could be different from the files in the "master" branch
516 of the upstream repository.
517 In other words, creating and checking out a local branch based on
518 the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
519 cloning and checking out the "master" branch if the repository.
520 Keep reading to see how you create a local snapshot of a Yocto
521 Project Release.
522 </para>
523
524 <para>
525 Git uses "tags" to mark specific changes in a repository.
526 Typically, a tag is used to mark a special point such as the final
527 change before a project is released.
528 You can see the tags used with the <filename>poky</filename> Git
529 repository by going to
530 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
531 clicking on the
532 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
533 link beneath the "Tag" heading.
534 </para>
535
536 <para>
537 Some key tags for the <filename>poky</filename> are
538 <filename>jethro-14.0.3</filename>,
539 <filename>morty-16.0.1</filename>,
540 <filename>pyro-17.0.0</filename>, and
541 <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
542 These tags represent Yocto Project releases.
543 </para>
544
545 <para>
546 When you create a local copy of the Git repository, you also
547 have access to all the tags in the upstream repository.
548 Similar to branches, you can create and checkout a local working
549 Git branch based on a tag name.
550 When you do this, you get a snapshot of the Git repository that
551 reflects the state of the files when the change was made associated
552 with that tag.
553 The most common use is to checkout a working branch that matches
554 a specific Yocto Project release.
555 Here is an example:
556 <literallayout class='monospaced'>
557 $ cd ~
558 $ git clone git://git.yoctoproject.org/poky
559 $ cd poky
560 $ git fetch --all --tags --prune
561 $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
562 </literallayout>
563 In this example, the name of the top-level directory of your
564 local Yocto Project repository is <filename>poky</filename>.
565 After moving to the <filename>poky</filename> directory, the
566 <filename>git fetch</filename> command makes all the upstream
567 tags available locally in your repository.
568 Finally, the <filename>git checkout</filename> command
569 creates and checks out a branch named "my-pyro-17.0.0" that is
570 based on the specific change upstream in the repository
571 associated with the "pyro-17.0.0" tag.
572 The files in your repository now exactly match that particular
573 Yocto Project release as it is tagged in the upstream Git
574 repository.
575 It is important to understand that when you create and
576 checkout a local working branch based on a tag, your environment
577 matches a specific point in time and not the entire development
578 branch (i.e. the "tip" of the branch).
579 </para>
580 </section>
581
582 <section id='basic-commands'>
583 <title>Basic Commands</title>
584
585 <para>
586 Git has an extensive set of commands that lets you manage changes
587 and perform collaboration over the life of a project.
588 Conveniently though, you can manage with a small set of basic
589 operations and workflows once you understand the basic
590 philosophy behind Git.
591 You do not have to be an expert in Git to be functional.
592 A good place to look for instruction on a minimal set of Git
593 commands is
594 <ulink url='http://git-scm.com/documentation'>here</ulink>.
595 </para>
596
597 <para>
598 If you do not know much about Git, you should educate
599 yourself by visiting the links previously mentioned.
600 </para>
601
602 <para>
603 The following list of Git commands briefly describes some basic
604 Git operations as a way to get started.
605 As with any set of commands, this list (in most cases) simply shows
606 the base command and omits the many arguments they support.
607 See the Git documentation for complete descriptions and strategies
608 on how to use these commands:
609 <itemizedlist>
610 <listitem><para>
611 <emphasis><filename>git init</filename>:</emphasis>
612 Initializes an empty Git repository.
613 You cannot use Git commands unless you have a
614 <filename>.git</filename> repository.
615 </para></listitem>
616 <listitem><para id='git-commands-clone'>
617 <emphasis><filename>git clone</filename>:</emphasis>
618 Creates a local clone of a Git repository that is on
619 equal footing with a fellow developer’s Git repository
620 or an upstream repository.
621 </para></listitem>
622 <listitem><para>
623 <emphasis><filename>git add</filename>:</emphasis>
624 Locally stages updated file contents to the index that
625 Git uses to track changes.
626 You must stage all files that have changed before you
627 can commit them.
628 </para></listitem>
629 <listitem><para>
630 <emphasis><filename>git commit</filename>:</emphasis>
631 Creates a local "commit" that documents the changes you
632 made.
633 Only changes that have been staged can be committed.
634 Commits are used for historical purposes, for determining
635 if a maintainer of a project will allow the change,
636 and for ultimately pushing the change from your local
637 Git repository into the project’s upstream repository.
638 </para></listitem>
639 <listitem><para>
640 <emphasis><filename>git status</filename>:</emphasis>
641 Reports any modified files that possibly need to be
642 staged and gives you a status of where you stand regarding
643 local commits as compared to the upstream repository.
644 </para></listitem>
645 <listitem><para>
646 <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis>
647 Changes your working branch.
648 This command is analogous to "cd".
649 </para></listitem>
650 <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis>
651 Creates and checks out a working branch on your local
652 machine that you can use to isolate your work.
653 It is a good idea to use local branches when adding
654 specific features or changes.
655 Using isolated branches facilitates easy removal of
656 changes if they do not work out.
657 </para></listitem>
658 <listitem><para><emphasis><filename>git branch</filename>:</emphasis>
659 Displays the existing local branches associated with your
660 local repository.
661 The branch that you have currently checked out is noted
662 with an asterisk character.
663 </para></listitem>
664 <listitem><para>
665 <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
666 Deletes an existing local branch.
667 You need to be in a local branch other than the one you
668 are deleting in order to delete
669 <replaceable>branch-name</replaceable>.
670 </para></listitem>
671 <listitem><para>
672 <emphasis><filename>git pull</filename>:</emphasis>
673 Retrieves information from an upstream Git repository
674 and places it in your local Git repository.
675 You use this command to make sure you are synchronized with
676 the repository from which you are basing changes
677 (.e.g. the "master" branch).
678 </para></listitem>
679 <listitem><para>
680 <emphasis><filename>git push</filename>:</emphasis>
681 Sends all your committed local changes to the upstream Git
682 repository that your local repository is tracking
683 (e.g. a contribution repository).
684 The maintainer of the project draws from these repositories
685 to merge changes (commits) into the appropriate branch
686 of project's upstream repository.
687 </para></listitem>
688 <listitem><para>
689 <emphasis><filename>git merge</filename>:</emphasis>
690 Combines or adds changes from one
691 local branch of your repository with another branch.
692 When you create a local Git repository, the default branch
693 is named "master".
694 A typical workflow is to create a temporary branch that is
695 based off "master" that you would use for isolated work.
696 You would make your changes in that isolated branch,
697 stage and commit them locally, switch to the "master"
698 branch, and then use the <filename>git merge</filename>
699 command to apply the changes from your isolated branch
700 into the currently checked out branch (e.g. "master").
701 After the merge is complete and if you are done with
702 working in that isolated branch, you can safely delete
703 the isolated branch.
704 </para></listitem>
705 <listitem><para>
706 <emphasis><filename>git cherry-pick</filename>:</emphasis>
707 Choose and apply specific commits from one branch
708 into another branch.
709 There are times when you might not be able to merge
710 all the changes in one branch with
711 another but need to pick out certain ones.
712 </para></listitem>
713 <listitem><para>
714 <emphasis><filename>gitk</filename>:</emphasis>
715 Provides a GUI view of the branches and changes in your
716 local Git repository.
717 This command is a good way to graphically see where things
718 have diverged in your local repository.
719 <note>
720 You need to install the <filename>gitk</filename>
721 package on your development system to use this
722 command.
723 </note>
724 </para></listitem>
725 <listitem><para>
726 <emphasis><filename>git log</filename>:</emphasis>
727 Reports a history of your commits to the repository.
728 This report lists all commits regardless of whether you
729 have pushed them upstream or not.
730 </para></listitem>
731 <listitem><para>
732 <emphasis><filename>git diff</filename>:</emphasis>
733 Displays line-by-line differences between a local
734 working file and the same file as understood by Git.
735 This command is useful to see what you have changed
736 in any given file.
737 </para></listitem>
738 </itemizedlist>
739 </para>
740 </section>
741</section>
742
743<section id='yocto-project-repositories'>
744 <title>Yocto Project Source Repositories</title>
745
746 <para>
747 The Yocto Project team maintains complete source repositories for all
748 Yocto Project files at
749 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
750 This web-based source code browser is organized into categories by
751 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
752 so forth.
753 From the interface, you can click on any particular item in the "Name"
754 column and see the URL at the bottom of the page that you need to clone
755 a Git repository for that particular item.
756 Having a local Git repository of the
757 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
758 which is usually named "poky", allows
759 you to make changes, contribute to the history, and ultimately enhance
760 the Yocto Project's tools, Board Support Packages, and so forth.
761 </para>
762
763 <para>
764 For any supported release of Yocto Project, you can also go to the
765 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
766 select the "Downloads" tab and get a released tarball of the
767 <filename>poky</filename> repository or any supported BSP tarballs.
768 Unpacking these tarballs gives you a snapshot of the released
769 files.
770 <note><title>Notes</title>
771 <itemizedlist>
772 <listitem><para>
773 The recommended method for setting up the Yocto Project
774 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
775 and the files for supported BSPs
776 (e.g., <filename>meta-intel</filename>) is to use
777 <link linkend='git'>Git</link> to create a local copy of
778 the upstream repositories.
779 </para></listitem>
780 <listitem><para>
781 Be sure to always work in matching branches for both
782 the selected BSP repository and the
783 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
784 (i.e. <filename>poky</filename>) repository.
785 For example, if you have checked out the "master" branch
786 of <filename>poky</filename> and you are going to use
787 <filename>meta-intel</filename>, be sure to checkout the
788 "master" branch of <filename>meta-intel</filename>.
789 </para></listitem>
790 </itemizedlist>
791 </note>
792 </para>
793
794 <para>
795 In summary, here is where you can get the project files needed for
796 development:
797 <itemizedlist>
798 <listitem><para id='source-repositories'>
799 <emphasis>
800 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink>
801 </emphasis>
802 This area contains IDE Plugins, Matchbox, Poky, Poky Support,
803 Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
804 You can create local copies of Git repositories for each of
805 these areas.</para>
806
807 <para>
808 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
809 For steps on how to view and access these upstream Git
810 repositories, see the
811 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
812 Section in the Yocto Project Development Tasks Manual.
813 </para></listitem>
814 <listitem><para><anchor id='index-downloads' />
815 <emphasis>
816 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
817 </emphasis>
818 This is an index of releases such as
819 the <trademark class='trade'>Eclipse</trademark>
820 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
821 for cross-development toolchains, and all released versions of
822 Yocto Project in the form of images or tarballs.
823 Downloading and extracting these files does not produce a local
824 copy of the Git repository but rather a snapshot of a
825 particular release or image.</para>
826
827 <para>
828 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
829 For steps on how to view and access these files, see the
830 "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
831 section in the Yocto Project Development Tasks Manual.
832 </para></listitem>
833 <listitem><para id='downloads-page'>
834 <emphasis>"Downloads" page for the
835 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
836 </emphasis></para>
837
838 <para role="writernotes">This section will change due to
839 reworking of the YP Website.</para>
840
841 <para>The Yocto Project website includes a "Downloads" tab
842 that allows you to download any Yocto Project
843 release and Board Support Package (BSP) in tarball form.
844 The tarballs are similar to those found in the
845 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
846
847 <para>
848 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
849 For steps on how to use the "Downloads" page, see the
850 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
851 section in the Yocto Project Development Tasks Manual.
852 </para></listitem>
853 </itemizedlist>
854 </para>
855</section>
856
857<section id='licensing'>
858 <title>Licensing</title>
859
860 <para>
861 Because open source projects are open to the public, they have
862 different licensing structures in place.
863 License evolution for both Open Source and Free Software has an
864 interesting history.
865 If you are interested in this history, you can find basic information
866 here:
867 <itemizedlist>
868 <listitem><para>
869 <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
870 </para></listitem>
871 <listitem><para>
872 <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink>
873 </para></listitem>
874 </itemizedlist>
875 </para>
876
877 <para>
878 In general, the Yocto Project is broadly licensed under the
879 Massachusetts Institute of Technology (MIT) License.
880 MIT licensing permits the reuse of software within proprietary
881 software as long as the license is distributed with that software.
882 MIT is also compatible with the GNU General Public License (GPL).
883 Patches to the Yocto Project follow the upstream licensing scheme.
884 You can find information on the MIT license
885 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
886 You can find information on the GNU GPL
887 <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>.
888 </para>
889
890 <para>
891 When you build an image using the Yocto Project, the build process
892 uses a known list of licenses to ensure compliance.
893 You can find this list in the
894 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
895 at <filename>meta/files/common-licenses</filename>.
896 Once the build completes, the list of all licenses found and used
897 during that build are kept in the
898 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
899 at <filename>tmp/deploy/licenses</filename>.
900 </para>
901
902 <para>
903 If a module requires a license that is not in the base list, the
904 build process generates a warning during the build.
905 These tools make it easier for a developer to be certain of the
906 licenses with which their shipped products must comply.
907 However, even with these tools it is still up to the developer to
908 resolve potential licensing issues.
909 </para>
910
911 <para>
912 The base list of licenses used by the build process is a combination
913 of the Software Package Data Exchange (SPDX) list and the Open
914 Source Initiative (OSI) projects.
915 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of
916 the Linux Foundation that maintains a specification for a standard
917 format for communicating the components, licenses, and copyrights
918 associated with a software package.
919 <ulink url='http://opensource.org'>OSI</ulink> is a corporation
920 dedicated to the Open Source Definition and the effort for reviewing
921 and approving licenses that conform to the Open Source Definition
922 (OSD).
923 </para>
924
925 <para>
926 You can find a list of the combined SPDX and OSI licenses that the
927 Yocto Project uses in the
928 <filename>meta/files/common-licenses</filename> directory in your
929 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
930 </para>
931
932 <para>
933 For information that can help you maintain compliance with various
934 open source licensing during the lifecycle of a product created using
935 the Yocto Project, see the
936 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
937 section in the Yocto Project Development Tasks Manual.
938 </para>
939</section>
940
941<section id='recipe-syntax'>
942 <title>Recipe Syntax</title>
943
944 <para>
945 Understanding recipe file syntax is important for
946 writing recipes.
947 The following list overviews the basic items that make up a
948 BitBake recipe file.
949 For more complete BitBake syntax descriptions, see the
950 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
951 chapter of the BitBake User Manual.
952 <itemizedlist>
953 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
954 Variable assignments allow a value to be assigned to a
955 variable.
956 The assignment can be static text or might include
957 the contents of other variables.
958 In addition to the assignment, appending and prepending
959 operations are also supported.</para>
960 <para>The following example shows some of the ways
961 you can use variables in recipes:
962 <literallayout class='monospaced'>
963 S = "${WORKDIR}/postfix-${PV}"
964 CFLAGS += "-DNO_ASM"
965 SRC_URI_append = " file://fixup.patch"
966 </literallayout>
967 </para></listitem>
968 <listitem><para><emphasis>Functions:</emphasis>
969 Functions provide a series of actions to be performed.
970 You usually use functions to override the default
971 implementation of a task function or to complement
972 a default function (i.e. append or prepend to an
973 existing function).
974 Standard functions use <filename>sh</filename> shell
975 syntax, although access to OpenEmbedded variables and
976 internal methods are also available.</para>
977 <para>The following is an example function from the
978 <filename>sed</filename> recipe:
979 <literallayout class='monospaced'>
980 do_install () {
981 autotools_do_install
982 install -d ${D}${base_bindir}
983 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
984 rmdir ${D}${bindir}/
985 }
986 </literallayout>
987 It is also possible to implement new functions that
988 are called between existing tasks as long as the
989 new functions are not replacing or complementing the
990 default functions.
991 You can implement functions in Python
992 instead of shell.
993 Both of these options are not seen in the majority of
994 recipes.</para></listitem>
995 <listitem><para><emphasis>Keywords:</emphasis>
996 BitBake recipes use only a few keywords.
997 You use keywords to include common
998 functions (<filename>inherit</filename>), load parts
999 of a recipe from other files
1000 (<filename>include</filename> and
1001 <filename>require</filename>) and export variables
1002 to the environment (<filename>export</filename>).</para>
1003 <para>The following example shows the use of some of
1004 these keywords:
1005 <literallayout class='monospaced'>
1006 export POSTCONF = "${STAGING_BINDIR}/postconf"
1007 inherit autoconf
1008 require otherfile.inc
1009 </literallayout>
1010 </para></listitem>
1011 <listitem><para><emphasis>Comments:</emphasis>
1012 Any lines that begin with the hash character
1013 (<filename>#</filename>) are treated as comment lines
1014 and are ignored:
1015 <literallayout class='monospaced'>
1016 # This is a comment
1017 </literallayout>
1018 </para></listitem>
1019 </itemizedlist>
1020 </para>
1021
1022 <para>
1023 This next list summarizes the most important and most commonly
1024 used parts of the recipe syntax.
1025 For more information on these parts of the syntax, you can
1026 reference the
1027 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1028 chapter in the BitBake User Manual.
1029 <itemizedlist>
1030 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1031 Use the backward slash (<filename>\</filename>)
1032 character to split a statement over multiple lines.
1033 Place the slash character at the end of the line that
1034 is to be continued on the next line:
1035 <literallayout class='monospaced'>
1036 VAR = "A really long \
1037 line"
1038 </literallayout>
1039 <note>
1040 You cannot have any characters including spaces
1041 or tabs after the slash character.
1042 </note>
1043 </para></listitem>
1044 <listitem><para>
1045 <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1046 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
1047 access the contents of a variable:
1048 <literallayout class='monospaced'>
1049 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1050 </literallayout>
1051 <note>
1052 It is important to understand that the value of a
1053 variable expressed in this form does not get
1054 substituted automatically.
1055 The expansion of these expressions happens
1056 on-demand later (e.g. usually when a function that
1057 makes reference to the variable executes).
1058 This behavior ensures that the values are most
1059 appropriate for the context in which they are
1060 finally used.
1061 On the rare occasion that you do need the variable
1062 expression to be expanded immediately, you can use
1063 the <filename>:=</filename> operator instead of
1064 <filename>=</filename> when you make the
1065 assignment, but this is not generally needed.
1066 </note>
1067 </para></listitem>
1068 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1069 Use double quotes around the value in all variable
1070 assignments.
1071 <literallayout class='monospaced'>
1072 VAR1 = "${OTHERVAR}"
1073 VAR2 = "The version is ${PV}"
1074 </literallayout>
1075 </para></listitem>
1076 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1077 Conditional assignment is used to assign a value to
1078 a variable, but only when the variable is currently
1079 unset.
1080 Use the question mark followed by the equal sign
1081 (<filename>?=</filename>) to make a "soft" assignment
1082 used for conditional assignment.
1083 Typically, "soft" assignments are used in the
1084 <filename>local.conf</filename> file for variables
1085 that are allowed to come through from the external
1086 environment.
1087 </para>
1088 <para>Here is an example where
1089 <filename>VAR1</filename> is set to "New value" if
1090 it is currently empty.
1091 However, if <filename>VAR1</filename> has already been
1092 set, it remains unchanged:
1093 <literallayout class='monospaced'>
1094 VAR1 ?= "New value"
1095 </literallayout>
1096 In this next example, <filename>VAR1</filename>
1097 is left with the value "Original value":
1098 <literallayout class='monospaced'>
1099 VAR1 = "Original value"
1100 VAR1 ?= "New value"
1101 </literallayout>
1102 </para></listitem>
1103 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1104 Use the plus character followed by the equals sign
1105 (<filename>+=</filename>) to append values to existing
1106 variables.
1107 <note>
1108 This operator adds a space between the existing
1109 content of the variable and the new content.
1110 </note></para>
1111 <para>Here is an example:
1112 <literallayout class='monospaced'>
1113 SRC_URI += "file://fix-makefile.patch"
1114 </literallayout>
1115 </para></listitem>
1116 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1117 Use the equals sign followed by the plus character
1118 (<filename>=+</filename>) to prepend values to existing
1119 variables.
1120 <note>
1121 This operator adds a space between the new content
1122 and the existing content of the variable.
1123 </note></para>
1124 <para>Here is an example:
1125 <literallayout class='monospaced'>
1126 VAR =+ "Starts"
1127 </literallayout>
1128 </para></listitem>
1129 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1130 Use the <filename>_append</filename> operator to
1131 append values to existing variables.
1132 This operator does not add any additional space.
1133 Also, the operator is applied after all the
1134 <filename>+=</filename>, and
1135 <filename>=+</filename> operators have been applied and
1136 after all <filename>=</filename> assignments have
1137 occurred.
1138 </para>
1139 <para>The following example shows the space being
1140 explicitly added to the start to ensure the appended
1141 value is not merged with the existing value:
1142 <literallayout class='monospaced'>
1143 SRC_URI_append = " file://fix-makefile.patch"
1144 </literallayout>
1145 You can also use the <filename>_append</filename>
1146 operator with overrides, which results in the actions
1147 only being performed for the specified target or
1148 machine:
1149 <literallayout class='monospaced'>
1150 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1151 </literallayout>
1152 </para></listitem>
1153 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1154 Use the <filename>_prepend</filename> operator to
1155 prepend values to existing variables.
1156 This operator does not add any additional space.
1157 Also, the operator is applied after all the
1158 <filename>+=</filename>, and
1159 <filename>=+</filename> operators have been applied and
1160 after all <filename>=</filename> assignments have
1161 occurred.
1162 </para>
1163 <para>The following example shows the space being
1164 explicitly added to the end to ensure the prepended
1165 value is not merged with the existing value:
1166 <literallayout class='monospaced'>
1167 CFLAGS_prepend = "-I${S}/myincludes "
1168 </literallayout>
1169 You can also use the <filename>_prepend</filename>
1170 operator with overrides, which results in the actions
1171 only being performed for the specified target or
1172 machine:
1173 <literallayout class='monospaced'>
1174 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1175 </literallayout>
1176 </para></listitem>
1177 <listitem><para><emphasis>Overrides:</emphasis> -
1178 You can use overrides to set a value conditionally,
1179 typically based on how the recipe is being built.
1180 For example, to set the
1181 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1182 variable's value to "standard/base" for any target
1183 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1184 except for qemuarm where it should be set to
1185 "standard/arm-versatile-926ejs", you would do the
1186 following:
1187 <literallayout class='monospaced'>
1188 KBRANCH = "standard/base"
1189 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1190 </literallayout>
1191 Overrides are also used to separate alternate values
1192 of a variable in other situations.
1193 For example, when setting variables such as
1194 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1195 and
1196 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1197 that are specific to individual packages produced by
1198 a recipe, you should always use an override that
1199 specifies the name of the package.
1200 </para></listitem>
1201 <listitem><para><emphasis>Indentation:</emphasis>
1202 Use spaces for indentation rather than than tabs.
1203 For shell functions, both currently work.
1204 However, it is a policy decision of the Yocto Project
1205 to use tabs in shell functions.
1206 Realize that some layers have a policy to use spaces
1207 for all indentation.
1208 </para></listitem>
1209 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1210 For more advanced processing, it is possible to use
1211 Python code during variable assignments (e.g.
1212 search and replacement on a variable).</para>
1213 <para>You indicate Python code using the
1214 <filename>${@<replaceable>python_code</replaceable>}</filename>
1215 syntax for the variable assignment:
1216 <literallayout class='monospaced'>
1217 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1218 </literallayout>
1219 </para></listitem>
1220 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1221 Write shell functions as if you were writing a shell
1222 script when you describe a list of actions to take.
1223 You should ensure that your script works with a generic
1224 <filename>sh</filename> and that it does not require
1225 any <filename>bash</filename> or other shell-specific
1226 functionality.
1227 The same considerations apply to various system
1228 utilities (e.g. <filename>sed</filename>,
1229 <filename>grep</filename>, <filename>awk</filename>,
1230 and so forth) that you might wish to use.
1231 If in doubt, you should check with multiple
1232 implementations - including those from BusyBox.
1233 </para></listitem>
1234 </itemizedlist>
1235 </para>
1236</section>
1237
1238<section id="development-concepts">
1239 <title>Development Concepts</title>
1240
1241 <para>
1242 This section takes a more detailed look inside the development
1243 process.
1244 The following diagram represents development at a high level.
1245 The remainder of this chapter expands on the fundamental input, output,
1246 process, and
1247 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>) blocks
1248 that make up development in the Yocto Project environment.
1249 </para>
1250
1251 <para id='general-yocto-environment-figure'>
1252 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
1253 </para>
1254
1255 <para>
1256 In general, development consists of several functional areas:
1257 <itemizedlist>
1258 <listitem><para><emphasis>User Configuration:</emphasis>
1259 Metadata you can use to control the build process.
1260 </para></listitem>
1261 <listitem><para><emphasis>Metadata Layers:</emphasis>
1262 Various layers that provide software, machine, and
1263 distro Metadata.</para></listitem>
1264 <listitem><para><emphasis>Source Files:</emphasis>
1265 Upstream releases, local projects, and SCMs.</para></listitem>
1266 <listitem><para><emphasis>Build System:</emphasis>
1267 Processes under the control of
1268 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
1269 This block expands on how BitBake fetches source, applies
1270 patches, completes compilation, analyzes output for package
1271 generation, creates and tests packages, generates images, and
1272 generates cross-development tools.</para></listitem>
1273 <listitem><para><emphasis>Package Feeds:</emphasis>
1274 Directories containing output packages (RPM, DEB or IPK),
1275 which are subsequently used in the construction of an image or
1276 SDK, produced by the build system.
1277 These feeds can also be copied and shared using a web server or
1278 other means to facilitate extending or updating existing
1279 images on devices at runtime if runtime package management is
1280 enabled.</para></listitem>
1281 <listitem><para><emphasis>Images:</emphasis>
1282 Images produced by the development process.
1283 </para></listitem>
1284 <listitem><para><emphasis>Application Development SDK:</emphasis>
1285 Cross-development tools that are produced along with an image
1286 or separately with BitBake.</para></listitem>
1287 </itemizedlist>
1288 </para>
1289
1290 <section id="user-configuration">
1291 <title>User Configuration</title>
1292
1293 <para>
1294 User configuration helps define the build.
1295 Through user configuration, you can tell BitBake the
1296 target architecture for which you are building the image,
1297 where to store downloaded source, and other build properties.
1298 </para>
1299
1300 <para>
1301 The following figure shows an expanded representation of the
1302 "User Configuration" box of the
1303 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1304 </para>
1305
1306 <para>
1307 <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" />
1308 </para>
1309
1310 <para>
1311 BitBake needs some basic configuration files in order to complete
1312 a build.
1313 These files are <filename>*.conf</filename> files.
1314 The minimally necessary ones reside as example files in the
1315 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1316 For simplicity, this section refers to the Source Directory as
1317 the "Poky Directory."
1318 </para>
1319
1320 <para>
1321 When you clone the <filename>poky</filename> Git repository or you
1322 download and unpack a Yocto Project release, you can set up the
1323 Source Directory to be named anything you want.
1324 For this discussion, the cloned repository uses the default
1325 name <filename>poky</filename>.
1326 <note>
1327 The Poky repository is primarily an aggregation of existing
1328 repositories.
1329 It is not a canonical upstream source.
1330 </note>
1331 </para>
1332
1333 <para>
1334 The <filename>meta-poky</filename> layer inside Poky contains
1335 a <filename>conf</filename> directory that has example
1336 configuration files.
1337 These example files are used as a basis for creating actual
1338 configuration files when you source the build environment
1339 script
1340 (i.e.
1341 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
1342 </para>
1343
1344 <para>
1345 Sourcing the build environment script creates a
1346 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1347 if one does not already exist.
1348 BitBake uses the Build Directory for all its work during builds.
1349 The Build Directory has a <filename>conf</filename> directory that
1350 contains default versions of your <filename>local.conf</filename>
1351 and <filename>bblayers.conf</filename> configuration files.
1352 These default configuration files are created only if versions
1353 do not already exist in the Build Directory at the time you
1354 source the build environment setup script.
1355 </para>
1356
1357 <para>
1358 Because the Poky repository is fundamentally an aggregation of
1359 existing repositories, some users might be familiar with running
1360 the <filename>&OE_INIT_FILE;</filename> script in the context
1361 of separate OpenEmbedded-Core and BitBake repositories rather than a
1362 single Poky repository.
1363 This discussion assumes the script is executed from within a cloned
1364 or unpacked version of Poky.
1365 </para>
1366
1367 <para>
1368 Depending on where the script is sourced, different sub-scripts
1369 are called to set up the Build Directory (Yocto or OpenEmbedded).
1370 Specifically, the script
1371 <filename>scripts/oe-setup-builddir</filename> inside the
1372 poky directory sets up the Build Directory and seeds the directory
1373 (if necessary) with configuration files appropriate for the
1374 Yocto Project development environment.
1375 <note>
1376 The <filename>scripts/oe-setup-builddir</filename> script
1377 uses the <filename>$TEMPLATECONF</filename> variable to
1378 determine which sample configuration files to locate.
1379 </note>
1380 </para>
1381
1382 <para>
1383 The <filename>local.conf</filename> file provides many
1384 basic variables that define a build environment.
1385 Here is a list of a few.
1386 To see the default configurations in a <filename>local.conf</filename>
1387 file created by the build environment script, see the
1388 <filename>local.conf.sample</filename> in the
1389 <filename>meta-poky</filename> layer:
1390 <itemizedlist>
1391 <listitem><para><emphasis>Parallelism Options:</emphasis>
1392 Controlled by the
1393 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
1394 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
1395 and
1396 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
1397 variables.</para></listitem>
1398 <listitem><para><emphasis>Target Machine Selection:</emphasis>
1399 Controlled by the
1400 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1401 variable.</para></listitem>
1402 <listitem><para><emphasis>Download Directory:</emphasis>
1403 Controlled by the
1404 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1405 variable.</para></listitem>
1406 <listitem><para><emphasis>Shared State Directory:</emphasis>
1407 Controlled by the
1408 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
1409 variable.</para></listitem>
1410 <listitem><para><emphasis>Build Output:</emphasis>
1411 Controlled by the
1412 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
1413 variable.</para></listitem>
1414 </itemizedlist>
1415 <note>
1416 Configurations set in the <filename>conf/local.conf</filename>
1417 file can also be set in the
1418 <filename>conf/site.conf</filename> and
1419 <filename>conf/auto.conf</filename> configuration files.
1420 </note>
1421 </para>
1422
1423 <para>
1424 The <filename>bblayers.conf</filename> file tells BitBake what
1425 layers you want considered during the build.
1426 By default, the layers listed in this file include layers
1427 minimally needed by the build system.
1428 However, you must manually add any custom layers you have created.
1429 You can find more information on working with the
1430 <filename>bblayers.conf</filename> file in the
1431 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1432 section in the Yocto Project Development Tasks Manual.
1433 </para>
1434
1435 <para>
1436 The files <filename>site.conf</filename> and
1437 <filename>auto.conf</filename> are not created by the environment
1438 initialization script.
1439 If you want the <filename>site.conf</filename> file, you need to
1440 create that yourself.
1441 The <filename>auto.conf</filename> file is typically created by
1442 an autobuilder:
1443 <itemizedlist>
1444 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
1445 You can use the <filename>conf/site.conf</filename>
1446 configuration file to configure multiple build directories.
1447 For example, suppose you had several build environments and
1448 they shared some common features.
1449 You can set these default build properties here.
1450 A good example is perhaps the packaging format to use
1451 through the
1452 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1453 variable.</para>
1454 <para>One useful scenario for using the
1455 <filename>conf/site.conf</filename> file is to extend your
1456 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
1457 variable to include the path to a
1458 <filename>conf/site.conf</filename>.
1459 Then, when BitBake looks for Metadata using
1460 <filename>BBPATH</filename>, it finds the
1461 <filename>conf/site.conf</filename> file and applies your
1462 common configurations found in the file.
1463 To override configurations in a particular build directory,
1464 alter the similar configurations within that build
1465 directory's <filename>conf/local.conf</filename> file.
1466 </para></listitem>
1467 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
1468 The file is usually created and written to by
1469 an autobuilder.
1470 The settings put into the file are typically the same as
1471 you would find in the <filename>conf/local.conf</filename>
1472 or the <filename>conf/site.conf</filename> files.
1473 </para></listitem>
1474 </itemizedlist>
1475 </para>
1476
1477 <para>
1478 You can edit all configuration files to further define
1479 any particular build environment.
1480 This process is represented by the "User Configuration Edits"
1481 box in the figure.
1482 </para>
1483
1484 <para>
1485 When you launch your build with the
1486 <filename>bitbake <replaceable>target</replaceable></filename>
1487 command, BitBake sorts out the configurations to ultimately
1488 define your build environment.
1489 It is important to understand that the OpenEmbedded build system
1490 reads the configuration files in a specific order:
1491 <filename>site.conf</filename>, <filename>auto.conf</filename>,
1492 and <filename>local.conf</filename>.
1493 And, the build system applies the normal assignment statement
1494 rules.
1495 Because the files are parsed in a specific order, variable
1496 assignments for the same variable could be affected.
1497 For example, if the <filename>auto.conf</filename> file and
1498 the <filename>local.conf</filename> set
1499 <replaceable>variable1</replaceable> to different values, because
1500 the build system parses <filename>local.conf</filename> after
1501 <filename>auto.conf</filename>,
1502 <replaceable>variable1</replaceable> is assigned the value from
1503 the <filename>local.conf</filename> file.
1504 </para>
1505 </section>
1506
1507 <section id="metadata-machine-configuration-and-policy-configuration">
1508 <title>Metadata, Machine Configuration, and Policy Configuration</title>
1509
1510 <para>
1511 The previous section described the user configurations that
1512 define BitBake's global behavior.
1513 This section takes a closer look at the layers the build system
1514 uses to further control the build.
1515 These layers provide Metadata for the software, machine, and
1516 policy.
1517 </para>
1518
1519 <para>
1520 In general, three types of layer input exist:
1521 <itemizedlist>
1522 <listitem><para><emphasis>Policy Configuration:</emphasis>
1523 Distribution Layers provide top-level or general
1524 policies for the image or SDK being built.
1525 For example, this layer would dictate whether BitBake
1526 produces RPM or IPK packages.</para></listitem>
1527 <listitem><para><emphasis>Machine Configuration:</emphasis>
1528 Board Support Package (BSP) layers provide machine
1529 configurations.
1530 This type of information is specific to a particular
1531 target architecture.</para></listitem>
1532 <listitem><para><emphasis>Metadata:</emphasis>
1533 Software layers contain user-supplied recipe files,
1534 patches, and append files.
1535 </para></listitem>
1536 </itemizedlist>
1537 </para>
1538
1539 <para>
1540 The following figure shows an expanded representation of the
1541 Metadata, Machine Configuration, and Policy Configuration input
1542 (layers) boxes of the
1543 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1544 </para>
1545
1546 <para>
1547 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
1548 </para>
1549
1550 <para>
1551 In general, all layers have a similar structure.
1552 They all contain a licensing file
1553 (e.g. <filename>COPYING</filename>) if the layer is to be
1554 distributed, a <filename>README</filename> file as good practice
1555 and especially if the layer is to be distributed, a
1556 configuration directory, and recipe directories.
1557 </para>
1558
1559 <para>
1560 The Yocto Project has many layers that can be used.
1561 You can see a web-interface listing of them on the
1562 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
1563 page.
1564 The layers are shown at the bottom categorized under
1565 "Yocto Metadata Layers."
1566 These layers are fundamentally a subset of the
1567 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
1568 which lists all layers provided by the OpenEmbedded community.
1569 <note>
1570 Layers exist in the Yocto Project Source Repositories that
1571 cannot be found in the OpenEmbedded Metadata Index.
1572 These layers are either deprecated or experimental in nature.
1573 </note>
1574 </para>
1575
1576 <para>
1577 BitBake uses the <filename>conf/bblayers.conf</filename> file,
1578 which is part of the user configuration, to find what layers it
1579 should be using as part of the build.
1580 </para>
1581
1582 <para>
1583 For more information on layers, see the
1584 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1585 section in the Yocto Project Development Tasks Manual.
1586 </para>
1587
1588 <section id="distro-layer">
1589 <title>Distro Layer</title>
1590
1591 <para>
1592 The distribution layer provides policy configurations for your
1593 distribution.
1594 Best practices dictate that you isolate these types of
1595 configurations into their own layer.
1596 Settings you provide in
1597 <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
1598 similar
1599 settings that BitBake finds in your
1600 <filename>conf/local.conf</filename> file in the Build
1601 Directory.
1602 </para>
1603
1604 <para>
1605 The following list provides some explanation and references
1606 for what you typically find in the distribution layer:
1607 <itemizedlist>
1608 <listitem><para><emphasis>classes:</emphasis>
1609 Class files (<filename>.bbclass</filename>) hold
1610 common functionality that can be shared among
1611 recipes in the distribution.
1612 When your recipes inherit a class, they take on the
1613 settings and functions for that class.
1614 You can read more about class files in the
1615 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
1616 section of the Yocto Reference Manual.
1617 </para></listitem>
1618 <listitem><para><emphasis>conf:</emphasis>
1619 This area holds configuration files for the
1620 layer (<filename>conf/layer.conf</filename>),
1621 the distribution
1622 (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
1623 and any distribution-wide include files.
1624 </para></listitem>
1625 <listitem><para><emphasis>recipes-*:</emphasis>
1626 Recipes and append files that affect common
1627 functionality across the distribution.
1628 This area could include recipes and append files
1629 to add distribution-specific configuration,
1630 initialization scripts, custom image recipes,
1631 and so forth.</para></listitem>
1632 </itemizedlist>
1633 </para>
1634 </section>
1635
1636 <section id="bsp-layer">
1637 <title>BSP Layer</title>
1638
1639 <para>
1640 The BSP Layer provides machine configurations.
1641 Everything in this layer is specific to the machine for which
1642 you are building the image or the SDK.
1643 A common structure or form is defined for BSP layers.
1644 You can learn more about this structure in the
1645 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
1646 <note>
1647 In order for a BSP layer to be considered compliant with the
1648 Yocto Project, it must meet some structural requirements.
1649 </note>
1650 </para>
1651
1652 <para>
1653 The BSP Layer's configuration directory contains
1654 configuration files for the machine
1655 (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and,
1656 of course, the layer (<filename>conf/layer.conf</filename>).
1657 </para>
1658
1659 <para>
1660 The remainder of the layer is dedicated to specific recipes
1661 by function: <filename>recipes-bsp</filename>,
1662 <filename>recipes-core</filename>,
1663 <filename>recipes-graphics</filename>, and
1664 <filename>recipes-kernel</filename>.
1665 Metadata can exist for multiple formfactors, graphics
1666 support systems, and so forth.
1667 <note>
1668 While the figure shows several <filename>recipes-*</filename>
1669 directories, not all these directories appear in all
1670 BSP layers.
1671 </note>
1672 </para>
1673 </section>
1674
1675 <section id="software-layer">
1676 <title>Software Layer</title>
1677
1678 <para>
1679 The software layer provides the Metadata for additional
1680 software packages used during the build.
1681 This layer does not include Metadata that is specific to the
1682 distribution or the machine, which are found in their
1683 respective layers.
1684 </para>
1685
1686 <para>
1687 This layer contains any new recipes that your project needs
1688 in the form of recipe files.
1689 </para>
1690 </section>
1691 </section>
1692
1693 <section id="sources-dev-environment">
1694 <title>Sources</title>
1695
1696 <para>
1697 In order for the OpenEmbedded build system to create an image or
1698 any target, it must be able to access source files.
1699 The
1700 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1701 represents source files using the "Upstream Project Releases",
1702 "Local Projects", and "SCMs (optional)" boxes.
1703 The figure represents mirrors, which also play a role in locating
1704 source files, with the "Source Mirror(s)" box.
1705 </para>
1706
1707 <para>
1708 The method by which source files are ultimately organized is
1709 a function of the project.
1710 For example, for released software, projects tend to use tarballs
1711 or other archived files that can capture the state of a release
1712 guaranteeing that it is statically represented.
1713 On the other hand, for a project that is more dynamic or
1714 experimental in nature, a project might keep source files in a
1715 repository controlled by a Source Control Manager (SCM) such as
1716 Git.
1717 Pulling source from a repository allows you to control
1718 the point in the repository (the revision) from which you want to
1719 build software.
1720 Finally, a combination of the two might exist, which would give the
1721 consumer a choice when deciding where to get source files.
1722 </para>
1723
1724 <para>
1725 BitBake uses the
1726 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1727 variable to point to source files regardless of their location.
1728 Each recipe must have a <filename>SRC_URI</filename> variable
1729 that points to the source.
1730 </para>
1731
1732 <para>
1733 Another area that plays a significant role in where source files
1734 come from is pointed to by the
1735 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1736 variable.
1737 This area is a cache that can hold previously downloaded source.
1738 You can also instruct the OpenEmbedded build system to create
1739 tarballs from Git repositories, which is not the default behavior,
1740 and store them in the <filename>DL_DIR</filename> by using the
1741 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1742 variable.
1743 </para>
1744
1745 <para>
1746 Judicious use of a <filename>DL_DIR</filename> directory can
1747 save the build system a trip across the Internet when looking
1748 for files.
1749 A good method for using a download directory is to have
1750 <filename>DL_DIR</filename> point to an area outside of your
1751 Build Directory.
1752 Doing so allows you to safely delete the Build Directory
1753 if needed without fear of removing any downloaded source file.
1754 </para>
1755
1756 <para>
1757 The remainder of this section provides a deeper look into the
1758 source files and the mirrors.
1759 Here is a more detailed look at the source file area of the
1760 base figure:
1761 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
1762 </para>
1763
1764 <section id='upstream-project-releases'>
1765 <title>Upstream Project Releases</title>
1766
1767 <para>
1768 Upstream project releases exist anywhere in the form of an
1769 archived file (e.g. tarball or zip file).
1770 These files correspond to individual recipes.
1771 For example, the figure uses specific releases each for
1772 BusyBox, Qt, and Dbus.
1773 An archive file can be for any released product that can be
1774 built using a recipe.
1775 </para>
1776 </section>
1777
1778 <section id='local-projects'>
1779 <title>Local Projects</title>
1780
1781 <para>
1782 Local projects are custom bits of software the user provides.
1783 These bits reside somewhere local to a project - perhaps
1784 a directory into which the user checks in items (e.g.
1785 a local directory containing a development source tree
1786 used by the group).
1787 </para>
1788
1789 <para>
1790 The canonical method through which to include a local project
1791 is to use the
1792 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
1793 class to include that local project.
1794 You use either the <filename>local.conf</filename> or a
1795 recipe's append file to override or set the
1796 recipe to point to the local directory on your disk to pull
1797 in the whole source tree.
1798 </para>
1799
1800 <para>
1801 For information on how to use the
1802 <filename>externalsrc</filename> class, see the
1803 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>"
1804 section.
1805 </para>
1806 </section>
1807
1808 <section id='scms'>
1809 <title>Source Control Managers (Optional)</title>
1810
1811 <para>
1812 Another place the build system can get source files from is
1813 through an SCM such as Git or Subversion.
1814 In this case, a repository is cloned or checked out.
1815 The
1816 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1817 task inside BitBake uses
1818 the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1819 variable and the argument's prefix to determine the correct
1820 fetcher module.
1821 </para>
1822
1823 <note>
1824 For information on how to have the OpenEmbedded build system
1825 generate tarballs for Git repositories and place them in the
1826 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1827 directory, see the
1828 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1829 variable.
1830 </note>
1831
1832 <para>
1833 When fetching a repository, BitBake uses the
1834 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1835 variable to determine the specific revision from which to
1836 build.
1837 </para>
1838 </section>
1839
1840 <section id='source-mirrors'>
1841 <title>Source Mirror(s)</title>
1842
1843 <para>
1844 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
1845 The
1846 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
1847 and
1848 <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink>
1849 variables point to these, respectively.
1850 BitBake checks pre-mirrors before looking upstream for any
1851 source files.
1852 Pre-mirrors are appropriate when you have a shared directory
1853 that is not a directory defined by the
1854 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1855 variable.
1856 A Pre-mirror typically points to a shared directory that is
1857 local to your organization.
1858 </para>
1859
1860 <para>
1861 Regular mirrors can be any site across the Internet that is
1862 used as an alternative location for source code should the
1863 primary site not be functioning for some reason or another.
1864 </para>
1865 </section>
1866 </section>
1867
1868 <section id="package-feeds-dev-environment">
1869 <title>Package Feeds</title>
1870
1871 <para>
1872 When the OpenEmbedded build system generates an image or an SDK,
1873 it gets the packages from a package feed area located in the
1874 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1875 The
1876 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1877 shows this package feeds area in the upper-right corner.
1878 </para>
1879
1880 <para>
1881 This section looks a little closer into the package feeds area used
1882 by the build system.
1883 Here is a more detailed look at the area:
1884 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
1885 </para>
1886
1887 <para>
1888 Package feeds are an intermediary step in the build process.
1889 The OpenEmbedded build system provides classes to generate
1890 different package types, and you specify which classes to enable
1891 through the
1892 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1893 variable.
1894 Before placing the packages into package feeds,
1895 the build process validates them with generated output quality
1896 assurance checks through the
1897 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
1898 class.
1899 </para>
1900
1901 <para>
1902 The package feed area resides in the Build Directory.
1903 The directory the build system uses to temporarily store packages
1904 is determined by a combination of variables and the particular
1905 package manager in use.
1906 See the "Package Feeds" box in the illustration and note the
1907 information to the right of that area.
1908 In particular, the following defines where package files are
1909 kept:
1910 <itemizedlist>
1911 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
1912 Defined as <filename>tmp/deploy</filename> in the Build
1913 Directory.
1914 </para></listitem>
1915 <listitem><para><filename>DEPLOY_DIR_*</filename>:
1916 Depending on the package manager used, the package type
1917 sub-folder.
1918 Given RPM, IPK, or DEB packaging and tarball creation, the
1919 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>,
1920 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>,
1921 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>,
1922 or
1923 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>,
1924 variables are used, respectively.
1925 </para></listitem>
1926 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
1927 Defines architecture-specific sub-folders.
1928 For example, packages could exist for the i586 or qemux86
1929 architectures.
1930 </para></listitem>
1931 </itemizedlist>
1932 </para>
1933
1934 <para>
1935 BitBake uses the <filename>do_package_write_*</filename> tasks to
1936 generate packages and place them into the package holding area (e.g.
1937 <filename>do_package_write_ipk</filename> for IPK packages).
1938 See the
1939 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>",
1940 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>",
1941 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>",
1942 and
1943 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>"
1944 sections for additional information.
1945 As an example, consider a scenario where an IPK packaging manager
1946 is being used and package architecture support for both i586
1947 and qemux86 exist.
1948 Packages for the i586 architecture are placed in
1949 <filename>build/tmp/deploy/ipk/i586</filename>, while packages for
1950 the qemux86 architecture are placed in
1951 <filename>build/tmp/deploy/ipk/qemux86</filename>.
1952 </para>
1953 </section>
1954
1955 <section id='bitbake-dev-environment'>
1956 <title>BitBake</title>
1957
1958 <para>
1959 The OpenEmbedded build system uses
1960 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
1961 to produce images.
1962 You can see from the
1963 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1964 the BitBake area consists of several functional areas.
1965 This section takes a closer look at each of those areas.
1966 </para>
1967
1968 <para>
1969 Separate documentation exists for the BitBake tool.
1970 See the
1971 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
1972 for reference material on BitBake.
1973 </para>
1974
1975 <section id='source-fetching-dev-environment'>
1976 <title>Source Fetching</title>
1977
1978 <para>
1979 The first stages of building a recipe are to fetch and unpack
1980 the source code:
1981 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
1982 </para>
1983
1984 <para>
1985 The
1986 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1987 and
1988 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1989 tasks fetch the source files and unpack them into the work
1990 directory.
1991 <note>
1992 For every local file (e.g. <filename>file://</filename>)
1993 that is part of a recipe's
1994 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1995 statement, the OpenEmbedded build system takes a checksum
1996 of the file for the recipe and inserts the checksum into
1997 the signature for the <filename>do_fetch</filename>.
1998 If any local file has been modified, the
1999 <filename>do_fetch</filename> task and all tasks that
2000 depend on it are re-executed.
2001 </note>
2002 By default, everything is accomplished in the
2003 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
2004 which has a defined structure.
2005 For additional general information on the Build Directory,
2006 see the
2007 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>"
2008 section in the Yocto Project Reference Manual.
2009 </para>
2010
2011 <para>
2012 Unpacked source files are pointed to by the
2013 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
2014 variable.
2015 Each recipe has an area in the Build Directory where the
2016 unpacked source code resides.
2017 The name of that directory for any given recipe is defined from
2018 several different variables.
2019 You can see the variables that define these directories
2020 by looking at the figure:
2021 <itemizedlist>
2022 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> -
2023 The base directory where the OpenEmbedded build system
2024 performs all its work during the build.
2025 </para></listitem>
2026 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> -
2027 The architecture of the built package or packages.
2028 </para></listitem>
2029 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink> -
2030 The operating system of the target device.
2031 </para></listitem>
2032 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> -
2033 The name of the built package.
2034 </para></listitem>
2035 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> -
2036 The version of the recipe used to build the package.
2037 </para></listitem>
2038 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> -
2039 The revision of the recipe used to build the package.
2040 </para></listitem>
2041 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> -
2042 The location within <filename>TMPDIR</filename> where
2043 a specific package is built.
2044 </para></listitem>
2045 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> -
2046 Contains the unpacked source files for a given recipe.
2047 </para></listitem>
2048 </itemizedlist>
2049 </para>
2050 </section>
2051
2052 <section id='patching-dev-environment'>
2053 <title>Patching</title>
2054
2055 <para>
2056 Once source code is fetched and unpacked, BitBake locates
2057 patch files and applies them to the source files:
2058 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
2059 </para>
2060
2061 <para>
2062 The
2063 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
2064 task processes recipes by
2065 using the
2066 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2067 variable to locate applicable patch files, which by default
2068 are <filename>*.patch</filename> or
2069 <filename>*.diff</filename> files, or any file if
2070 "apply=yes" is specified for the file in
2071 <filename>SRC_URI</filename>.
2072 </para>
2073
2074 <para>
2075 BitBake finds and applies multiple patches for a single recipe
2076 in the order in which it finds the patches.
2077 Patches are applied to the recipe's source files located in the
2078 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
2079 directory.
2080 </para>
2081
2082 <para>
2083 For more information on how the source directories are
2084 created, see the
2085 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
2086 section.
2087 </para>
2088 </section>
2089
2090 <section id='configuration-and-compilation-dev-environment'>
2091 <title>Configuration and Compilation</title>
2092
2093 <para>
2094 After source code is patched, BitBake executes tasks that
2095 configure and compile the source code:
2096 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
2097 </para>
2098
2099 <para>
2100 This step in the build process consists of three tasks:
2101 <itemizedlist>
2102 <listitem><para>
2103 <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink>:</emphasis>
2104 This task sets up the two sysroots in
2105 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
2106 (i.e. <filename>recipe-sysroot</filename> and
2107 <filename>recipe-sysroot-native</filename>) so that
2108 the sysroots contain the contents of the
2109 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
2110 tasks of the recipes on which the recipe
2111 containing the tasks depends.
2112 A sysroot exists for both the target and for the native
2113 binaries, which run on the host system.
2114 </para></listitem>
2115 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
2116 This task configures the source by enabling and
2117 disabling any build-time and configuration options for
2118 the software being built.
2119 Configurations can come from the recipe itself as well
2120 as from an inherited class.
2121 Additionally, the software itself might configure itself
2122 depending on the target for which it is being built.
2123 </para>
2124
2125 <para>The configurations handled by the
2126 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
2127 task are specific
2128 to source code configuration for the source code
2129 being built by the recipe.</para>
2130
2131 <para>If you are using the
2132 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
2133 class,
2134 you can add additional configuration options by using
2135 the
2136 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
2137 or
2138 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
2139 variables.
2140 For information on how this variable works within
2141 that class, see the
2142 <filename>meta/classes/autotools.bbclass</filename> file.
2143 </para></listitem>
2144 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
2145 Once a configuration task has been satisfied, BitBake
2146 compiles the source using the
2147 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
2148 task.
2149 Compilation occurs in the directory pointed to by the
2150 <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
2151 variable.
2152 Realize that the <filename>B</filename> directory is, by
2153 default, the same as the
2154 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
2155 directory.</para></listitem>
2156 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
2157 Once compilation is done, BitBake executes the
2158 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
2159 task.
2160 This task copies files from the <filename>B</filename>
2161 directory and places them in a holding area pointed to
2162 by the
2163 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
2164 variable.</para></listitem>
2165 </itemizedlist>
2166 </para>
2167 </section>
2168
2169 <section id='package-splitting-dev-environment'>
2170 <title>Package Splitting</title>
2171
2172 <para>
2173 After source code is configured and compiled, the
2174 OpenEmbedded build system analyzes
2175 the results and splits the output into packages:
2176 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
2177 </para>
2178
2179 <para>
2180 The
2181 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
2182 and
2183 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
2184 tasks combine to analyze
2185 the files found in the
2186 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> directory
2187 and split them into subsets based on available packages and
2188 files.
2189 The analyzing process involves the following as well as other
2190 items: splitting out debugging symbols,
2191 looking at shared library dependencies between packages,
2192 and looking at package relationships.
2193 The <filename>do_packagedata</filename> task creates package
2194 metadata based on the analysis such that the
2195 OpenEmbedded build system can generate the final packages.
2196 Working, staged, and intermediate results of the analysis
2197 and package splitting process use these areas:
2198 <itemizedlist>
2199 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink> -
2200 The destination directory for packages before they are
2201 split.
2202 </para></listitem>
2203 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> -
2204 A shared, global-state directory that holds data
2205 generated during the packaging process.
2206 </para></listitem>
2207 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink> -
2208 A temporary work area used by the
2209 <filename>do_package</filename> task.
2210 </para></listitem>
2211 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink> -
2212 The parent directory for packages after they have
2213 been split.
2214 </para></listitem>
2215 </itemizedlist>
2216 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
2217 variable defines the files that go into each package in
2218 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>.
2219 If you want details on how this is accomplished, you can
2220 look at the
2221 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package</filename></ulink>
2222 class.
2223 </para>
2224
2225 <para>
2226 Depending on the type of packages being created (RPM, DEB, or
2227 IPK), the <filename>do_package_write_*</filename> task
2228 creates the actual packages and places them in the
2229 Package Feed area, which is
2230 <filename>${TMPDIR}/deploy</filename>.
2231 You can see the
2232 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
2233 section for more detail on that part of the build process.
2234 <note>
2235 Support for creating feeds directly from the
2236 <filename>deploy/*</filename> directories does not exist.
2237 Creating such feeds usually requires some kind of feed
2238 maintenance mechanism that would upload the new packages
2239 into an official package feed (e.g. the
2240 Ångström distribution).
2241 This functionality is highly distribution-specific
2242 and thus is not provided out of the box.
2243 </note>
2244 </para>
2245 </section>
2246
2247 <section id='image-generation-dev-environment'>
2248 <title>Image Generation</title>
2249
2250 <para>
2251 Once packages are split and stored in the Package Feeds area,
2252 the OpenEmbedded build system uses BitBake to generate the
2253 root filesystem image:
2254 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
2255 </para>
2256
2257 <para>
2258 The image generation process consists of several stages and
2259 depends on several tasks and variables.
2260 The
2261 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
2262 task creates the root filesystem (file and directory structure)
2263 for an image.
2264 This task uses several key variables to help create the list
2265 of packages to actually install:
2266 <itemizedlist>
2267 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
2268 Lists out the base set of packages to install from
2269 the Package Feeds area.</para></listitem>
2270 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
2271 Specifies packages that should not be installed.
2272 </para></listitem>
2273 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
2274 Specifies features to include in the image.
2275 Most of these features map to additional packages for
2276 installation.</para></listitem>
2277 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>:
2278 Specifies the package backend to use and consequently
2279 helps determine where to locate packages within the
2280 Package Feeds area.</para></listitem>
2281 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>:
2282 Determines the language(s) for which additional
2283 language support packages are installed.
2284 </para></listitem>
2285 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>:
2286 The final list of packages passed to the package manager
2287 for installation into the image.
2288 </para></listitem>
2289 </itemizedlist>
2290 </para>
2291
2292 <para>
2293 With
2294 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink>
2295 pointing to the location of the filesystem under construction and
2296 the <filename>PACKAGE_INSTALL</filename> variable providing the
2297 final list of packages to install, the root file system is
2298 created.
2299 </para>
2300
2301 <para>
2302 Package installation is under control of the package manager
2303 (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or
2304 not package management is enabled for the target.
2305 At the end of the process, if package management is not
2306 enabled for the target, the package manager's data files
2307 are deleted from the root filesystem.
2308 As part of the final stage of package installation, postinstall
2309 scripts that are part of the packages are run.
2310 Any scripts that fail to run
2311 on the build host are run on the target when the target system
2312 is first booted.
2313 If you are using a
2314 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
2315 all the post installation scripts must succeed during the
2316 package installation phase since the root filesystem is
2317 read-only.
2318 </para>
2319
2320 <para>
2321 The final stages of the <filename>do_rootfs</filename> task
2322 handle post processing.
2323 Post processing includes creation of a manifest file and
2324 optimizations.
2325 </para>
2326
2327 <para>
2328 The manifest file (<filename>.manifest</filename>) resides
2329 in the same directory as the root filesystem image.
2330 This file lists out, line-by-line, the installed packages.
2331 The manifest file is useful for the
2332 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
2333 class, for example, to determine whether or not to run
2334 specific tests.
2335 See the
2336 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink>
2337 variable for additional information.
2338 </para>
2339
2340 <para>
2341 Optimizing processes run across the image include
2342 <filename>mklibs</filename>, <filename>prelink</filename>,
2343 and any other post-processing commands as defined by the
2344 <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink>
2345 variable.
2346 The <filename>mklibs</filename> process optimizes the size
2347 of the libraries, while the
2348 <filename>prelink</filename> process optimizes the dynamic
2349 linking of shared libraries to reduce start up time of
2350 executables.
2351 </para>
2352
2353 <para>
2354 After the root filesystem is built, processing begins on
2355 the image through the
2356 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
2357 task.
2358 The build system runs any pre-processing commands as defined
2359 by the
2360 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink>
2361 variable.
2362 This variable specifies a list of functions to call before
2363 the OpenEmbedded build system creates the final image output
2364 files.
2365 </para>
2366
2367 <para>
2368 The OpenEmbedded build system dynamically creates
2369 <filename>do_image_*</filename> tasks as needed, based
2370 on the image types specified in the
2371 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2372 variable.
2373 The process turns everything into an image file or a set of
2374 image files and compresses the root filesystem image to reduce
2375 the overall size of the image.
2376 The formats used for the root filesystem depend on the
2377 <filename>IMAGE_FSTYPES</filename> variable.
2378 </para>
2379
2380 <para>
2381 As an example, a dynamically created task when creating a
2382 particular image <replaceable>type</replaceable> would take the
2383 following form:
2384 <literallayout class='monospaced'>
2385 do_image_<replaceable>type</replaceable>[depends]
2386 </literallayout>
2387 So, if the <replaceable>type</replaceable> as specified by the
2388 <filename>IMAGE_FSTYPES</filename> were
2389 <filename>ext4</filename>, the dynamically generated task
2390 would be as follows:
2391 <literallayout class='monospaced'>
2392 do_image_ext4[depends]
2393 </literallayout>
2394 </para>
2395
2396 <para>
2397 The final task involved in image creation is the
2398 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink>
2399 task.
2400 This task completes the image by applying any image
2401 post processing as defined through the
2402 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink>
2403 variable.
2404 The variable specifies a list of functions to call once the
2405 OpenEmbedded build system has created the final image output
2406 files.
2407 </para>
2408
2409 <note>
2410 The entire image generation process is run under Pseudo.
2411 Running under Pseudo ensures that the files in the root
2412 filesystem have correct ownership.
2413 </note>
2414 </section>
2415
2416 <section id='sdk-generation-dev-environment'>
2417 <title>SDK Generation</title>
2418
2419 <para>
2420 The OpenEmbedded build system uses BitBake to generate the
2421 Software Development Kit (SDK) installer script for both the
2422 standard and extensible SDKs:
2423 <imagedata fileref="figures/sdk-generation.png" align="center" />
2424 </para>
2425
2426 <note>
2427 For more information on the cross-development toolchain
2428 generation, see the
2429 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
2430 section.
2431 For information on advantages gained when building a
2432 cross-development toolchain using the
2433 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
2434 task, see the
2435 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
2436 section in the Yocto Project Application Development and the
2437 Extensible Software Development Kit (SDK) manual.
2438 </note>
2439
2440 <para>
2441 Like image generation, the SDK script process consists of
2442 several stages and depends on many variables.
2443 The <filename>do_populate_sdk</filename> and
2444 <filename>do_populate_sdk_ext</filename> tasks use these
2445 key variables to help create the list of packages to actually
2446 install.
2447 For information on the variables listed in the figure, see the
2448 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
2449 section.
2450 </para>
2451
2452 <para>
2453 The <filename>do_populate_sdk</filename> task helps create
2454 the standard SDK and handles two parts: a target part and a
2455 host part.
2456 The target part is the part built for the target hardware and
2457 includes libraries and headers.
2458 The host part is the part of the SDK that runs on the
2459 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>.
2460 </para>
2461
2462 <para>
2463 The <filename>do_populate_sdk_ext</filename> task helps create
2464 the extensible SDK and handles host and target parts
2465 differently than its counter part does for the standard SDK.
2466 For the extensible SDK, the task encapsulates the build system,
2467 which includes everything needed (host and target) for the SDK.
2468 </para>
2469
2470 <para>
2471 Regardless of the type of SDK being constructed, the
2472 tasks perform some cleanup after which a cross-development
2473 environment setup script and any needed configuration files
2474 are created.
2475 The final output is the Cross-development
2476 toolchain installation script (<filename>.sh</filename> file),
2477 which includes the environment setup script.
2478 </para>
2479 </section>
2480
2481 <section id='stamp-files-and-the-rerunning-of-tasks'>
2482 <title>Stamp Files and the Rerunning of Tasks</title>
2483
2484 <para>
2485 For each task that completes successfully, BitBake writes a
2486 stamp file into the
2487 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
2488 directory.
2489 The beginning of the stamp file's filename is determined by the
2490 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink>
2491 variable, and the end of the name consists of the task's name
2492 and current
2493 <link linkend='overview-checksums'>input checksum</link>.
2494 <note>
2495 This naming scheme assumes that
2496 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
2497 is "OEBasicHash", which is almost always the case in
2498 current OpenEmbedded.
2499 </note>
2500 To determine if a task needs to be rerun, BitBake checks if a
2501 stamp file with a matching input checksum exists for the task.
2502 If such a stamp file exists, the task's output is assumed to
2503 exist and still be valid.
2504 If the file does not exist, the task is rerun.
2505 <note>
2506 <para>The stamp mechanism is more general than the shared
2507 state (sstate) cache mechanism described in the
2508 "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
2509 section.
2510 BitBake avoids rerunning any task that has a valid
2511 stamp file, not just tasks that can be accelerated through
2512 the sstate cache.</para>
2513 <para>However, you should realize that stamp files only
2514 serve as a marker that some work has been done and that
2515 these files do not record task output.
2516 The actual task output would usually be somewhere in
2517 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
2518 (e.g. in some recipe's
2519 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.)
2520 What the sstate cache mechanism adds is a way to cache task
2521 output that can then be shared between build machines.
2522 </para>
2523 </note>
2524 Since <filename>STAMPS_DIR</filename> is usually a subdirectory
2525 of <filename>TMPDIR</filename>, removing
2526 <filename>TMPDIR</filename> will also remove
2527 <filename>STAMPS_DIR</filename>, which means tasks will
2528 properly be rerun to repopulate <filename>TMPDIR</filename>.
2529 </para>
2530
2531 <para>
2532 If you want some task to always be considered "out of date",
2533 you can mark it with the
2534 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
2535 varflag.
2536 If some other task depends on such a task, then that task will
2537 also always be considered out of date, which might not be what
2538 you want.
2539 </para>
2540
2541 <para>
2542 For details on how to view information about a task's
2543 signature, see the
2544 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
2545 section in the Yocto Project Development Tasks Manual.
2546 </para>
2547 </section>
2548
2549 <section id='setscene-tasks-and-shared-state'>
2550 <title>Setscene Tasks and Shared State</title>
2551
2552 <para>
2553 The description of tasks so far assumes that BitBake needs to
2554 build everything and there are no prebuilt objects available.
2555 BitBake does support skipping tasks if prebuilt objects are
2556 available.
2557 These objects are usually made available in the form of a
2558 shared state (sstate) cache.
2559 <note>
2560 For information on variables affecting sstate, see the
2561 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
2562 and
2563 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
2564 variables.
2565 </note>
2566 </para>
2567
2568 <para>
2569 The idea of a setscene task (i.e
2570 <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
2571 is a version of the task where
2572 instead of building something, BitBake can skip to the end
2573 result and simply place a set of files into specific locations
2574 as needed.
2575 In some cases, it makes sense to have a setscene task variant
2576 (e.g. generating package files in the
2577 <filename>do_package_write_*</filename> task).
2578 In other cases, it does not make sense, (e.g. a
2579 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
2580 task or
2581 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
2582 task) since the work involved would be equal to or greater than
2583 the underlying task.
2584 </para>
2585
2586 <para>
2587 In the OpenEmbedded build system, the common tasks that have
2588 setscene variants are
2589 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>,
2590 <filename>do_package_write_*</filename>,
2591 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>,
2592 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>,
2593 and
2594 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>.
2595 Notice that these are most of the tasks whose output is an
2596 end result.
2597 </para>
2598
2599 <para>
2600 The OpenEmbedded build system has knowledge of the relationship
2601 between these tasks and other tasks that precede them.
2602 For example, if BitBake runs
2603 <filename>do_populate_sysroot_setscene</filename> for
2604 something, there is little point in running any of the
2605 <filename>do_fetch</filename>, <filename>do_unpack</filename>,
2606 <filename>do_patch</filename>,
2607 <filename>do_configure</filename>,
2608 <filename>do_compile</filename>, and
2609 <filename>do_install</filename> tasks.
2610 However, if <filename>do_package</filename> needs to be run,
2611 BitBake would need to run those other tasks.
2612 </para>
2613
2614 <para>
2615 It becomes more complicated if everything can come from an
2616 sstate cache because some objects are simply not required at
2617 all.
2618 For example, you do not need a compiler or native tools, such
2619 as quilt, if there is nothing to compile or patch.
2620 If the <filename>do_package_write_*</filename> packages are
2621 available from sstate, BitBake does not need the
2622 <filename>do_package</filename> task data.
2623 </para>
2624
2625 <para>
2626 To handle all these complexities, BitBake runs in two phases.
2627 The first is the "setscene" stage.
2628 During this stage, BitBake first checks the sstate cache for
2629 any targets it is planning to build.
2630 BitBake does a fast check to see if the object exists rather
2631 than a complete download.
2632 If nothing exists, the second phase, which is the setscene
2633 stage, completes and the main build proceeds.
2634 </para>
2635
2636 <para>
2637 If objects are found in the sstate cache, the OpenEmbedded
2638 build system works backwards from the end targets specified
2639 by the user.
2640 For example, if an image is being built, the OpenEmbedded build
2641 system first looks for the packages needed for that image and
2642 the tools needed to construct an image.
2643 If those are available, the compiler is not needed.
2644 Thus, the compiler is not even downloaded.
2645 If something was found to be unavailable, or the download or
2646 setscene task fails, the OpenEmbedded build system then tries
2647 to install dependencies, such as the compiler, from the cache.
2648 </para>
2649
2650 <para>
2651 The availability of objects in the sstate cache is handled by
2652 the function specified by the
2653 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
2654 variable and returns a list of the objects that are available.
2655 The function specified by the
2656 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
2657 variable is the function that determines whether a given
2658 dependency needs to be followed, and whether for any given
2659 relationship the function needs to be passed.
2660 The function returns a True or False value.
2661 </para>
2662 </section>
2663 </section>
2664
2665 <section id='images-dev-environment'>
2666 <title>Images</title>
2667
2668 <para>
2669 The images produced by the OpenEmbedded build system
2670 are compressed forms of the
2671 root filesystem that are ready to boot on a target device.
2672 You can see from the
2673 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
2674 that BitBake output, in part, consists of images.
2675 This section is going to look more closely at this output:
2676 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
2677 </para>
2678
2679 <para>
2680 For a list of example images that the Yocto Project provides,
2681 see the
2682 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
2683 chapter in the Yocto Project Reference Manual.
2684 </para>
2685
2686 <para>
2687 Images are written out to the
2688 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2689 inside the
2690 <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
2691 folder as shown in the figure.
2692 This folder contains any files expected to be loaded on the
2693 target device.
2694 The
2695 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>
2696 variable points to the <filename>deploy</filename> directory,
2697 while the
2698 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
2699 variable points to the appropriate directory containing images for
2700 the current configuration.
2701 <itemizedlist>
2702 <listitem><para><filename><replaceable>kernel-image</replaceable></filename>:
2703 A kernel binary file.
2704 The
2705 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>
2706 variable setting determines the naming scheme for the
2707 kernel image file.
2708 Depending on that variable, the file could begin with
2709 a variety of naming strings.
2710 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2711 directory can contain multiple image files for the
2712 machine.</para></listitem>
2713 <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>:
2714 Root filesystems for the target device (e.g.
2715 <filename>*.ext3</filename> or <filename>*.bz2</filename>
2716 files).
2717 The
2718 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2719 variable setting determines the root filesystem image
2720 type.
2721 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2722 directory can contain multiple root filesystems for the
2723 machine.</para></listitem>
2724 <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>:
2725 Tarballs that contain all the modules built for the kernel.
2726 Kernel module tarballs exist for legacy purposes and
2727 can be suppressed by setting the
2728 <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink>
2729 variable to "0".
2730 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2731 directory can contain multiple kernel module tarballs
2732 for the machine.</para></listitem>
2733 <listitem><para><filename><replaceable>bootloaders</replaceable></filename>:
2734 Bootloaders supporting the image, if applicable to the
2735 target machine.
2736 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2737 directory can contain multiple bootloaders for the
2738 machine.</para></listitem>
2739 <listitem><para><filename><replaceable>symlinks</replaceable></filename>:
2740 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2741 folder contains
2742 a symbolic link that points to the most recently built file
2743 for each machine.
2744 These links might be useful for external scripts that
2745 need to obtain the latest version of each file.
2746 </para></listitem>
2747 </itemizedlist>
2748 </para>
2749 </section>
2750
2751 <section id='sdk-dev-environment'>
2752 <title>Application Development SDK</title>
2753
2754 <para>
2755 In the
2756 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
2757 the output labeled "Application Development SDK" represents an
2758 SDK.
2759 The SDK generation process differs depending on whether you build
2760 a standard SDK
2761 (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>)
2762 or an extensible SDK
2763 (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>).
2764 This section is going to take a closer look at this output:
2765 <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
2766 </para>
2767
2768 <para>
2769 The specific form of this output is a self-extracting
2770 SDK installer (<filename>*.sh</filename>) that, when run,
2771 installs the SDK, which consists of a cross-development
2772 toolchain, a set of libraries and headers, and an SDK
2773 environment setup script.
2774 Running this installer essentially sets up your
2775 cross-development environment.
2776 You can think of the cross-toolchain as the "host"
2777 part because it runs on the SDK machine.
2778 You can think of the libraries and headers as the "target"
2779 part because they are built for the target hardware.
2780 The environment setup script is added so that you can initialize
2781 the environment before using the tools.
2782 </para>
2783
2784 <note><title>Notes</title>
2785 <itemizedlist>
2786 <listitem><para>
2787 The Yocto Project supports several methods by which you can
2788 set up this cross-development environment.
2789 These methods include downloading pre-built SDK installers
2790 or building and installing your own SDK installer.
2791 </para></listitem>
2792 <listitem><para>
2793 For background information on cross-development toolchains
2794 in the Yocto Project development environment, see the
2795 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
2796 section.
2797 </para></listitem>
2798 <listitem><para>
2799 For information on setting up a cross-development
2800 environment, see the
2801 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
2802 manual.
2803 </para></listitem>
2804 </itemizedlist>
2805 </note>
2806
2807 <para>
2808 Once built, the SDK installers are written out to the
2809 <filename>deploy/sdk</filename> folder inside the
2810 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2811 as shown in the figure at the beginning of this section.
2812 Depending on the type of SDK, several variables exist that help
2813 configure these files.
2814 The following list shows the variables associated with a standard
2815 SDK:
2816 <itemizedlist>
2817 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2818 Points to the <filename>deploy</filename>
2819 directory.</para></listitem>
2820 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>:
2821 Specifies the architecture of the machine
2822 on which the cross-development tools are run to
2823 create packages for the target hardware.
2824 </para></listitem>
2825 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>:
2826 Lists the features to include in the "target" part
2827 of the SDK.
2828 </para></listitem>
2829 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>:
2830 Lists packages that make up the host
2831 part of the SDK (i.e. the part that runs on
2832 the <filename>SDKMACHINE</filename>).
2833 When you use
2834 <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
2835 to create the SDK, a set of default packages
2836 apply.
2837 This variable allows you to add more packages.
2838 </para></listitem>
2839 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>:
2840 Lists packages that make up the target part
2841 of the SDK (i.e. the part built for the
2842 target hardware).
2843 </para></listitem>
2844 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>:
2845 Defines the default SDK installation path offered by the
2846 installation script.
2847 </para></listitem>
2848 </itemizedlist>
2849 This next list, shows the variables associated with an extensible
2850 SDK:
2851 <itemizedlist>
2852 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2853 Points to the <filename>deploy</filename> directory.
2854 </para></listitem>
2855 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>:
2856 Controls whether or not shared state artifacts are copied
2857 into the extensible SDK.
2858 By default, all required shared state artifacts are copied
2859 into the SDK.
2860 </para></listitem>
2861 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>:
2862 Specifies whether or not packagedata will be included in
2863 the extensible SDK for all recipes in the "world" target.
2864 </para></listitem>
2865 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>:
2866 Specifies whether or not the toolchain will be included
2867 when building the extensible SDK.
2868 </para></listitem>
2869 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>:
2870 A list of variables allowed through from the build system
2871 configuration into the extensible SDK configuration.
2872 </para></listitem>
2873 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>:
2874 A list of variables not allowed through from the build
2875 system configuration into the extensible SDK configuration.
2876 </para></listitem>
2877 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>:
2878 A list of classes to remove from the
2879 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
2880 value globally within the extensible SDK configuration.
2881 </para></listitem>
2882 </itemizedlist>
2883 </para>
2884 </section>
2885</section>
2886
2887</chapter>
2888<!--
2889vim: expandtab tw=80 ts=4
2890-->
diff --git a/documentation/overview-manual/overview-manual-customization.xsl b/documentation/overview-manual/overview-manual-customization.xsl
deleted file mode 100644
index ccb7521259..0000000000
--- a/documentation/overview-manual/overview-manual-customization.xsl
+++ /dev/null
@@ -1,27 +0,0 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
5
6<!--
7
8 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
9
10 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
11
12-->
13
14 <xsl:include href="../template/permalinks.xsl"/>
15 <xsl:include href="../template/section.title.xsl"/>
16 <xsl:include href="../template/component.title.xsl"/>
17 <xsl:include href="../template/division.title.xsl"/>
18 <xsl:include href="../template/formal.object.heading.xsl"/>
19
20 <xsl:param name="html.stylesheet" select="'overview-style.css'" />
21 <xsl:param name="chapter.autolabel" select="1" />
22 <xsl:param name="appendix.autolabel" select="A" />
23 <xsl:param name="section.autolabel" select="1" />
24 <xsl:param name="section.label.includes.component.label" select="1" />
25 <xsl:param name="generate.id.attributes" select="1" />
26
27</xsl:stylesheet>
diff --git a/documentation/overview-manual/overview-manual-eclipse-customization.xsl b/documentation/overview-manual/overview-manual-eclipse-customization.xsl
deleted file mode 100644
index aaf99ea1ba..0000000000
--- a/documentation/overview-manual/overview-manual-eclipse-customization.xsl
+++ /dev/null
@@ -1,35 +0,0 @@
1<?xml version='1.0'?>
2<xsl:stylesheet
3 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4 xmlns="http://www.w3.org/1999/xhtml"
5 xmlns:fo="http://www.w3.org/1999/XSL/Format"
6 version="1.0">
7
8 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
9
10<!--
11
12 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
13
14 <xsl:import
15 href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" />
16
17-->
18
19 <xsl:param name="chunker.output.indent" select="'yes'"/>
20 <xsl:param name="chunk.quietly" select="1"/>
21 <xsl:param name="chunk.first.sections" select="1"/>
22 <xsl:param name="chunk.section.depth" select="10"/>
23 <xsl:param name="use.id.as.filename" select="1"/>
24 <xsl:param name="ulink.target" select="'_self'" />
25 <xsl:param name="base.dir" select="'html/overview-manual/'"/>
26 <xsl:param name="html.stylesheet" select="'../book.css'"/>
27 <xsl:param name="eclipse.manifest" select="0"/>
28 <xsl:param name="create.plugin.xml" select="0"/>
29 <xsl:param name="suppress.navigation" select="1"/>
30 <xsl:param name="generate.index" select="0"/>
31 <xsl:param name="chapter.autolabel" select="1" />
32 <xsl:param name="appendix.autolabel" select="1" />
33 <xsl:param name="section.autolabel" select="1" />
34 <xsl:param name="section.label.includes.component.label" select="1" />
35</xsl:stylesheet>
diff --git a/documentation/overview-manual/overview-manual-intro.xml b/documentation/overview-manual/overview-manual-intro.xml
deleted file mode 100644
index 51a21b6e23..0000000000
--- a/documentation/overview-manual/overview-manual-intro.xml
+++ /dev/null
@@ -1,103 +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='overview-manual-intro'>
6
7<title>The Yocto Project Overview Manual</title>
8 <section id='overview-welcome'>
9 <title>Welcome</title>
10
11 <para>
12 Welcome to the Yocto Project Overview Manual!
13 This manual introduces the Yocto Project by providing concepts,
14 software overviews, best-known-methods (BKMs), and any other
15 high-level introductory information suitable for a new Yocto
16 Project user.
17 </para>
18
19 <para>
20 The following list describes what you can get from this manual:
21 <itemizedlist>
22 <listitem><para>
23 <emphasis>Major Topic:</emphasis>
24 Provide a high-level description of this major topic.
25 </para></listitem>
26 <listitem><para>
27 <emphasis>Major Topic:</emphasis>
28 Provide a high-level description of this major topic.
29 </para></listitem>
30 <listitem><para>
31 <emphasis>Major Topic:</emphasis>
32 Provide a high-level description of this major topic.
33 </para></listitem>
34 <listitem><para>
35 <emphasis>Major Topic:</emphasis>
36 Provide a high-level description of this major topic.
37 </para></listitem>
38 </itemizedlist>
39 </para>
40
41 <para>
42 This manual does not give you the following:
43 <itemizedlist>
44 <listitem><para>
45 <emphasis>Step-by-step Instructions for Development Tasks:</emphasis>
46 Instructional procedures reside in other manuals within
47 the Yocto Project documentation set.
48 For example, the
49 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>
50 provides examples on how to perform various development
51 tasks.
52 As another example, the
53 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
54 manual contains detailed instructions on how to install an
55 SDK, which is used to develop applications for target
56 hardware.
57 </para></listitem>
58 <listitem><para>
59 <emphasis>Reference Material:</emphasis>
60 This type of material resides in an appropriate reference
61 manual.
62 For example, system variables are documented in the
63 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
64 As another example, the
65 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
66 contains reference information on BSPs.
67 </para></listitem>
68 <listitem><para>
69 <emphasis>Detailed Public Information Not Specific to the
70 Yocto Project:</emphasis>
71 For example, exhaustive information on how to use the
72 Source Control Manager Git is better covered with Internet
73 searches and official Git Documentation than through the
74 Yocto Project documentation.
75 </para></listitem>
76 </itemizedlist>
77 </para>
78 </section>
79
80 <section id='overview-other-information'>
81 <title>Other Information</title>
82
83 <para>
84 Because this manual presents information for many different
85 topics, supplemental information is recommended for full
86 comprehension.
87 For additional introductory information on the Yocto Project, see
88 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
89 You can find an introductory to using the Yocto Project by working
90 through the
91 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
92 </para>
93
94 <para>
95 For a comprehensive list of links and other documentation, see the
96 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
97 section in the Yocto Project Reference Manual.
98 </para>
99 </section>
100</chapter>
101<!--
102vim: expandtab tw=80 ts=4
103-->
diff --git a/documentation/overview-manual/overview-manual.xml b/documentation/overview-manual/overview-manual.xml
deleted file mode 100644
index fe021073da..0000000000
--- a/documentation/overview-manual/overview-manual.xml
+++ /dev/null
@@ -1,94 +0,0 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='overview-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/overview-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Overview Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <firstname>Scott</firstname> <surname>Rifenbark</surname>
26 <affiliation>
27 <orgname>Scotty's Documentation Services, INC</orgname>
28 </affiliation>
29 <email>srifenbark@gmail.com</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>2.5</revnumber>
36 <date>April 2018</date>
37 <revremark>The initial document released with the Yocto Project 2.5 Release.</revremark>
38 </revision>
39 </revhistory>
40
41 <copyright>
42 <year>&COPYRIGHT_YEAR;</year>
43 <holder>Linux Foundation</holder>
44 </copyright>
45
46 <legalnotice>
47 <para>
48 Permission is granted to copy, distribute and/or modify this document under
49 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
50 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
51 Creative Commons.
52 </para>
53 <note><title>Manual Notes</title>
54 <itemizedlist>
55 <listitem><para>
56 This version of the
57 <emphasis>Yocto Project Overview Manual</emphasis>
58 is for the &YOCTO_DOC_VERSION; release of the
59 Yocto Project.
60 To be sure you have the latest version of the manual
61 for this release, use the manual from the
62 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
63 </para></listitem>
64 <listitem><para>
65 For manuals associated with other releases of the Yocto
66 Project, go to the
67 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
68 and use the drop-down "Active Releases" button
69 and choose the manual associated with the desired
70 Yocto Project.
71 </para></listitem>
72 <listitem><para>
73 To report any inaccuracies or problems with this
74 manual, send an email to the Yocto Project
75 discussion group at
76 <filename>yocto@yoctoproject.com</filename> or log into
77 the freenode <filename>#yocto</filename> channel.
78 </para></listitem>
79 </itemizedlist>
80 </note>
81 </legalnotice>
82
83 </bookinfo>
84
85 <xi:include href="overview-manual-intro.xml"/>
86
87 <xi:include href="overview-development-environment.xml"/>
88
89 <xi:include href="overview-concepts.xml"/>
90
91</book>
92<!--
93vim: expandtab tw=80 ts=4
94-->
diff --git a/documentation/overview-manual/overview-style.css b/documentation/overview-manual/overview-style.css
deleted file mode 100644
index 9d7bf9e0d6..0000000000
--- a/documentation/overview-manual/overview-style.css
+++ /dev/null
@@ -1,988 +0,0 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/overview-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316/* This style defines how the permalink character
317 appears by itself and when hovered over with
318 the mouse. */
319
320[alt='Permalink'] { color: #eee; }
321[alt='Permalink']:hover { color: black; }
322
323
324div.informalfigure,
325div.informalexample,
326div.informaltable,
327div.figure,
328div.table,
329div.example {
330 margin: 1em 0em;
331 padding: 1em;
332 page-break-inside: avoid;
333}
334
335
336div.informalfigure p.title b,
337div.informalexample p.title b,
338div.informaltable p.title b,
339div.figure p.title b,
340div.example p.title b,
341div.table p.title b{
342 padding-top: 0em;
343 margin-top: 0em;
344 font-size: 100%;
345 font-weight: normal;
346}
347
348.mediaobject .caption,
349.mediaobject .caption p {
350 text-align: center;
351 font-size: 80%;
352 padding-top: 0.5em;
353 padding-bottom: 0.5em;
354}
355
356.epigraph {
357 padding-left: 55%;
358 margin-bottom: 1em;
359}
360
361.epigraph p {
362 text-align: left;
363}
364
365.epigraph .quote {
366 font-style: italic;
367}
368.epigraph .attribution {
369 font-style: normal;
370 text-align: right;
371}
372
373span.application {
374 font-style: italic;
375}
376
377.programlisting {
378 font-family: monospace;
379 font-size: 80%;
380 white-space: pre;
381 margin: 1.33em 0em;
382 padding: 1.33em;
383}
384
385.tip,
386.warning,
387.caution,
388.note {
389 margin-top: 1em;
390 margin-bottom: 1em;
391
392}
393
394/* force full width of table within div */
395.tip table,
396.warning table,
397.caution table,
398.note table {
399 border: none;
400 width: 100%;
401}
402
403
404.tip table th,
405.warning table th,
406.caution table th,
407.note table th {
408 padding: 0.8em 0.0em 0.0em 0.0em;
409 margin : 0em 0em 0em 0em;
410}
411
412.tip p,
413.warning p,
414.caution p,
415.note p {
416 margin-top: 0.5em;
417 margin-bottom: 0.5em;
418 padding-right: 1em;
419 text-align: left;
420}
421
422.acronym {
423 text-transform: uppercase;
424}
425
426b.keycap,
427.keycap {
428 padding: 0.09em 0.3em;
429 margin: 0em;
430}
431
432.itemizedlist li {
433 clear: none;
434}
435
436.filename {
437 font-size: medium;
438 font-family: Courier, monospace;
439}
440
441
442div.navheader, div.heading{
443 position: absolute;
444 left: 0em;
445 top: 0em;
446 width: 100%;
447 background-color: #cdf;
448 width: 100%;
449}
450
451div.navfooter, div.footing{
452 position: fixed;
453 left: 0em;
454 bottom: 0em;
455 background-color: #eee;
456 width: 100%;
457}
458
459
460div.navheader td,
461div.navfooter td {
462 font-size: 66%;
463}
464
465div.navheader table th {
466 /*font-family: Georgia, Times, serif;*/
467 /*font-size: x-large;*/
468 font-size: 80%;
469}
470
471div.navheader table {
472 border-left: 0em;
473 border-right: 0em;
474 border-top: 0em;
475 width: 100%;
476}
477
478div.navfooter table {
479 border-left: 0em;
480 border-right: 0em;
481 border-bottom: 0em;
482 width: 100%;
483}
484
485div.navheader table td a,
486div.navfooter table td a {
487 color: #777;
488 text-decoration: none;
489}
490
491/* normal text in the footer */
492div.navfooter table td {
493 color: black;
494}
495
496div.navheader table td a:visited,
497div.navfooter table td a:visited {
498 color: #444;
499}
500
501
502/* links in header and footer */
503div.navheader table td a:hover,
504div.navfooter table td a:hover {
505 text-decoration: underline;
506 background-color: transparent;
507 color: #33a;
508}
509
510div.navheader hr,
511div.navfooter hr {
512 display: none;
513}
514
515
516.qandaset tr.question td p {
517 margin: 0em 0em 1em 0em;
518 padding: 0em 0em 0em 0em;
519}
520
521.qandaset tr.answer td p {
522 margin: 0em 0em 1em 0em;
523 padding: 0em 0em 0em 0em;
524}
525.answer td {
526 padding-bottom: 1.5em;
527}
528
529.emphasis {
530 font-weight: bold;
531}
532
533
534 /************* /
535 / decorations /
536/ *************/
537
538.titlepage {
539}
540
541.part .title {
542}
543
544.subtitle {
545 border: none;
546}
547
548/*
549h1 {
550 border: none;
551}
552
553h2 {
554 border-top: solid 0.2em;
555 border-bottom: solid 0.06em;
556}
557
558h3 {
559 border-top: 0em;
560 border-bottom: solid 0.06em;
561}
562
563h4 {
564 border: 0em;
565 border-bottom: solid 0.06em;
566}
567
568h5 {
569 border: 0em;
570}
571*/
572
573.programlisting {
574 border: solid 1px;
575}
576
577div.figure,
578div.table,
579div.informalfigure,
580div.informaltable,
581div.informalexample,
582div.example {
583 border: 1px solid;
584}
585
586
587
588.tip,
589.warning,
590.caution,
591.note {
592 border: 1px solid;
593}
594
595.tip table th,
596.warning table th,
597.caution table th,
598.note table th {
599 border-bottom: 1px solid;
600}
601
602.question td {
603 border-top: 1px solid black;
604}
605
606.answer {
607}
608
609
610b.keycap,
611.keycap {
612 border: 1px solid;
613}
614
615
616div.navheader, div.heading{
617 border-bottom: 1px solid;
618}
619
620
621div.navfooter, div.footing{
622 border-top: 1px solid;
623}
624
625 /********* /
626 / colors /
627/ *********/
628
629body {
630 color: #333;
631 background: white;
632}
633
634a {
635 background: transparent;
636}
637
638a:hover {
639 background-color: #dedede;
640}
641
642
643h1,
644h2,
645h3,
646h4,
647h5,
648h6,
649h7,
650h8 {
651 background-color: transparent;
652}
653
654hr {
655 border-color: #aaa;
656}
657
658
659.tip, .warning, .caution, .note {
660 border-color: #fff;
661}
662
663
664.tip table th,
665.warning table th,
666.caution table th,
667.note table th {
668 border-bottom-color: #fff;
669}
670
671
672.warning {
673 background-color: #f0f0f2;
674}
675
676.caution {
677 background-color: #f0f0f2;
678}
679
680.tip {
681 background-color: #f0f0f2;
682}
683
684.note {
685 background-color: #f0f0f2;
686}
687
688.glossary dl dt,
689.variablelist dl dt,
690.variablelist dl dt span.term {
691 color: #044;
692}
693
694div.figure,
695div.table,
696div.example,
697div.informalfigure,
698div.informaltable,
699div.informalexample {
700 border-color: #aaa;
701}
702
703pre.programlisting {
704 color: black;
705 background-color: #fff;
706 border-color: #aaa;
707 border-width: 2px;
708}
709
710.guimenu,
711.guilabel,
712.guimenuitem {
713 background-color: #eee;
714}
715
716
717b.keycap,
718.keycap {
719 background-color: #eee;
720 border-color: #999;
721}
722
723
724div.navheader {
725 border-color: black;
726}
727
728
729div.navfooter {
730 border-color: black;
731}
732
733.writernotes {
734 color: red;
735}
736
737
738 /*********** /
739 / graphics /
740/ ***********/
741
742/*
743body {
744 background-image: url("images/body_bg.jpg");
745 background-attachment: fixed;
746}
747
748.navheader,
749.note,
750.tip {
751 background-image: url("images/note_bg.jpg");
752 background-attachment: fixed;
753}
754
755.warning,
756.caution {
757 background-image: url("images/warning_bg.jpg");
758 background-attachment: fixed;
759}
760
761.figure,
762.informalfigure,
763.example,
764.informalexample,
765.table,
766.informaltable {
767 background-image: url("images/figure_bg.jpg");
768 background-attachment: fixed;
769}
770
771*/
772h1,
773h2,
774h3,
775h4,
776h5,
777h6,
778h7{
779}
780
781/*
782Example of how to stick an image as part of the title.
783
784div.article .titlepage .title
785{
786 background-image: url("figures/white-on-black.png");
787 background-position: center;
788 background-repeat: repeat-x;
789}
790*/
791
792div.preface .titlepage .title,
793div.colophon .title,
794div.chapter .titlepage .title,
795div.article .titlepage .title
796{
797}
798
799div.section div.section .titlepage .title,
800div.sect2 .titlepage .title {
801 background: none;
802}
803
804
805h1.title {
806 background-color: transparent;
807 background-repeat: no-repeat;
808 height: 256px;
809 text-indent: -9000px;
810 overflow:hidden;
811}
812
813h2.subtitle {
814 background-color: transparent;
815 text-indent: -9000px;
816 overflow:hidden;
817 width: 0px;
818 display: none;
819}
820
821 /*************************************** /
822 / pippin.gimp.org specific alterations /
823/ ***************************************/
824
825/*
826div.heading, div.navheader {
827 color: #777;
828 font-size: 80%;
829 padding: 0;
830 margin: 0;
831 text-align: left;
832 position: absolute;
833 top: 0px;
834 left: 0px;
835 width: 100%;
836 height: 50px;
837 background: url('/gfx/heading_bg.png') transparent;
838 background-repeat: repeat-x;
839 background-attachment: fixed;
840 border: none;
841}
842
843div.heading a {
844 color: #444;
845}
846
847div.footing, div.navfooter {
848 border: none;
849 color: #ddd;
850 font-size: 80%;
851 text-align:right;
852
853 width: 100%;
854 padding-top: 10px;
855 position: absolute;
856 bottom: 0px;
857 left: 0px;
858
859 background: url('/gfx/footing_bg.png') transparent;
860}
861*/
862
863
864
865 /****************** /
866 / nasty ie tweaks /
867/ ******************/
868
869/*
870div.heading, div.navheader {
871 width:expression(document.body.clientWidth + "px");
872}
873
874div.footing, div.navfooter {
875 width:expression(document.body.clientWidth + "px");
876 margin-left:expression("-5em");
877}
878body {
879 padding:expression("4em 5em 0em 5em");
880}
881*/
882
883 /**************************************** /
884 / mozilla vendor specific css extensions /
885/ ****************************************/
886/*
887div.navfooter, div.footing{
888 -moz-opacity: 0.8em;
889}
890
891div.figure,
892div.table,
893div.informalfigure,
894div.informaltable,
895div.informalexample,
896div.example,
897.tip,
898.warning,
899.caution,
900.note {
901 -moz-border-radius: 0.5em;
902}
903
904b.keycap,
905.keycap {
906 -moz-border-radius: 0.3em;
907}
908*/
909
910table tr td table tr td {
911 display: none;
912}
913
914
915hr {
916 display: none;
917}
918
919table {
920 border: 0em;
921}
922
923 .photo {
924 float: right;
925 margin-left: 1.5em;
926 margin-bottom: 1.5em;
927 margin-top: 0em;
928 max-width: 17em;
929 border: 1px solid gray;
930 padding: 3px;
931 background: white;
932}
933 .seperator {
934 padding-top: 2em;
935 clear: both;
936 }
937
938 #validators {
939 margin-top: 5em;
940 text-align: right;
941 color: #777;
942 }
943 @media print {
944 body {
945 font-size: 8pt;
946 }
947 .noprint {
948 display: none;
949 }
950 }
951
952
953.tip,
954.note {
955 background: #f0f0f2;
956 color: #333;
957 padding: 20px;
958 margin: 20px;
959}
960
961.tip h3,
962.note h3 {
963 padding: 0em;
964 margin: 0em;
965 font-size: 2em;
966 font-weight: bold;
967 color: #333;
968}
969
970.tip a,
971.note a {
972 color: #333;
973 text-decoration: underline;
974}
975
976.footnote {
977 font-size: small;
978 color: #333;
979}
980
981/* Changes the announcement text */
982.tip h3,
983.warning h3,
984.caution h3,
985.note h3 {
986 font-size:large;
987 color: #00557D;
988}
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-21 17:51:43 +0000