diff options
author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-18 16:25:25 +0000 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-27 21:03:24 +0000 |
commit | bd4140578ebf3150691e453232ba9dc8fbcd96bc (patch) | |
tree | 5364a5398ef8fb8b9b25a58c05d2167566f5a25b /bitbake | |
parent | 5cce95c6028ab610e148e4d6884330151881dd98 (diff) | |
download | poky-bd4140578ebf3150691e453232ba9dc8fbcd96bc.tar.gz |
bitbake: user-manual-bitbakecommand: Various edits/cleanups
(Bitbake rev: f079e0886b1b191d84621057f9752cc32bfabb44)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-bitbakecommand.xml | 162 |
1 files changed, 88 insertions, 74 deletions
diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml index c8163331be..78da71d069 100644 --- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml +++ b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml | |||
@@ -2,16 +2,16 @@ | |||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
3 | 3 | ||
4 | <chapter> | 4 | <chapter> |
5 | <title>The BitBake command</title> | 5 | <title>The BitBake Command</title> |
6 | 6 | ||
7 | <section id='bitbake-command-introduction'> | 7 | <section id='bitbake-command-introduction'> |
8 | <title>Introduction</title> | 8 | <title>Introduction</title> |
9 | 9 | ||
10 | <para> | 10 | <para> |
11 | bitbake is the primary command in the system. | 11 | Bitbake is the primary command in the system. |
12 | It facilitates executing tasks in a single .bb | 12 | It facilitates executing tasks in a single <filename>.bb</filename> |
13 | file, or executing a given task on a set of multiple | 13 | file, or executing a given task on a set of multiple |
14 | .bb files, accounting for interdependencies | 14 | <filename>.bb</filename> files, accounting for interdependencies |
15 | amongst them. | 15 | amongst them. |
16 | </para> | 16 | </para> |
17 | </section> | 17 | </section> |
@@ -20,8 +20,9 @@ | |||
20 | <title>Usage and syntax</title> | 20 | <title>Usage and syntax</title> |
21 | 21 | ||
22 | <para> | 22 | <para> |
23 | Following is the usage and syntax for BitBake: | ||
23 | <literallayout class='monospaced'> | 24 | <literallayout class='monospaced'> |
24 | <prompt>$ </prompt>bitbake --help | 25 | $ bitbake -h |
25 | Usage: bitbake [options] [recipename/target ...] | 26 | Usage: bitbake [options] [recipename/target ...] |
26 | 27 | ||
27 | Executes the specified task (default is 'build') for a given set of target recipes (.bb files). | 28 | Executes the specified task (default is 'build') for a given set of target recipes (.bb files). |
@@ -99,23 +100,30 @@ Options: | |||
99 | <section id='bitbake-examples'> | 100 | <section id='bitbake-examples'> |
100 | <title>Examples</title> | 101 | <title>Examples</title> |
101 | 102 | ||
103 | <para> | ||
104 | This section presents some examples showing how to use BitBake. | ||
105 | </para> | ||
106 | |||
102 | <section id='example-executing-a-task-against-a-single-recipe'> | 107 | <section id='example-executing-a-task-against-a-single-recipe'> |
103 | <title>Executing a task against a single .bb</title> | 108 | <title>Executing a Task Against a Single Recipe</title> |
104 | 109 | ||
105 | <para> | 110 | <para> |
106 | Executing tasks for a single file is relatively simple. | 111 | Executing tasks for a single recipe file is relatively simple. |
107 | You specify the file in question, and BitBake parses | 112 | You specify the file in question, and BitBake parses |
108 | it and executes the specified task (or <quote>build</quote> by default). | 113 | it and executes the specified task (or “build” by default). |
109 | It obeys intertask dependencies when doing so. | 114 | BitBake obeys inter-task dependencies when doing |
115 | so. | ||
110 | </para> | 116 | </para> |
111 | 117 | ||
112 | <para> | 118 | <para> |
113 | <para><quote>clean</quote> task:</para> | 119 | The following command runs the clean task on the |
120 | <filename>foo_1.0.bb</filename> recipe file: | ||
114 | <literallayout class='monospaced'> | 121 | <literallayout class='monospaced'> |
115 | $ bitbake -b foo.bb -c clean | 122 | $ bitbake -b foo.bb -c clean |
116 | </literallayout> | 123 | </literallayout> |
117 | 124 | The following command runs the build task, which is | |
118 | <para><quote>build</quote> task:</para> | 125 | the default task, on the <filename>foo_1.0.bb</filename> |
126 | recipe file: | ||
119 | <literallayout class='monospaced'> | 127 | <literallayout class='monospaced'> |
120 | $ bitbake -b foo_1.0.bb | 128 | $ bitbake -b foo_1.0.bb |
121 | </literallayout> | 129 | </literallayout> |
@@ -123,20 +131,21 @@ Options: | |||
123 | </section> | 131 | </section> |
124 | 132 | ||
125 | <section id='executing-tasks-against-a-set-of-recipe-files'> | 133 | <section id='executing-tasks-against-a-set-of-recipe-files'> |
126 | <title>Executing tasks against a set of .bb files</title> | 134 | <title>Executing Tasks Against a Set of Recipe Files</title> |
135 | |||
127 | <para> | 136 | <para> |
128 | There are a number of additional complexities introduced | 137 | There are a number of additional complexities introduced |
129 | when one wants to manage multiple .bb | 138 | when one wants to manage multiple <filename>.bb</filename> |
130 | files. | 139 | files. |
131 | Clearly there needs to be a way to tell BitBake what | 140 | Clearly there needs to be a way to tell BitBake what |
132 | files are available, and of those, which we | 141 | files are available, and of those, which we |
133 | want to execute at this time | 142 | want to execute at this time. |
134 | There also needs to be a way for each .bb | 143 | There also needs to be a way for each <filename>.bb</filename> |
135 | to express its dependencies, both for build time and | 144 | to express its dependencies, both for build-time and |
136 | runtime. | 145 | runtime. |
137 | There must be a way for the user to express their preferences | 146 | There must be a way for the user to express their preferences |
138 | when multiple .bb's provide the same functionality, or when | 147 | when multiple recipes provide the same functionality, or when |
139 | there are multiple versions of a .bb. | 148 | there are multiple versions of a <filename>.bb</filename> file. |
140 | </para> | 149 | </para> |
141 | 150 | ||
142 | <para> | 151 | <para> |
@@ -144,10 +153,10 @@ Options: | |||
144 | </para> | 153 | </para> |
145 | 154 | ||
146 | <para> | 155 | <para> |
147 | Note that the bitbake command, when not using | 156 | The <filename>bitbake</filename> command, when not using |
148 | --buildfile, accepts a <varname>PROVIDER</varname>, not a filename or | 157 | "--buildfile", accepts a PROVIDER, not a filename or |
149 | anything else. | 158 | anything else. |
150 | By default, a .bb generally PROVIDES its | 159 | By default, a <filename>.bb</filename> generally PROVIDES its |
151 | packagename, packagename-version, and packagename-version-revision. | 160 | packagename, packagename-version, and packagename-version-revision. |
152 | <literallayout class='monospaced'> | 161 | <literallayout class='monospaced'> |
153 | $ bitbake foo | 162 | $ bitbake foo |
@@ -166,22 +175,23 @@ Options: | |||
166 | </section> | 175 | </section> |
167 | 176 | ||
168 | <section id='generating-dependency-graphs'> | 177 | <section id='generating-dependency-graphs'> |
169 | <title>Generating dependency graphs</title> | 178 | <title>Generating Dependency Graphs</title> |
170 | <para> | 179 | |
171 | BitBake is able to generate dependency graphs using | 180 | <para> |
181 | BitBake is able to generate dependency graphs using | ||
172 | the dot syntax. | 182 | the dot syntax. |
173 | These graphs can be converted to images using the <application>dot</application> | 183 | These graphs can be converted to images using the dot |
174 | application from | 184 | application from |
175 | <ulink url="http://www.graphviz.org">Graphviz</ulink>. | 185 | <ulink url='http://www.graphviz.org'>Graphviz</ulink>. |
176 | Two files will be written into the current working directory, | 186 | Two files will be written into the current working directory: |
177 | <emphasis>depends.dot</emphasis> containing dependency information | 187 | <filename>depends.dot</filename> containing dependency information |
178 | at the package level and <emphasis>task-depends.dot</emphasis> | 188 | at the package level and <filename>task-depends.dot</filename> |
179 | containing a breakdown of the dependencies at the task level. | 189 | containing a breakdown of the dependencies at the task level. |
180 | To stop depending on common depends, one can use the <prompt>-I depend</prompt> | 190 | To stop depending on common depends, one can use the "-I" depend |
181 | to omit these from the graph. | 191 | option to omit these from the graph. |
182 | This can lead to more readable graphs. | 192 | This can lead to more readable graphs. |
183 | This way, <varname>DEPENDS</varname> from inherited classes | 193 | This way, <filename>DEPENDS</filename> from inherited classes |
184 | such as base.bbclass can be removed from the | 194 | such as <filename>base.bbclass</filename> can be removed from the |
185 | graph. | 195 | graph. |
186 | <literallayout class='monospaced'> | 196 | <literallayout class='monospaced'> |
187 | $ bitbake -g foo | 197 | $ bitbake -g foo |
@@ -193,14 +203,14 @@ Options: | |||
193 | </section> | 203 | </section> |
194 | 204 | ||
195 | <section id='special-variables'> | 205 | <section id='special-variables'> |
196 | <title>Special variables</title> | 206 | <title>Special Variables</title> |
197 | 207 | ||
198 | <para> | 208 | <para> |
199 | Certain variables affect BitBake operation: | 209 | Certain variables affect BitBake operation: |
200 | </para> | 210 | </para> |
201 | 211 | ||
202 | <section id='bb-number-threads'> | 212 | <section id='bb-number-threads'> |
203 | <title><varname>BB_NUMBER_THREADS</varname></title> | 213 | <title><filename>BB_NUMBER_THREADS</filename></title> |
204 | 214 | ||
205 | <para> | 215 | <para> |
206 | The number of threads BitBake should run at once (default: 1). | 216 | The number of threads BitBake should run at once (default: 1). |
@@ -211,34 +221,35 @@ Options: | |||
211 | <section id='bitbake-command-metadata'> | 221 | <section id='bitbake-command-metadata'> |
212 | <title>Metadata</title> | 222 | <title>Metadata</title> |
213 | 223 | ||
214 | <para> | 224 | <para> |
215 | As you may have seen in the usage information, or in the | 225 | As you may have seen in the usage information, or in the |
216 | information about .bb files, the | 226 | information about <filename>.bb</filename> files, the |
217 | <varname>BBFILES</varname> variable is how the BitBake | 227 | <filename>BBFILES</filename> variable is how the BitBake |
218 | tool locates its files. | 228 | tool locates its files. |
219 | This variable is a space separated list of files | 229 | This variable is a space-separated list of files |
220 | that are available, and supports wildcards. | 230 | that are available, and supports wildcards. |
221 | </para> | 231 | </para> |
232 | |||
222 | <section id='setting-bbfiles'> | 233 | <section id='setting-bbfiles'> |
223 | <title>Setting BBFILES</title> | 234 | <title>Setting <filename>BBFILES</filename></title> |
224 | 235 | ||
225 | <para> | 236 | <para> |
226 | <literallayout class='monospaced'> | 237 | <literallayout class='monospaced'> |
227 | BBFILES = "/path/to/bbfiles/*.bb" | 238 | BBFILES = "/path/to/bbfiles/*.bb" |
228 | </literallayout> | 239 | </literallayout> |
229 | With regard to dependencies, it expects the | 240 | With regard to dependencies, it expects the |
230 | .bb to define a | 241 | <filename>.bb</filename> to define a |
231 | <varname>DEPENDS</varname> variable, which contains a | 242 | <filename>DEPENDS</filename> variable, which contains a |
232 | space separated list of <quote>package names</quote>, which themselves | 243 | space separated list of “package names”, which themselves |
233 | are the <varname>PN</varname> variable. The | 244 | are the <filename>PN</filename> variable. The |
234 | <varname>PN</varname> variable is, in general, | 245 | <filename>PN</filename> variable is, in general, |
235 | set to a component of the .bb | 246 | set to a component of the <filename>.bb</filename> |
236 | filename by default. | 247 | filename by default. |
237 | </para> | 248 | </para> |
238 | </section> | 249 | </section> |
239 | 250 | ||
240 | <section id='depending-on-another-recipe-file'> | 251 | <section id='depending-on-another-recipe-file'> |
241 | <title>Depending on another .bb</title> | 252 | <title>Depending on Another Recipe File</title> |
242 | 253 | ||
243 | <para> | 254 | <para> |
244 | <literallayout class='monospaced'> | 255 | <literallayout class='monospaced'> |
@@ -255,10 +266,13 @@ Options: | |||
255 | </section> | 266 | </section> |
256 | 267 | ||
257 | <section id='using-provides'> | 268 | <section id='using-provides'> |
258 | <title>Using PROVIDES</title> | 269 | <title>Using <filename>PROVIDES</filename></title> |
259 | 270 | ||
260 | <para> | 271 | <para> |
261 | This example shows the usage of the <varname>PROVIDES</varname> variable, which allows a given .bb to specify what functionality it provides. | 272 | This example shows the usage of the |
273 | <filename>PROVIDES</filename> variable, which allows a | ||
274 | given <filename>.bb</filename> to specify what | ||
275 | functionality it provides. | ||
262 | <literallayout class='monospaced'> | 276 | <literallayout class='monospaced'> |
263 | package1.bb: | 277 | package1.bb: |
264 | 278 | ||
@@ -273,7 +287,7 @@ This example shows the usage of the <varname>PROVIDES</varname> variable, which | |||
273 | PROVIDES += "virtual/package" | 287 | PROVIDES += "virtual/package" |
274 | </literallayout> | 288 | </literallayout> |
275 | As you can see, we have two different | 289 | As you can see, we have two different |
276 | .bb's that provide the same functionality | 290 | recipes that provide the same functionality |
277 | (virtual/package). | 291 | (virtual/package). |
278 | Clearly, there needs to be a way for the person running | 292 | Clearly, there needs to be a way for the person running |
279 | BitBake to control which of those providers | 293 | BitBake to control which of those providers |
@@ -282,7 +296,8 @@ This example shows the usage of the <varname>PROVIDES</varname> variable, which | |||
282 | </para> | 296 | </para> |
283 | 297 | ||
284 | <para> | 298 | <para> |
285 | The following would go into a .conf file, to select package1: | 299 | The following would go into a <filename>.conf</filename> |
300 | file, to select package1: | ||
286 | <literallayout class='monospaced'> | 301 | <literallayout class='monospaced'> |
287 | PREFERRED_PROVIDER_virtual/package = "package1" | 302 | PREFERRED_PROVIDER_virtual/package = "package1" |
288 | </literallayout> | 303 | </literallayout> |
@@ -290,27 +305,27 @@ The following would go into a .conf file, to select package1: | |||
290 | </section> | 305 | </section> |
291 | 306 | ||
292 | <section id='specifying-version-preference'> | 307 | <section id='specifying-version-preference'> |
293 | <title>Specifying version preference</title> | 308 | <title>Specifying Version Preference</title> |
294 | 309 | ||
295 | <para> | 310 | <para> |
296 | When there are multiple <quote>versions</quote> of a given package, | 311 | When there are multiple “versions” of a given package, |
297 | BitBake defaults to selecting the most recent version, | 312 | BitBake defaults to selecting the most recent |
298 | unless otherwise specified. | 313 | version, unless otherwise specified. |
299 | If the .bb in question has a | 314 | If the <filename>.bb</filename> in question has a |
300 | <varname>DEFAULT_PREFERENCE</varname> set lower than | 315 | <filename>DEFAULT_PREFERENCE</filename> set lower than |
301 | the other .bb's (default is 0), then it will not be | 316 | the other recipes (default is 0), then it will not be |
302 | selected. | 317 | selected. |
303 | This allows the person or persons maintaining | 318 | This allows the person or persons maintaining |
304 | the repository of .bb files to specify | 319 | the repository of <filename>.bb</filename> files to specify |
305 | their preference for the default selected version. | 320 | their preference for the default selected version. |
306 | In addition, the user can specify their preferred version. | 321 | In addition, the user can specify their preferred version. |
307 | </para> | 322 | </para> |
308 | 323 | ||
309 | <para> | 324 | <para> |
310 | If the first .bb is named | 325 | If the first <filename>.bb</filename> is named |
311 | <filename>a_1.1.bb</filename>, then the | 326 | <filename>a_1.1.bb</filename>, then the |
312 | <varname>PN</varname> variable will be set to | 327 | <filename>PN</filename> variable will be set to |
313 | <quote>a</quote>, and the <varname>PV</varname> variable will be | 328 | “a”, and the <filename>PV</filename> variable will be |
314 | set to 1.1. | 329 | set to 1.1. |
315 | </para> | 330 | </para> |
316 | 331 | ||
@@ -318,27 +333,26 @@ The following would go into a .conf file, to select package1: | |||
318 | If we then have an <filename>a_1.2.bb</filename>, BitBake | 333 | If we then have an <filename>a_1.2.bb</filename>, BitBake |
319 | will choose 1.2 by default. | 334 | will choose 1.2 by default. |
320 | However, if we define the following variable in a | 335 | However, if we define the following variable in a |
321 | .conf that BitBake parses, we | 336 | <filename>.conf</filename> file that BitBake parses, we |
322 | can change that. | 337 | can change that. |
323 | <literallayout class='monospaced'> | 338 | <literallayout class='monospaced'> |
324 | PREFERRED_VERSION_a = "1.1" | 339 | PREFERRED_VERSION_a = "1.1" |
325 | </literallayout> | 340 | </literallayout> |
326 | |||
327 | </para> | 341 | </para> |
328 | </section> | 342 | </section> |
329 | 343 | ||
330 | <section id='using-recipe-file-collections'> | 344 | <section id='using-recipe-file-collections'> |
331 | <title>Using <quote>bbfile collections</quote></title> | 345 | <title>Using Recipe File Collections</title> |
332 | 346 | ||
333 | <para> | 347 | <para> |
334 | bbfile collections exist to allow the user to | 348 | Recipe file collections exist to allow the user to |
335 | have multiple repositories of | 349 | have multiple repositories of |
336 | bbfiles that contain the same | 350 | <filename>.bb</filename> files that contain the same |
337 | exact package. | 351 | exact package. |
338 | For example, one could easily use them to make one's | 352 | For example, one could easily use them to make one's |
339 | own local copy of an upstream repository, but with | 353 | own local copy of an upstream repository, but with |
340 | custom modifications that one does not want upstream. | 354 | custom modifications that one does not want upstream. |
341 | Usage: | 355 | Here is an example: |
342 | <literallayout class='monospaced'> | 356 | <literallayout class='monospaced'> |
343 | BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" | 357 | BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" |
344 | BBFILE_COLLECTIONS = "upstream local" | 358 | BBFILE_COLLECTIONS = "upstream local" |