diff options
-rw-r--r-- | bitbake/doc/user-manual/user-manual-bitbakecommand.xml | 341 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual-execution.xml | 329 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual-fetching.xml | 2 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual-intro.xml | 250 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 63 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual-ref-variables.xml | 9 | ||||
-rw-r--r-- | bitbake/doc/user-manual/user-manual.xml | 2 |
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 | ||
31 | Usage: 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 | |||
37 | Options: | ||
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 <target> | 23 | $ bitbake <target> |
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 | ||
447 | Usage: 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 | |||
453 | Options: | ||
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"/> |