summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-25 17:56:24 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-09 18:59:04 -0700
commitc5095104aaf28e11b508faa59ca71d233123a6d8 (patch)
treef8c462983ad7df9e535cb222f3b79a6bdf4ca6b5 /bitbake/doc/user-manual
parent4cd882b9d05f503ee58f78cceebaa9e63dc2048f (diff)
downloadpoky-c5095104aaf28e11b508faa59ca71d233123a6d8.tar.gz
bitbake: user-manual: Review edits from Richard (second draft)
Applied the comprehensive set of review comments from Richard Purdie. All files affected. One major point here was that the "BitBake Command" chapter was eliminated. This information was folded into various areas of the book. Consequently, the bits including the file for make had to be updated. (Bitbake rev: 8ec38c6b456a92a0e0b9b04c2793a5b148be5027) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/user-manual')
-rw-r--r--bitbake/doc/user-manual/user-manual-bitbakecommand.xml341
-rw-r--r--bitbake/doc/user-manual/user-manual-execution.xml329
-rw-r--r--bitbake/doc/user-manual/user-manual-fetching.xml2
-rw-r--r--bitbake/doc/user-manual/user-manual-intro.xml250
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml63
-rw-r--r--bitbake/doc/user-manual/user-manual-ref-variables.xml9
-rw-r--r--bitbake/doc/user-manual/user-manual.xml2
7 files changed, 579 insertions, 417 deletions
diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
deleted file mode 100644
index 5c301a56f3..0000000000
--- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
+++ /dev/null
@@ -1,341 +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
4<chapter id="user-manual-command">
5 <title>The BitBake Command</title>
6
7 <para>
8 BitBake is the underlying piece of the build system.
9 Two excellent examples are the Yocto Project and the OpenEmbedded
10 build systems.
11 Each provide an environment in which to develop embedded Linux
12 images, and each use BitBake as their underlying build engine.
13 </para>
14
15 <para>
16 BitBake facilitates executing tasks in a single <filename>.bb</filename>
17 file, or executing a given task on a set of multiple
18 <filename>.bb</filename> files, accounting for interdependencies
19 amongst them.
20 This chapter presents the BitBake syntax, provides some execution
21 examples, and shows you how to control BitBake with key metadata.
22 </para>
23
24 <section id='usage-and-syntax'>
25 <title>Usage and syntax</title>
26
27 <para>
28 Following is the usage and syntax for BitBake:
29 <literallayout class='monospaced'>
30 $ bitbake -h
31Usage: bitbake [options] [recipename/target ...]
32
33 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
34 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
35 will provide the layer, BBFILES and other configuration information.
36
37Options:
38 --version show program's version number and exit
39 -h, --help show this help message and exit
40 -b BUILDFILE, --buildfile=BUILDFILE
41 Execute tasks from a specific .bb recipe directly.
42 WARNING: Does not handle any dependencies from other
43 recipes.
44 -k, --continue Continue as much as possible after an error. While the
45 target that failed and anything depending on it cannot
46 be built, as much as possible will be built before
47 stopping.
48 -a, --tryaltconfigs Continue with builds by trying to use alternative
49 providers where possible.
50 -f, --force Force the specified targets/task to run (invalidating
51 any existing stamp file).
52 -c CMD, --cmd=CMD Specify the task to execute. The exact options
53 available depend on the metadata. Some examples might
54 be 'compile' or 'populate_sysroot' or 'listtasks' may
55 give a list of the tasks available.
56 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
57 Invalidate the stamp for the specified task such as
58 'compile' and then run the default task for the
59 specified target(s).
60 -r PREFILE, --read=PREFILE
61 Read the specified file before bitbake.conf.
62 -R POSTFILE, --postread=POSTFILE
63 Read the specified file after bitbake.conf.
64 -v, --verbose Output more log message data to the terminal.
65 -D, --debug Increase the debug level. You can specify this more
66 than once.
67 -n, --dry-run Don't execute, just go through the motions.
68 -S, --dump-signatures
69 Don't execute, just dump out the signature
70 construction information.
71 -p, --parse-only Quit after parsing the BB recipes.
72 -s, --show-versions Show current and preferred versions of all recipes.
73 -e, --environment Show the global or per-package environment complete
74 with information about where variables were
75 set/changed.
76 -g, --graphviz Save dependency tree information for the specified
77 targets in the dot syntax.
78 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
79 Assume these dependencies don't exist and are already
80 provided (equivalent to ASSUME_PROVIDED). Useful to
81 make dependency graphs more appealing
82 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
83 Show debug logging for the specified logging domains
84 -P, --profile Profile the command and save reports.
85 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
86 -t SERVERTYPE, --servertype=SERVERTYPE
87 Choose which server to use, process or xmlrpc.
88 --revisions-changed Set the exit code depending on whether upstream
89 floating revisions have changed or not.
90 --server-only Run bitbake without a UI, only starting a server
91 (cooker) process.
92 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
93 --no-setscene Do not run any setscene tasks. sstate will be ignored
94 and everything needed, built.
95 --remote-server=REMOTE_SERVER
96 Connect to the specified server.
97 -m, --kill-server Terminate the remote server.
98 --observe-only Connect to a server as an observing-only client.
99 --status-only Check the status of the remote bitbake server.
100
101 </literallayout>
102 </para>
103 </section>
104
105 <section id='bitbake-examples'>
106 <title>Examples</title>
107
108 <para>
109 This section presents some examples showing how to use BitBake.
110 </para>
111
112 <section id='example-executing-a-task-against-a-single-recipe'>
113 <title>Executing a Task Against a Single Recipe</title>
114
115 <para>
116 Executing tasks for a single recipe file is relatively simple.
117 You specify the file in question, and BitBake parses
118 it and executes the specified task.
119 If you do not specify a task, BitBake executes the default
120 task, which is "build”.
121 BitBake obeys inter-task dependencies when doing
122 so.
123 </para>
124
125 <para>
126 The following command runs the clean task on the
127 <filename>foo_1.0.bb</filename> recipe file:
128 <literallayout class='monospaced'>
129 $ bitbake -b foo.bb -c clean
130 </literallayout>
131 The following command runs the build task, which is
132 the default task, on the <filename>foo_1.0.bb</filename>
133 recipe file:
134 <literallayout class='monospaced'>
135 $ bitbake -b foo_1.0.bb
136 </literallayout>
137 </para>
138 </section>
139
140 <section id='executing-tasks-against-a-set-of-recipe-files'>
141 <title>Executing Tasks Against a Set of Recipe Files</title>
142
143 <para>
144 There are a number of additional complexities introduced
145 when one wants to manage multiple <filename>.bb</filename>
146 files.
147 Clearly there needs to be a way to tell BitBake what
148 files are available, and of those, which you
149 want to execute.
150 There also needs to be a way for each recipe
151 to express its dependencies, both for build-time and
152 runtime.
153 There must be a way for you to express recipe preferences
154 when multiple recipes provide the same functionality, or when
155 there are multiple versions of a recipe.
156 </para>
157
158 <para>
159 The <filename>bitbake</filename> command, when not using
160 "--buildfile" or "-b" only accepts a "PROVIDER".
161 You cannot provide anything else.
162 By default, a recipe file generally "PROVIDES" its
163 "packagename", "packagename-version", and
164 "packagename-version-revision" as shown in the following
165 example:
166 <literallayout class='monospaced'>
167 $ bitbake foo
168
169 $ bitbake foo-1.0
170
171 $ bitbake foo-1.0-r0
172 </literallayout>
173 This next example "PROVIDES" the package name and also uses
174 the "-c" option to tell BitBake to just excute the
175 <filename>do_clean</filename> task:
176 <literallayout class='monospaced'>
177 $ bitbake -c clean foo
178 </literallayout>
179 </para>
180 </section>
181
182 <section id='generating-dependency-graphs'>
183 <title>Generating Dependency Graphs</title>
184
185 <para>
186 BitBake is able to generate dependency graphs using
187 the dot syntax.
188 You can convert these graphs into images using the dot
189 application from
190 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
191 </para>
192
193 <para>
194 When you generate a dependency graph, BitBake writes two files
195 to the current working directory:
196 <filename>depends.dot</filename>, which contains dependency information
197 at the package level, and <filename>task-depends.dot</filename>,
198 which contains a breakdown of the dependencies at the task level.
199 </para>
200
201 <para>
202 To stop depending on common depends, use use the "-I" depend
203 option and BitBake omits them from the graph.
204 Leaving this information out can produce more readable graphs.
205 This way, you can remove from the graph
206 <filename>DEPENDS</filename> from inherited classes
207 such as <filename>base.bbclass</filename>.
208 </para>
209
210 <para>
211 Here are two exmples that create dependency graphs.
212 The second example omits common depends from the graph:
213 <literallayout class='monospaced'>
214 $ bitbake -g foo
215
216 $ bitbake -g -I virtual/whatever -I bloom foo
217 </literallayout>
218 </para>
219 </section>
220 </section>
221
222 <section id='controlling-bitbake'>
223 <title>Controlling BitBake</title>
224
225 <para>
226 Including variables in your recipe and class files help control
227 how BitBake operates.
228 </para>
229
230 <section id='execution-threads'>
231 <title>Execution Threads</title>
232
233 <para>
234 You can control how many thread BitBake supports by using the
235 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
236 variable.
237 You would set this in your <filename>local.conf</filename>
238 configuration file.
239 </para>
240 </section>
241
242 <section id='using-provides'>
243 <title>Using <filename>PROVIDES</filename></title>
244
245 <para>
246 This example shows the usage of the
247 <filename>PROVIDES</filename> variable, which allows a
248 given <filename>.bb</filename> to specify what
249 functionality it provides.
250 <literallayout class='monospaced'>
251 package1.bb:
252
253 PROVIDES += "virtual/package"
254
255 package2.bb:
256
257 DEPENDS += "virtual/package"
258
259 package3.bb:
260
261 PROVIDES += "virtual/package"
262 </literallayout>
263 As you can see, we have two different
264 recipes that provide the same functionality
265 (virtual/package).
266 Clearly, there needs to be a way for the person running
267 BitBake to control which of those providers
268 gets used.
269 There is, indeed, such a way.
270 </para>
271
272 <para>
273 The following would go into a <filename>.conf</filename>
274 file, to select package1:
275 <literallayout class='monospaced'>
276 PREFERRED_PROVIDER_virtual/package = "package1"
277 </literallayout>
278 </para>
279 </section>
280
281 <section id='specifying-version-preference'>
282 <title>Specifying Version Preference</title>
283
284 <para>
285 When there are multiple “versions” of a given package,
286 BitBake defaults to selecting the most recent
287 version, unless otherwise specified.
288 If the <filename>.bb</filename> in question has a
289 <filename>DEFAULT_PREFERENCE</filename> set lower than
290 the other recipes (default is 0), then it will not be
291 selected.
292 This allows the person or persons maintaining
293 the repository of <filename>.bb</filename> files to specify
294 their preference for the default selected version.
295 In addition, the user can specify their preferred version.
296 </para>
297
298 <para>
299 If the first <filename>.bb</filename> is named
300 <filename>a_1.1.bb</filename>, then the
301 <filename>PN</filename> variable will be set to
302 “a”, and the <filename>PV</filename> variable will be
303 set to 1.1.
304 </para>
305
306 <para>
307 If we then have an <filename>a_1.2.bb</filename>, BitBake
308 will choose 1.2 by default.
309 However, if we define the following variable in a
310 <filename>.conf</filename> file that BitBake parses, we
311 can change that.
312 <literallayout class='monospaced'>
313 PREFERRED_VERSION_a = "1.1"
314 </literallayout>
315 </para>
316 </section>
317
318 <section id='using-recipe-file-collections'>
319 <title>Using Recipe File Collections</title>
320
321 <para>
322 Recipe file collections exist to allow the user to
323 have multiple repositories of
324 <filename>.bb</filename> files that contain the same
325 exact package.
326 For example, one could easily use them to make one's
327 own local copy of an upstream repository, but with
328 custom modifications that one does not want upstream.
329 Here is an example:
330 <literallayout class='monospaced'>
331 BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
332 BBFILE_COLLECTIONS = "upstream local"
333 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
334 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
335 BBFILE_PRIORITY_upstream = "5"
336 BBFILE_PRIORITY_local = "10"
337 </literallayout>
338 </para>
339 </section>
340 </section>
341</chapter>
diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml
index e9f19be6de..148ac3e38a 100644
--- a/bitbake/doc/user-manual/user-manual-execution.xml
+++ b/bitbake/doc/user-manual/user-manual-execution.xml
@@ -23,11 +23,19 @@
23 $ bitbake &lt;target&gt; 23 $ bitbake &lt;target&gt;
24 </literallayout> 24 </literallayout>
25 For information on the BitBake command and its options, 25 For information on the BitBake command and its options,
26 see the 26 see
27 "<link linkend='user-manual-command'>BitBake Command</link> 27 "<link linkend='user-manual-command'>The BitBake Command</link>"
28 chapter. 28 section.
29 </para> 29 </para>
30 30
31 <note>
32 Prior to executing BitBake, you should take advantage of parallel
33 thread execution by setting the
34 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
35 variable in your <filename>local.conf</filename>
36 configuration file.
37 </note>
38
31 <section id='parsing-the-base-configuration-metadata'> 39 <section id='parsing-the-base-configuration-metadata'>
32 <title>Parsing the Base Configuration Metadata</title> 40 <title>Parsing the Base Configuration Metadata</title>
33 41
@@ -103,10 +111,13 @@
103 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem> 111 <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
104 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem> 112 <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
105 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem> 113 <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
106 <listitem><para><link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link></para></listitem> 114 <listitem><para>
107 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem> 115 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
108 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem> 116 </para></listitem>
109 </itemizedlist> 117 </itemizedlist>
118 You can find information on how to pass environment variables into the BitBake
119 execution environment in the
120 "<link linkend='passing-information-into-the-build-task-environment'>Passing Information Into the Build Task Environment</link>" section.
110 </para> 121 </para>
111 122
112 <para> 123 <para>
@@ -146,12 +157,16 @@
146 <para> 157 <para>
147 Only variable definitions and include directives are allowed 158 Only variable definitions and include directives are allowed
148 in <filename>.conf</filename> files. 159 in <filename>.conf</filename> files.
149 The following variables include: 160 Some variables directly influence BitBake's behavior.
161 These variables might have been set from the environment
162 depending on the environment variables previously
163 mentioned or set in the configuration files.
164 See the
165 "<link linkend='ref-variables-glos'>Variables Glossary</link>"
166 for a full list of variables.
167 The following list shows common variables set:
150 <itemizedlist> 168 <itemizedlist>
151 <listitem><para> 169 <listitem><para>
152 <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
153 </para></listitem>
154 <listitem><para>
155 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link> 170 <link linkend='var-BBDEBUG'><filename>BBDEBUG</filename></link>
156 </para></listitem> 171 </para></listitem>
157 <listitem><para> 172 <listitem><para>
@@ -196,6 +211,8 @@
196 <listitem><para> 211 <listitem><para>
197 <link linkend='var-BBMASK'><filename>BBMASK</filename></link> 212 <link linkend='var-BBMASK'><filename>BBMASK</filename></link>
198 </para></listitem> 213 </para></listitem>
214 <listitem><para><link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link></para></listitem>
215 <listitem><para><link linkend='var-PREFERRED_PROVIDERS'><filename>PREFERRED_PROVIDERS</filename></link></para></listitem>
199 </itemizedlist> 216 </itemizedlist>
200 </para> 217 </para>
201 218
@@ -234,8 +251,7 @@
234 <title>Locating and Parsing Recipes</title> 251 <title>Locating and Parsing Recipes</title>
235 252
236 <para> 253 <para>
237 During the configuration phase, BitBake will have 254 During the configuration phase, BitBake will have set
238 set
239 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>. 255 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>.
240 BitBake now uses it to construct a list of recipes to parse, 256 BitBake now uses it to construct a list of recipes to parse,
241 along with any append files (<filename>.bbappend</filename>) 257 along with any append files (<filename>.bbappend</filename>)
@@ -244,7 +260,7 @@
244 available files and supports wildcards. 260 available files and supports wildcards.
245 An example would be: 261 An example would be:
246 <literallayout class='monospaced'> 262 <literallayout class='monospaced'>
247 BBFILES = "/path/to/bbfiles/*.bb" 263 BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
248 </literallayout> 264 </literallayout>
249 BitBake parses each recipe and append file located 265 BitBake parses each recipe and append file located
250 with <filename>BBFILES</filename> and stores the values of 266 with <filename>BBFILES</filename> and stores the values of
@@ -279,7 +295,8 @@
279 <para> 295 <para>
280 By the time parsing is complete for a recipe, BitBake 296 By the time parsing is complete for a recipe, BitBake
281 has a list of tasks that the recipe defines and a set of 297 has a list of tasks that the recipe defines and a set of
282 data consisting of keys and values. 298 data consisting of keys and values as well as
299 dependency information about the tasks.
283 </para> 300 </para>
284 301
285 <para> 302 <para>
@@ -287,16 +304,48 @@
287 It only needs a small subset of the information to make 304 It only needs a small subset of the information to make
288 decisions about the recipe. 305 decisions about the recipe.
289 Consequently, BitBake caches the values in which it is 306 Consequently, BitBake caches the values in which it is
290 interested. 307 interested and does not store the rest of the information.
291 </para> 308 Experience has shown it's faster to re-parse the metadata than to
292 309 try and write it out to the disk and reload then it.
293 <para> 310 </para>
294 Subsequent BitBake commands then parse the base 311
295 configuration and compute a checksum of that data. 312 <para>
296 If that checksum matches what is in the cache, the 313 Where possible, subsequent BitBake commands reuse this cache of
297 recipe and class files have not changed. 314 recipe information.
298 In this case, BitBake reloads the cached information 315 The validity of this cache is determined by first computing a
299 about the recipe instead of reparsing it from scratch. 316 checksum of the base configuration data (see
317 <link linkend='var-BB_HASHCONFIG_WHITELIST'><filename>BB_HASHCONFIG_WHITELIST</filename></link>)
318 and then checking if the checksum matches.
319 If that checksum matches what is in the cache and the recipe
320 and class files have not changed, Bitbake is able to use
321 the cache.
322 BitBake then reloads the cached information about the recipe
323 instead of reparsing it from scratch.
324 </para>
325
326 <para>
327 Recipe file collections exist to allow the user to
328 have multiple repositories of
329 <filename>.bb</filename> files that contain the same
330 exact package.
331 For example, one could easily use them to make one's
332 own local copy of an upstream repository, but with
333 custom modifications that one does not want upstream.
334 Here is an example:
335 <literallayout class='monospaced'>
336 BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
337 BBFILE_COLLECTIONS = "upstream local"
338 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
339 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
340 BBFILE_PRIORITY_upstream = "5"
341 BBFILE_PRIORITY_local = "10"
342 </literallayout>
343 <note>
344 The layers mechanism is now the preferred method of collecting
345 code.
346 While the collections code remains, its main use is to set layer
347 priorities and to deal with overlap (conflicts) between layers.
348 </note>
300 </para> 349 </para>
301 </section> 350 </section>
302 351
@@ -304,38 +353,60 @@
304 <title>Preferences and Providers</title> 353 <title>Preferences and Providers</title>
305 354
306 <para> 355 <para>
307 Assuming BitBake has been instructed to execute a target and 356 Assuming BitBake has been instructed to execute a target
308 that all the recipe files have been parsed, BitBake starts to 357 and that all the recipe files have been parsed, BitBake
309 build the target and look for providers of that target. 358 starts to figure out how to build the target.
310 Once a provider is selected, BitBake resolves all the dependencies for 359 BitBake starts by looking through the
311 the target. 360 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
312 As an example, suppose the target is 361 set in recipe files.
313 <filename>core-image-sato</filename>. 362 The default <filename>PROVIDES</filename> for a recipe is its name
314 In this case, it would lead to 363 (<link linkend='var-PN'><filename>PN</filename></link>),
315 <filename>packagegroup-core-x11-sato</filename>, 364 however, a recipe can provide multiple things.
316 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
317 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
318 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
319 </para> 365 </para>
320 366
321 <para> 367 <para>
322 Sometimes a target might have multiple providers. 368 As an example of adding an extra provider, suppose a recipe named
323 A common example is "virtual/kernel", which is provided by each kernel package. 369 <filename>package1.bb</filename> contained the following:
324 Each machine often selects the best kernel provider by using a line similar to the 370 <literallayout class='monospaced'>
325 following in the machine configuration file: 371 PROVIDES += "virtual/package"
372 </literallayout>
373 The recipe now provides both "package1" and "virtual/package.
374 The "virtual/" namespace is often used to denote cases where
375 multiple providers are expected with the user choosing between
376 them.
377 Kernels and toolchain components are common cases of this in
378 OpenEmbedded.
326 </para> 379 </para>
327 380
328 <literallayout class='monospaced'>
329 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
330 </literallayout>
331
332 <para> 381 <para>
382 Sometimes a target might have multiple providers.
383 A common example is "virtual/kernel", which is provided by each
384 kernel recipe.
385 Each machine often selects the best kernel provider by using a
386 line similar to the following in the machine configuration file:
387 <literallayout class='monospaced'>
388 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
389 </literallayout>
333 The default 390 The default
334 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link> 391 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
335 is the provider with the same name as the target. 392 is the provider with the same name as the target.
336 </para> 393 </para>
337 394
338 <para> 395 <para>
396 Bitbake iterates through each target it needs to build and resolve
397 them using this process.
398 As an example, suppose the target is
399 <filename>core-image-sato</filename>.
400 In this case, it would lead to
401 <filename>packagegroup-core-x11-sato</filename>,
402 which in turn leads to recipes like
403 <filename>matchbox-terminal</filename>, <filename>pcmanfm</filename>
404 and <filename>gthumb</filename>.
405 These recipes in turn depend on <filename>eglibc</filename>
406 and the toolchain.
407 </para>
408
409 <para>
339 Understanding how providers are chosen is made complicated by the fact 410 Understanding how providers are chosen is made complicated by the fact
340 that multiple versions might exist. 411 that multiple versions might exist.
341 BitBake defaults to the highest version of a provider. 412 BitBake defaults to the highest version of a provider.
@@ -358,6 +429,41 @@
358 <para> 429 <para>
359 In summary, BitBake has created a list of providers, which is prioritized, for each target. 430 In summary, BitBake has created a list of providers, which is prioritized, for each target.
360 </para> 431 </para>
432
433 <para>
434 When there are multiple “versions” of a given package,
435 BitBake defaults to selecting the most recent
436 version, unless otherwise specified.
437 If the recipe in question has a
438 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
439 set lower than
440 the other recipes (default is 0), then it will not be
441 selected.
442 This allows the person or persons maintaining
443 the repository of recipe files to specify
444 their preference for the default selected version.
445 In addition, the user can specify their preferred version.
446 </para>
447
448 <para>
449 If the first recipe is named <filename>a_1.1.bb</filename>,
450 then the
451 <link linkend='var-PN'><filename>PN</filename></link> variable
452 will be set to “a”, and the
453 <link linkend='var-PV'><filename>PV</filename></link>
454 variable will be set to 1.1.
455 </para>
456
457 <para>
458 If we then have a recipe named <filename>a_1.2.bb</filename>, BitBake
459 will choose 1.2 by default.
460 However, if we define the following variable in a
461 <filename>.conf</filename> file that BitBake parses, we
462 can change that.
463 <literallayout class='monospaced'>
464 PREFERRED_VERSION_a = "1.1"
465 </literallayout>
466 </para>
361 </section> 467 </section>
362 468
363 <section id='bb-bitbake-dependencies'> 469 <section id='bb-bitbake-dependencies'>
@@ -422,7 +528,20 @@
422 compile timestamp for a given target, then the compile task would rerun. 528 compile timestamp for a given target, then the compile task would rerun.
423 Running the compile task again, however, has no effect on other providers 529 Running the compile task again, however, has no effect on other providers
424 that depend on that target. 530 that depend on that target.
425 This behavior could change or become configurable in future versions of BitBake. 531 </para>
532
533 <para>
534 The exact format of the stamps is partly configurable.
535 In modern versions of BitBake, a hash is appended to the
536 stamp so that if the configuration changes, the stamp becomes
537 invalid and the task is automatically rerun.
538 This hash, or signature used, is governed by the signature policy
539 that is configured (see the
540 "<link linkend='checksums'>Checksums (Signatures)</link>"
541 section for information).
542 It is also possible to append extra metadata to the stamp using
543 the "stamp-extra-info" task flag.
544 For example, OpenEmbedded uses this flag to make some tasks machine-specific.
426 </para> 545 </para>
427 546
428 <note> 547 <note>
@@ -462,7 +581,12 @@
462 </para> 581 </para>
463 582
464 <para> 583 <para>
465 Variables specific to scheduling functionality exist: 584 The order in which BitBake runs the tasks is controlled by its
585 task scheduler.
586 It is possible to configure the scheduler and define custom
587 implementations for specific use cases.
588 For more information, see these variables that control the
589 behavior:
466 <itemizedlist> 590 <itemizedlist>
467 <listitem><para> 591 <listitem><para>
468 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link> 592 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
@@ -471,22 +595,10 @@
471 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link> 595 <link linkend='var-BB_SCHEDULERS'><filename>BB_SCHEDULERS</filename></link>
472 </para></listitem> 596 </para></listitem>
473 </itemizedlist> 597 </itemizedlist>
474 </para> 598 It is possible to have functions run before and after a task's main
475 </section> 599 function.
476 600 This is done using the "prefuncs" and "postfuncs" flags of the task
477 <section id='setscene'> 601 that lists the functions to run.
478 <title>Setscene</title>
479
480 <para>
481 This section needs to get the concept of the setscene across.
482 The reader needs to know what it is and what it is used for during
483 the build process.
484 </para>
485
486 <para>
487 You can find more information on setscene metadata in the
488 "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
489 section.
490 </para> 602 </para>
491 </section> 603 </section>
492 604
@@ -495,10 +607,10 @@
495 607
496 <para> 608 <para>
497 A checksum is a unique signature of a task's inputs. 609 A checksum is a unique signature of a task's inputs.
498 The setscene code uses a checksum to determine if a task needs 610 The signature of a task can be used to determine if a task
499 to be run. 611 needs to be run.
500 Because it is a change in a task's inputs that triggers running 612 Because it is a change in a task's inputs that triggers running
501 the task, the process needs to detect all the inputs to a given task. 613 the task, BitBake needs to detect all the inputs to a given task.
502 For shell tasks, this turns out to be fairly easy because 614 For shell tasks, this turns out to be fairly easy because
503 BitBake generates a "run" shell script for each task and 615 BitBake generates a "run" shell script for each task and
504 it is possible to create a checksum that gives you a good idea of when 616 it is possible to create a checksum that gives you a good idea of when
@@ -514,6 +626,10 @@
514 affect the output for target packages. 626 affect the output for target packages.
515 The simplistic approach for excluding the working directory is to set 627 The simplistic approach for excluding the working directory is to set
516 it to some fixed value and create the checksum for the "run" script. 628 it to some fixed value and create the checksum for the "run" script.
629 BitBake goes one step better and uses the
630 <link linkend='var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></link>
631 variable to define a list of variables that should never be included
632 when generating the signatures.
517 </para> 633 </para>
518 634
519 <para> 635 <para>
@@ -652,4 +768,87 @@
652 section. 768 section.
653 </para> 769 </para>
654 </section> 770 </section>
771
772 <section id='setscene'>
773 <title>Setscene</title>
774
775 <para>
776 The setscene process enables BitBake to handle "pre-built" artifacts.
777 The ability to handle and reuse these artifacts allows BitBake
778 the luxury of not having to build something from scratch every time.
779 Instead, BitBake can use, when possible, existing build artifacts.
780 </para>
781
782 <para>
783 BitBake needs to have reliable data indicating whether or not an
784 artifact is compatible.
785 Signatures, described in the previous section, provide an ideal
786 way of representing whether an artifact is compatible.
787 If a signature is the same, an object can be reused.
788 </para>
789
790 <para>
791 If an object can be reused, the problem then becomes how to
792 replace a given task or set of tasks with the pre-built artifact.
793 BitBake solves the problem with the "setscene" process.
794 </para>
795
796 <para>
797 When BitBake is asked to build a given target, before building anything,
798 it first asks whether cached information is available for any of the
799 targets it's building, or any of the intermediate targets.
800 If cached information is available, BitBake uses this information instead of
801 running the main tasks.
802 </para>
803
804 <para>
805 BitBake first calls the function defined by the
806 <link linkend='var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>
807 variable with a list of tasks and corresponding
808 hashes it wants to build.
809 This function is designed to be fast and returns a list
810 of the tasks for which it believes in can obtain artifacts.
811 </para>
812
813 <para>
814 Next, for each of the tasks that were returned as possibilities,
815 BitBake executes a setscene version of the task that the possible
816 artifact covers.
817 Setscene versions of a task have the string "_setscene" appended to the
818 task name.
819 So, for example, the task with the name <filename>xxx</filename> has
820 a setscene task named <filename>xxx_setscene</filename>.
821 The setscene version of the task executes and provides the necessary
822 artifacts returning either success or failure.
823 <note>
824 Artifacts might need to be fetched from the network.
825 </note>
826 </para>
827
828 <para>
829 As previously mentioned, an artifact can cover more than one task.
830 For example, it is pointless to obtain a compiler if you
831 already have the compiled binary.
832 To handle this, BitBake calls the
833 <link linkend='var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>
834 function for each successful setscene task to know whether or not it needs
835 to obtain the dependencies of that task.
836 </para>
837
838 <para>
839 Finally, after all the setscene tasks have executed, BitBake calls the
840 function listed in
841 <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION'><filename>BB_SETSCENE_VERIFY_FUNCTION</filename></link>
842 with the list of tasks BitBake thinks has been "covered".
843 The metadata can then ensure that this list is correct and can
844 inform BitBake that it wants specific tasks to be run regardless
845 of the setscene result.
846 </para>
847
848 <para>
849 You can find more information on setscene metadata in the
850 "<link linkend='task-checksums-and-setscene'>Task Checksums and Setscene</link>"
851 section.
852 </para>
853 </section>
655</chapter> 854</chapter>
diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml
index 87951fd4b4..b4c1aa21d8 100644
--- a/bitbake/doc/user-manual/user-manual-fetching.xml
+++ b/bitbake/doc/user-manual/user-manual-fetching.xml
@@ -31,7 +31,7 @@
31 perhaps in a specific way. 31 perhaps in a specific way.
32 Getting and unpacking the files is often optionally followed 32 Getting and unpacking the files is often optionally followed
33 by patching. 33 by patching.
34 Patching, however, is not covered by the fetch. 34 Patching, however, is not covered by this module.
35 </para> 35 </para>
36 36
37 <para> 37 <para>
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index c1a9aed3a5..6f9ad2049a 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -322,6 +322,29 @@
322 Information in append files overrides the information in the 322 Information in append files overrides the information in the
323 similarly-named recipe file. 323 similarly-named recipe file.
324 </para> 324 </para>
325
326 <para>
327 When you name an append file, you can use the
328 wildcard character (%) to allow for matching recipe names.
329 For example, suppose you have an append file named
330 as follows:
331 <literallayout class='monospaced'>
332 busybox_1.21.%.bbappend
333 </literallayout>
334 That append file would match any <filename>busybox_1.21.x.bb</filename>
335 version of the recipe.
336 So, the append file would match the following recipe names:
337 <literallayout class='monospaced'>
338 busybox_1.21.1.bb
339 busybox_1.21.2.bb
340 busybox_1.21.3.bb
341 </literallayout>
342 If the <filename>busybox</filename> recipe was updated to
343 <filename>busybox_1.3.0.bb</filename>, the append name would not
344 match.
345 However, if you named the append file
346 <filename>busybox_1.%.bb</filename>, then you would have a match.
347 </para>
325 </section> 348 </section>
326 </section> 349 </section>
327 350
@@ -373,7 +396,13 @@
373 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis> 396 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
374 Downloading a snapshot of BitBake from the 397 Downloading a snapshot of BitBake from the
375 source code repository gives you access to a known 398 source code repository gives you access to a known
376 branch or release of BitBake.</para> 399 branch or release of BitBake.
400 <note>
401 Cloning the Git repository, as described earlier,
402 is the preferred method for getting BitBake.
403 Cloning the repository makes it easier to update as
404 patches are added to the stable branches.
405 </note></para>
377 <para>The following example downloads a snapshot of 406 <para>The following example downloads a snapshot of
378 BitBake version 1.17.0: 407 BitBake version 1.17.0:
379 <literallayout class='monospaced'> 408 <literallayout class='monospaced'>
@@ -387,4 +416,223 @@
387 </itemizedlist> 416 </itemizedlist>
388 </para> 417 </para>
389 </section> 418 </section>
419
420 <section id="user-manual-command">
421 <title>The BitBake Command</title>
422
423 <para>
424 BitBake is the underlying piece of the build system.
425 Two excellent examples are the Yocto Project and the OpenEmbedded
426 build systems.
427 Each provide an environment in which to develop embedded Linux
428 images, and each use BitBake as their underlying build engine.
429 </para>
430
431 <para>
432 BitBake facilitates executing tasks in a single <filename>.bb</filename>
433 file, or executing a given task on a set of multiple
434 <filename>.bb</filename> files, accounting for interdependencies
435 amongst them.
436 This section presents the BitBake syntax and provides some execution
437 examples.
438 </para>
439
440 <section id='usage-and-syntax'>
441 <title>Usage and syntax</title>
442
443 <para>
444 Following is the usage and syntax for BitBake:
445 <literallayout class='monospaced'>
446 $ bitbake -h
447Usage: bitbake [options] [recipename/target ...]
448
449 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
450 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
451 will provide the layer, BBFILES and other configuration information.
452
453Options:
454 --version show program's version number and exit
455 -h, --help show this help message and exit
456 -b BUILDFILE, --buildfile=BUILDFILE
457 Execute tasks from a specific .bb recipe directly.
458 WARNING: Does not handle any dependencies from other
459 recipes.
460 -k, --continue Continue as much as possible after an error. While the
461 target that failed and anything depending on it cannot
462 be built, as much as possible will be built before
463 stopping.
464 -a, --tryaltconfigs Continue with builds by trying to use alternative
465 providers where possible.
466 -f, --force Force the specified targets/task to run (invalidating
467 any existing stamp file).
468 -c CMD, --cmd=CMD Specify the task to execute. The exact options
469 available depend on the metadata. Some examples might
470 be 'compile' or 'populate_sysroot' or 'listtasks' may
471 give a list of the tasks available.
472 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
473 Invalidate the stamp for the specified task such as
474 'compile' and then run the default task for the
475 specified target(s).
476 -r PREFILE, --read=PREFILE
477 Read the specified file before bitbake.conf.
478 -R POSTFILE, --postread=POSTFILE
479 Read the specified file after bitbake.conf.
480 -v, --verbose Output more log message data to the terminal.
481 -D, --debug Increase the debug level. You can specify this more
482 than once.
483 -n, --dry-run Don't execute, just go through the motions.
484 -S, --dump-signatures
485 Don't execute, just dump out the signature
486 construction information.
487 -p, --parse-only Quit after parsing the BB recipes.
488 -s, --show-versions Show current and preferred versions of all recipes.
489 -e, --environment Show the global or per-package environment complete
490 with information about where variables were
491 set/changed.
492 -g, --graphviz Save dependency tree information for the specified
493 targets in the dot syntax.
494 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
495 Assume these dependencies don't exist and are already
496 provided (equivalent to ASSUME_PROVIDED). Useful to
497 make dependency graphs more appealing
498 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
499 Show debug logging for the specified logging domains
500 -P, --profile Profile the command and save reports.
501 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
502 -t SERVERTYPE, --servertype=SERVERTYPE
503 Choose which server to use, process or xmlrpc.
504 --revisions-changed Set the exit code depending on whether upstream
505 floating revisions have changed or not.
506 --server-only Run bitbake without a UI, only starting a server
507 (cooker) process.
508 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
509 --no-setscene Do not run any setscene tasks. sstate will be ignored
510 and everything needed, built.
511 --remote-server=REMOTE_SERVER
512 Connect to the specified server.
513 -m, --kill-server Terminate the remote server.
514 --observe-only Connect to a server as an observing-only client.
515 --status-only Check the status of the remote bitbake server.
516
517 </literallayout>
518 </para>
519 </section>
520
521 <section id='bitbake-examples'>
522 <title>Examples</title>
523
524 <para>
525 This section presents some examples showing how to use BitBake.
526 </para>
527
528 <section id='example-executing-a-task-against-a-single-recipe'>
529 <title>Executing a Task Against a Single Recipe</title>
530
531 <para>
532 Executing tasks for a single recipe file is relatively simple.
533 You specify the file in question, and BitBake parses
534 it and executes the specified task.
535 If you do not specify a task, BitBake executes the default
536 task, which is "build”.
537 BitBake obeys inter-task dependencies when doing
538 so.
539 </para>
540
541 <para>
542 The following command runs the clean task on the
543 <filename>foo_1.0.bb</filename> recipe file:
544 <literallayout class='monospaced'>
545 $ bitbake -b foo.bb -c clean
546 </literallayout>
547 The following command runs the build task, which is
548 the default task, on the <filename>foo_1.0.bb</filename>
549 recipe file:
550 <literallayout class='monospaced'>
551 $ bitbake -b foo_1.0.bb
552 </literallayout>
553 </para>
554 </section>
555
556 <section id='executing-tasks-against-a-set-of-recipe-files'>
557 <title>Executing Tasks Against a Set of Recipe Files</title>
558
559 <para>
560 There are a number of additional complexities introduced
561 when one wants to manage multiple <filename>.bb</filename>
562 files.
563 Clearly there needs to be a way to tell BitBake what
564 files are available, and of those, which you
565 want to execute.
566 There also needs to be a way for each recipe
567 to express its dependencies, both for build-time and
568 runtime.
569 There must be a way for you to express recipe preferences
570 when multiple recipes provide the same functionality, or when
571 there are multiple versions of a recipe.
572 </para>
573
574 <para>
575 The <filename>bitbake</filename> command, when not using
576 "--buildfile" or "-b" only accepts a "PROVIDER".
577 You cannot provide anything else.
578 By default, a recipe file generally "PROVIDES" its
579 "packagename", "packagename-version", and
580 "packagename-version-revision" as shown in the following
581 example:
582 <literallayout class='monospaced'>
583 $ bitbake foo
584
585 $ bitbake foo-1.0
586
587 $ bitbake foo-1.0-r0
588 </literallayout>
589 This next example "PROVIDES" the package name and also uses
590 the "-c" option to tell BitBake to just execute the
591 <filename>do_clean</filename> task:
592 <literallayout class='monospaced'>
593 $ bitbake -c clean foo
594 </literallayout>
595 </para>
596 </section>
597
598 <section id='generating-dependency-graphs'>
599 <title>Generating Dependency Graphs</title>
600
601 <para>
602 BitBake is able to generate dependency graphs using
603 the dot syntax.
604 You can convert these graphs into images using the dot
605 application from
606 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
607 </para>
608
609 <para>
610 When you generate a dependency graph, BitBake writes two files
611 to the current working directory:
612 <filename>depends.dot</filename>, which contains dependency information
613 at the package level, and <filename>task-depends.dot</filename>,
614 which contains a breakdown of the dependencies at the task level.
615 </para>
616
617 <para>
618 To stop depending on common depends, use use the "-I" depend
619 option and BitBake omits them from the graph.
620 Leaving this information out can produce more readable graphs.
621 This way, you can remove from the graph
622 <filename>DEPENDS</filename> from inherited classes
623 such as <filename>base.bbclass</filename>.
624 </para>
625
626 <para>
627 Here are two examples that create dependency graphs.
628 The second example omits common depends from the graph:
629 <literallayout class='monospaced'>
630 $ bitbake -g foo
631
632 $ bitbake -g -I virtual/whatever -I bloom foo
633 </literallayout>
634 </para>
635 </section>
636 </section>
637 </section>
390</chapter> 638</chapter>
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index cabf25fb6f..9cd8bf0e68 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -819,6 +819,20 @@
819 </para> 819 </para>
820 </section> 820 </section>
821 821
822 <section id='deleting-a-task'>
823 <title>Deleting a Task</title>
824
825 <para>
826 As well as being able to add tasks, tasks can also be deleted.
827 This is done simply with <filename>deltask</filename> command.
828 For example, to delete the example task used in the previous
829 sections, you would use:
830 <literallayout class='monospaced'>
831 deltask printdate
832 </literallayout>
833 </para>
834 </section>
835
822 <section id='passing-information-into-the-build-task-environment'> 836 <section id='passing-information-into-the-build-task-environment'>
823 <title>Passing Information Into the Build Task Environment</title> 837 <title>Passing Information Into the Build Task Environment</title>
824 838
@@ -867,6 +881,28 @@
867 </note></para></listitem> 881 </note></para></listitem>
868 </orderedlist> 882 </orderedlist>
869 </para> 883 </para>
884
885 <para>
886 Sometimes, its useful to be able to obtain information
887 from the original execution environment.
888 Bitbake saves a copy of the original environment into
889 a special variable named
890 <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
891 </para>
892
893 <para>
894 The <filename>BB_ORIGENV</filename> variable returns a datastore
895 object that can be queried using the standard datastore operators
896 such as <filename>getVar()</filename>.
897 The datastore object is useful, for example, to find the original
898 <filename>DISPLAY</filename> variable.
899 </para>
900
901 <para>
902 By default, BitBake cleans the environment to include only those
903 things exported or listed in its whitelist to ensure that the build
904 environment is reproducible and consistent.
905 </para>
870 </section> 906 </section>
871 </section> 907 </section>
872 908
@@ -975,6 +1011,17 @@
975 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" 1011 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
976 section for more information. 1012 section for more information.
977 </para></listitem> 1013 </para></listitem>
1014 <listitem><para><emphasis>postfuncs:</emphasis>
1015 List of functions to call after the completion of the task.
1016 </para></listitem>
1017 <listitem><para><emphasis>prefuncs:</emphasis>
1018 List of functions to call before the task executes.
1019 </para></listitem>
1020 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1021 Extra stamp information to append to the task's stamp
1022 As an example, OpenEmbedded uses this flag to allow
1023 machine-specific tasks.
1024 </para></listitem>
978 </itemizedlist> 1025 </itemizedlist>
979 </para> 1026 </para>
980 </section> 1027 </section>
@@ -1016,7 +1063,7 @@
1016 </para> 1063 </para>
1017 1064
1018 <para> 1065 <para>
1019 During all builds, the following common events occur: 1066 During a standard build, the following common events might occur:
1020 <itemizedlist> 1067 <itemizedlist>
1021 <listitem><para> 1068 <listitem><para>
1022 <filename>bb.event.ConfigParsed()</filename> 1069 <filename>bb.event.ConfigParsed()</filename>
@@ -1100,7 +1147,19 @@
1100 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> 1147 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
1101 and 1148 and
1102 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link> 1149 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
1103 variables: 1150 variables.
1151 <note>
1152 The mechanism for this class extension is extremely
1153 specific to the implementation.
1154 Usually, the recipe's
1155 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
1156 <link linkend='var-PN'><filename>PN</filename></link>, and
1157 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1158 variables would need to be modified by the extension class.
1159 For specific examples, see the OE-Core
1160 <filename>native</filename>, <filename>nativesdk</filename>,
1161 and <filename>multilib</filename> classes.
1162 </note>
1104 <itemizedlist> 1163 <itemizedlist>
1105 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis> 1164 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
1106 This variable is a space separated list of classes used to "extend" the 1165 This variable is a space separated list of classes used to "extend" the
diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml
index e1bf2b561d..ff2d59a6e6 100644
--- a/bitbake/doc/user-manual/user-manual-ref-variables.xml
+++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml
@@ -388,16 +388,15 @@
388 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm> 388 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
389 <glossdef> 389 <glossdef>
390 <para> 390 <para>
391 Lists variables that are excluded from checksum 391 Lists variables that are excluded from base configuration
392 comparisons to determine if the cache can be reused. 392 checksum, which is used to determine if the cache can
393 be reused.
393 </para> 394 </para>
394 395
395 <para> 396 <para>
396 One of the ways BitBake determines whether to re-parse the 397 One of the ways BitBake determines whether to re-parse the
397 main metadata is through checksums of the variables in the 398 main metadata is through checksums of the variables in the
398 datastore of the base configuration data (see the 399 datastore of the base configuration data.
399 <link linkend='var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></link>
400 variable).
401 There are variables that you typically want to exclude when 400 There are variables that you typically want to exclude when
402 checking whether or not to re-parse and thus rebuild the 401 checking whether or not to re-parse and thus rebuild the
403 cache. 402 cache.
diff --git a/bitbake/doc/user-manual/user-manual.xml b/bitbake/doc/user-manual/user-manual.xml
index 76c3edf527..9f94886c7f 100644
--- a/bitbake/doc/user-manual/user-manual.xml
+++ b/bitbake/doc/user-manual/user-manual.xml
@@ -81,8 +81,6 @@
81 81
82 <xi:include href="user-manual-fetching.xml"/> 82 <xi:include href="user-manual-fetching.xml"/>
83 83
84 <xi:include href="user-manual-bitbakecommand.xml"/>
85
86 <xi:include href="user-manual-ref-variables.xml"/> 84 <xi:include href="user-manual-ref-variables.xml"/>
87 85
88 <xi:include href="user-manual-hello.xml"/> 86 <xi:include href="user-manual-hello.xml"/>