diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-11-13 00:21:41 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-01-04 10:55:00 +0000 |
commit | 22384b2fe567406b3c318b2edd0d23dee0d72023 (patch) | |
tree | b19414c699324722f371d4138c305e925a43da95 /bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst | |
parent | 16d477fa5d2bec49ccd83ede8249431d30e0c80c (diff) | |
download | poky-22384b2fe567406b3c318b2edd0d23dee0d72023.tar.gz |
bitbake: sphinx: import sphinx docs
The Bitbake manual was migrated to Sphinx in Yocto Project 3.2. Since
the docs between 3.2 and 3.1 are "similar", and since 3.1 is an LTS
release, we agreed to backport the documentation onto 3.1.
If we look at all docs changes in 3.1 and 3.2, we have the following:
=== Changes in 3.1
git log --oneline b94dec477a8d48ebceec91952ba290798c56c1f5..origin/1.46 -- doc/
====
324aaa7f bitbake-user-manual-metadata.xml: fix a minor error
f92e19a3 doc: More explanation to tasks that recursively depend on themselves
e4695176 doc: Clarify how task dependencies relate to RDEPENDS
25c5c79b user manual: properly tag content as <replaceable>
be367887 docs: delete reference to obsolete recipe-depends.dot
=== Changes in 3.2/master
git log --oneline b94dec477a8d48ebceec91952ba290798c56c1f5..origin/master -- doc/
====
a7c47f1e sphinx: rename Makefile.sphinx
427721d8 sphinx: remove DocBook files
d52190ea docs: static: theme_overrides.css: fix responsive design on <640px screens
9ae5cce7 docs: sphinx: report errors when dependencies are not met
ec4c481a docs: update README file after migrationg to Sphinx
c87cc35a docs: sphinx: replace special quotes with double quotes
ebdeef2c docs: ref-variables: add links to terms in glossary
29081375 bitbake-user-manual: fix bad links
a0f37789 sphinx: theme_override: Use bold for emphasis text
cbc5ca48 sphinx: theme_override: properly set font for verbatim text
08b1ae23 sphinx: remove leading '/'
99ba6fe9 sphinx: update style for important, caution and warnings
d99760cc sphinx: last manual round of fixes/improvements
4f94633a sphinx: bitbake-user-manual: insert additional blank line after title
63adcaa5 sphinx: add releases page
3e940d93 sphinx: conf: enable extlinks extension
9921c652 sphinx: index: move the boilerplate at the end of the page
4e461224 sphinx: add SPDX headers
cb19159c sphinx: Enhance the sphinx experience/nagivation with:
10a54678 sphinx: tweak html output a bit
219b2348 sphinx: Makefile.sphinx: add clean and publish targets
35fdc185 sphinx: fixes all remaining warnings
e11d2dd1 sphinx: fix links inside notes
57300955 sphinx: fixup for links
fa304c01 sphinx: override theme CSS
29af1cd2 sphinx: switch to readthedocs theme
e8359fd8 sphinx: bitbake-user-manual: use builtin sphinx glossary
6bf6c8d6 sphinx: initial sphinx support
84ccba0f sphinx: add initial build infrastructure
44b57216 bitbake-user-manual: update perforce fetcher docs
9186ca47 bitbake-user-manual: Add BBFILES_DYNAMIC
7689fa78 bitbake-user-manual: Remove TERM from BB_HASHBASE_WHITELIST example
06b5cf0a bitbake-user-manual-metadata.xml: fix a minor error
c92a266c doc: More explanation to tasks that recursively depend on themselves
caf42243 doc: Clarify how task dependencies relate to RDEPENDS
647c13d4 user manual: properly tag content as <replaceable>
2effbb6e docs: delete reference to obsolete recipe-depends.dot
We can conclude the following commits exist in 3.2 and not in 3.1 (if
we filter out sphinx changes)
44b57216 bitbake-user-manual: update perforce fetcher docs
9186ca47 bitbake-user-manual: Add BBFILES_DYNAMIC
7689fa78 bitbake-user-manual: Remove TERM from BB_HASHBASE_WHITELIST example
Out of these 3 changes, the following patches are for 3.2 only:
44b57216 bitbake-user-manual: update perforce fetcher docs
7689fa78 bitbake-user-manual: Remove TERM from BB_HASHBASE_WHITELIST example
To backport the Sphinx docs, we then need to cherry-pick all docs
patches from 3.2/1.48 and 'undo' the two patches above.
This first patch is the first step that imports all Sphinx files, and
remove Docbook files. It was done with the following command:
git cherry-pick -n \
$(git log --reverse --oneline \
b94dec477a8d48ebceec91952ba290798c56c1f5..origin/master -- doc/ \
| cut -f1 -d' ')
(Bitbake rev: cd68f14031eb45006b44d10b348e35c69ac21ad0)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst')
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst | 651 |
1 files changed, 651 insertions, 0 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst new file mode 100644 index 0000000000..6f9d392935 --- /dev/null +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst | |||
@@ -0,0 +1,651 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.5 | ||
2 | |||
3 | ======== | ||
4 | Overview | ||
5 | ======== | ||
6 | |||
7 | | | ||
8 | |||
9 | Welcome to the BitBake User Manual. This manual provides information on | ||
10 | the BitBake tool. The information attempts to be as independent as | ||
11 | possible regarding systems that use BitBake, such as OpenEmbedded and | ||
12 | the Yocto Project. In some cases, scenarios or examples within the | ||
13 | context of a build system are used in the manual to help with | ||
14 | understanding. For these cases, the manual clearly states the context. | ||
15 | |||
16 | .. _intro: | ||
17 | |||
18 | Introduction | ||
19 | ============ | ||
20 | |||
21 | Fundamentally, BitBake is a generic task execution engine that allows | ||
22 | shell and Python tasks to be run efficiently and in parallel while | ||
23 | working within complex inter-task dependency constraints. One of | ||
24 | BitBake's main users, OpenEmbedded, takes this core and builds embedded | ||
25 | Linux software stacks using a task-oriented approach. | ||
26 | |||
27 | Conceptually, BitBake is similar to GNU Make in some regards but has | ||
28 | significant differences: | ||
29 | |||
30 | - BitBake executes tasks according to provided metadata that builds up | ||
31 | the tasks. Metadata is stored in recipe (``.bb``) and related recipe | ||
32 | "append" (``.bbappend``) files, configuration (``.conf``) and | ||
33 | underlying include (``.inc``) files, and in class (``.bbclass``) | ||
34 | files. The metadata provides BitBake with instructions on what tasks | ||
35 | to run and the dependencies between those tasks. | ||
36 | |||
37 | - BitBake includes a fetcher library for obtaining source code from | ||
38 | various places such as local files, source control systems, or | ||
39 | websites. | ||
40 | |||
41 | - The instructions for each unit to be built (e.g. a piece of software) | ||
42 | are known as "recipe" files and contain all the information about the | ||
43 | unit (dependencies, source file locations, checksums, description and | ||
44 | so on). | ||
45 | |||
46 | - BitBake includes a client/server abstraction and can be used from a | ||
47 | command line or used as a service over XML-RPC and has several | ||
48 | different user interfaces. | ||
49 | |||
50 | History and Goals | ||
51 | ================= | ||
52 | |||
53 | BitBake was originally a part of the OpenEmbedded project. It was | ||
54 | inspired by the Portage package management system used by the Gentoo | ||
55 | Linux distribution. On December 7, 2004, OpenEmbedded project team | ||
56 | member Chris Larson split the project into two distinct pieces: | ||
57 | |||
58 | - BitBake, a generic task executor | ||
59 | |||
60 | - OpenEmbedded, a metadata set utilized by BitBake | ||
61 | |||
62 | Today, BitBake is the primary basis of the | ||
63 | `OpenEmbedded <http://www.openembedded.org/>`__ project, which is being | ||
64 | used to build and maintain Linux distributions such as the `Angstrom | ||
65 | Distribution <http://www.angstrom-distribution.org/>`__, and which is | ||
66 | also being used as the build tool for Linux projects such as the `Yocto | ||
67 | Project <http://www.yoctoproject.org>`__. | ||
68 | |||
69 | Prior to BitBake, no other build tool adequately met the needs of an | ||
70 | aspiring embedded Linux distribution. All of the build systems used by | ||
71 | traditional desktop Linux distributions lacked important functionality, | ||
72 | and none of the ad hoc Buildroot-based systems, prevalent in the | ||
73 | embedded space, were scalable or maintainable. | ||
74 | |||
75 | Some important original goals for BitBake were: | ||
76 | |||
77 | - Handle cross-compilation. | ||
78 | |||
79 | - Handle inter-package dependencies (build time on target architecture, | ||
80 | build time on native architecture, and runtime). | ||
81 | |||
82 | - Support running any number of tasks within a given package, | ||
83 | including, but not limited to, fetching upstream sources, unpacking | ||
84 | them, patching them, configuring them, and so forth. | ||
85 | |||
86 | - Be Linux distribution agnostic for both build and target systems. | ||
87 | |||
88 | - Be architecture agnostic. | ||
89 | |||
90 | - Support multiple build and target operating systems (e.g. Cygwin, the | ||
91 | BSDs, and so forth). | ||
92 | |||
93 | - Be self-contained, rather than tightly integrated into the build | ||
94 | machine's root filesystem. | ||
95 | |||
96 | - Handle conditional metadata on the target architecture, operating | ||
97 | system, distribution, and machine. | ||
98 | |||
99 | - Be easy to use the tools to supply local metadata and packages | ||
100 | against which to operate. | ||
101 | |||
102 | - Be easy to use BitBake to collaborate between multiple projects for | ||
103 | their builds. | ||
104 | |||
105 | - Provide an inheritance mechanism to share common metadata between | ||
106 | many packages. | ||
107 | |||
108 | Over time it became apparent that some further requirements were | ||
109 | necessary: | ||
110 | |||
111 | - Handle variants of a base recipe (e.g. native, sdk, and multilib). | ||
112 | |||
113 | - Split metadata into layers and allow layers to enhance or override | ||
114 | other layers. | ||
115 | |||
116 | - Allow representation of a given set of input variables to a task as a | ||
117 | checksum. Based on that checksum, allow acceleration of builds with | ||
118 | prebuilt components. | ||
119 | |||
120 | BitBake satisfies all the original requirements and many more with | ||
121 | extensions being made to the basic functionality to reflect the | ||
122 | additional requirements. Flexibility and power have always been the | ||
123 | priorities. BitBake is highly extensible and supports embedded Python | ||
124 | code and execution of any arbitrary tasks. | ||
125 | |||
126 | .. _Concepts: | ||
127 | |||
128 | Concepts | ||
129 | ======== | ||
130 | |||
131 | BitBake is a program written in the Python language. At the highest | ||
132 | level, BitBake interprets metadata, decides what tasks are required to | ||
133 | run, and executes those tasks. Similar to GNU Make, BitBake controls how | ||
134 | software is built. GNU Make achieves its control through "makefiles", | ||
135 | while BitBake uses "recipes". | ||
136 | |||
137 | BitBake extends the capabilities of a simple tool like GNU Make by | ||
138 | allowing for the definition of much more complex tasks, such as | ||
139 | assembling entire embedded Linux distributions. | ||
140 | |||
141 | The remainder of this section introduces several concepts that should be | ||
142 | understood in order to better leverage the power of BitBake. | ||
143 | |||
144 | Recipes | ||
145 | ------- | ||
146 | |||
147 | BitBake Recipes, which are denoted by the file extension ``.bb``, are | ||
148 | the most basic metadata files. These recipe files provide BitBake with | ||
149 | the following: | ||
150 | |||
151 | - Descriptive information about the package (author, homepage, license, | ||
152 | and so on) | ||
153 | |||
154 | - The version of the recipe | ||
155 | |||
156 | - Existing dependencies (both build and runtime dependencies) | ||
157 | |||
158 | - Where the source code resides and how to fetch it | ||
159 | |||
160 | - Whether the source code requires any patches, where to find them, and | ||
161 | how to apply them | ||
162 | |||
163 | - How to configure and compile the source code | ||
164 | |||
165 | - How to assemble the generated artifacts into one or more installable | ||
166 | packages | ||
167 | |||
168 | - Where on the target machine to install the package or packages | ||
169 | created | ||
170 | |||
171 | Within the context of BitBake, or any project utilizing BitBake as its | ||
172 | build system, files with the ``.bb`` extension are referred to as | ||
173 | recipes. | ||
174 | |||
175 | .. note:: | ||
176 | |||
177 | The term "package" is also commonly used to describe recipes. | ||
178 | However, since the same word is used to describe packaged output from | ||
179 | a project, it is best to maintain a single descriptive term - | ||
180 | "recipes". Put another way, a single "recipe" file is quite capable | ||
181 | of generating a number of related but separately installable | ||
182 | "packages". In fact, that ability is fairly common. | ||
183 | |||
184 | Configuration Files | ||
185 | ------------------- | ||
186 | |||
187 | Configuration files, which are denoted by the ``.conf`` extension, | ||
188 | define various configuration variables that govern the project's build | ||
189 | process. These files fall into several areas that define machine | ||
190 | configuration, distribution configuration, possible compiler tuning, | ||
191 | general common configuration, and user configuration. The main | ||
192 | configuration file is the sample ``bitbake.conf`` file, which is located | ||
193 | within the BitBake source tree ``conf`` directory. | ||
194 | |||
195 | Classes | ||
196 | ------- | ||
197 | |||
198 | Class files, which are denoted by the ``.bbclass`` extension, contain | ||
199 | information that is useful to share between metadata files. The BitBake | ||
200 | source tree currently comes with one class metadata file called | ||
201 | ``base.bbclass``. You can find this file in the ``classes`` directory. | ||
202 | The ``base.bbclass`` class files is special since it is always included | ||
203 | automatically for all recipes and classes. This class contains | ||
204 | definitions for standard basic tasks such as fetching, unpacking, | ||
205 | configuring (empty by default), compiling (runs any Makefile present), | ||
206 | installing (empty by default) and packaging (empty by default). These | ||
207 | tasks are often overridden or extended by other classes added during the | ||
208 | project development process. | ||
209 | |||
210 | Layers | ||
211 | ------ | ||
212 | |||
213 | Layers allow you to isolate different types of customizations from each | ||
214 | other. While you might find it tempting to keep everything in one layer | ||
215 | when working on a single project, the more modular your metadata, the | ||
216 | easier it is to cope with future changes. | ||
217 | |||
218 | To illustrate how you can use layers to keep things modular, consider | ||
219 | customizations you might make to support a specific target machine. | ||
220 | These types of customizations typically reside in a special layer, | ||
221 | rather than a general layer, called a Board Support Package (BSP) layer. | ||
222 | Furthermore, the machine customizations should be isolated from recipes | ||
223 | and metadata that support a new GUI environment, for example. This | ||
224 | situation gives you a couple of layers: one for the machine | ||
225 | configurations and one for the GUI environment. It is important to | ||
226 | understand, however, that the BSP layer can still make machine-specific | ||
227 | additions to recipes within the GUI environment layer without polluting | ||
228 | the GUI layer itself with those machine-specific changes. You can | ||
229 | accomplish this through a recipe that is a BitBake append | ||
230 | (``.bbappend``) file. | ||
231 | |||
232 | .. _append-bbappend-files: | ||
233 | |||
234 | Append Files | ||
235 | ------------ | ||
236 | |||
237 | Append files, which are files that have the ``.bbappend`` file | ||
238 | extension, extend or override information in an existing recipe file. | ||
239 | |||
240 | BitBake expects every append file to have a corresponding recipe file. | ||
241 | Furthermore, the append file and corresponding recipe file must use the | ||
242 | same root filename. The filenames can differ only in the file type | ||
243 | suffix used (e.g. ``formfactor_0.0.bb`` and | ||
244 | ``formfactor_0.0.bbappend``). | ||
245 | |||
246 | Information in append files extends or overrides the information in the | ||
247 | underlying, similarly-named recipe files. | ||
248 | |||
249 | When you name an append file, you can use the "``%``" wildcard character | ||
250 | to allow for matching recipe names. For example, suppose you have an | ||
251 | append file named as follows: :: | ||
252 | |||
253 | busybox_1.21.%.bbappend | ||
254 | |||
255 | That append file | ||
256 | would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, | ||
257 | the append file would match the following recipe names: :: | ||
258 | |||
259 | busybox_1.21.1.bb | ||
260 | busybox_1.21.2.bb | ||
261 | busybox_1.21.3.bb | ||
262 | |||
263 | .. note:: | ||
264 | |||
265 | The use of the " % " character is limited in that it only works directly in | ||
266 | front of the .bbappend portion of the append file's name. You cannot use the | ||
267 | wildcard character in any other location of the name. | ||
268 | |||
269 | If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the | ||
270 | append name would not match. However, if you named the append file | ||
271 | ``busybox_1.%.bbappend``, then you would have a match. | ||
272 | |||
273 | In the most general case, you could name the append file something as | ||
274 | simple as ``busybox_%.bbappend`` to be entirely version independent. | ||
275 | |||
276 | Obtaining BitBake | ||
277 | ================= | ||
278 | |||
279 | You can obtain BitBake several different ways: | ||
280 | |||
281 | - **Cloning BitBake:** Using Git to clone the BitBake source code | ||
282 | repository is the recommended method for obtaining BitBake. Cloning | ||
283 | the repository makes it easy to get bug fixes and have access to | ||
284 | stable branches and the master branch. Once you have cloned BitBake, | ||
285 | you should use the latest stable branch for development since the | ||
286 | master branch is for BitBake development and might contain less | ||
287 | stable changes. | ||
288 | |||
289 | You usually need a version of BitBake that matches the metadata you | ||
290 | are using. The metadata is generally backwards compatible but not | ||
291 | forward compatible. | ||
292 | |||
293 | Here is an example that clones the BitBake repository: :: | ||
294 | |||
295 | $ git clone git://git.openembedded.org/bitbake | ||
296 | |||
297 | This command clones the BitBake | ||
298 | Git repository into a directory called ``bitbake``. Alternatively, | ||
299 | you can designate a directory after the ``git clone`` command if you | ||
300 | want to call the new directory something other than ``bitbake``. Here | ||
301 | is an example that names the directory ``bbdev``: :: | ||
302 | |||
303 | $ git clone git://git.openembedded.org/bitbake bbdev | ||
304 | |||
305 | - **Installation using your Distribution Package Management System:** | ||
306 | This method is not recommended because the BitBake version that is | ||
307 | provided by your distribution, in most cases, is several releases | ||
308 | behind a snapshot of the BitBake repository. | ||
309 | |||
310 | - **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake | ||
311 | from the source code repository gives you access to a known branch or | ||
312 | release of BitBake. | ||
313 | |||
314 | .. note:: | ||
315 | |||
316 | Cloning the Git repository, as described earlier, is the preferred | ||
317 | method for getting BitBake. Cloning the repository makes it easier | ||
318 | to update as patches are added to the stable branches. | ||
319 | |||
320 | The following example downloads a snapshot of BitBake version 1.17.0: :: | ||
321 | |||
322 | $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz | ||
323 | $ tar zxpvf bitbake-1.17.0.tar.gz | ||
324 | |||
325 | After extraction of the tarball using | ||
326 | the tar utility, you have a directory entitled ``bitbake-1.17.0``. | ||
327 | |||
328 | - **Using the BitBake that Comes With Your Build Checkout:** A final | ||
329 | possibility for getting a copy of BitBake is that it already comes | ||
330 | with your checkout of a larger BitBake-based build system, such as | ||
331 | Poky. Rather than manually checking out individual layers and gluing | ||
332 | them together yourself, you can check out an entire build system. The | ||
333 | checkout will already include a version of BitBake that has been | ||
334 | thoroughly tested for compatibility with the other components. For | ||
335 | information on how to check out a particular BitBake-based build | ||
336 | system, consult that build system's supporting documentation. | ||
337 | |||
338 | .. _bitbake-user-manual-command: | ||
339 | |||
340 | The BitBake Command | ||
341 | =================== | ||
342 | |||
343 | The ``bitbake`` command is the primary interface to the BitBake tool. | ||
344 | This section presents the BitBake command syntax and provides several | ||
345 | execution examples. | ||
346 | |||
347 | Usage and syntax | ||
348 | ---------------- | ||
349 | |||
350 | Following is the usage and syntax for BitBake: :: | ||
351 | |||
352 | $ bitbake -h | ||
353 | Usage: bitbake [options] [recipename/target recipe:do_task ...] | ||
354 | |||
355 | Executes the specified task (default is 'build') for a given set of target recipes (.bb files). | ||
356 | It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which | ||
357 | will provide the layer, BBFILES and other configuration information. | ||
358 | |||
359 | Options: | ||
360 | --version show program's version number and exit | ||
361 | -h, --help show this help message and exit | ||
362 | -b BUILDFILE, --buildfile=BUILDFILE | ||
363 | Execute tasks from a specific .bb recipe directly. | ||
364 | WARNING: Does not handle any dependencies from other | ||
365 | recipes. | ||
366 | -k, --continue Continue as much as possible after an error. While the | ||
367 | target that failed and anything depending on it cannot | ||
368 | be built, as much as possible will be built before | ||
369 | stopping. | ||
370 | -f, --force Force the specified targets/task to run (invalidating | ||
371 | any existing stamp file). | ||
372 | -c CMD, --cmd=CMD Specify the task to execute. The exact options | ||
373 | available depend on the metadata. Some examples might | ||
374 | be 'compile' or 'populate_sysroot' or 'listtasks' may | ||
375 | give a list of the tasks available. | ||
376 | -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP | ||
377 | Invalidate the stamp for the specified task such as | ||
378 | 'compile' and then run the default task for the | ||
379 | specified target(s). | ||
380 | -r PREFILE, --read=PREFILE | ||
381 | Read the specified file before bitbake.conf. | ||
382 | -R POSTFILE, --postread=POSTFILE | ||
383 | Read the specified file after bitbake.conf. | ||
384 | -v, --verbose Enable tracing of shell tasks (with 'set -x'). Also | ||
385 | print bb.note(...) messages to stdout (in addition to | ||
386 | writing them to ${T}/log.do_<task>). | ||
387 | -D, --debug Increase the debug level. You can specify this more | ||
388 | than once. -D sets the debug level to 1, where only | ||
389 | bb.debug(1, ...) messages are printed to stdout; -DD | ||
390 | sets the debug level to 2, where both bb.debug(1, ...) | ||
391 | and bb.debug(2, ...) messages are printed; etc. | ||
392 | Without -D, no debug messages are printed. Note that | ||
393 | -D only affects output to stdout. All debug messages | ||
394 | are written to ${T}/log.do_taskname, regardless of the | ||
395 | debug level. | ||
396 | -q, --quiet Output less log message data to the terminal. You can | ||
397 | specify this more than once. | ||
398 | -n, --dry-run Don't execute, just go through the motions. | ||
399 | -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER | ||
400 | Dump out the signature construction information, with | ||
401 | no task execution. The SIGNATURE_HANDLER parameter is | ||
402 | passed to the handler. Two common values are none and | ||
403 | printdiff but the handler may define more/less. none | ||
404 | means only dump the signature, printdiff means compare | ||
405 | the dumped signature with the cached one. | ||
406 | -p, --parse-only Quit after parsing the BB recipes. | ||
407 | -s, --show-versions Show current and preferred versions of all recipes. | ||
408 | -e, --environment Show the global or per-recipe environment complete | ||
409 | with information about where variables were | ||
410 | set/changed. | ||
411 | -g, --graphviz Save dependency tree information for the specified | ||
412 | targets in the dot syntax. | ||
413 | -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED | ||
414 | Assume these dependencies don't exist and are already | ||
415 | provided (equivalent to ASSUME_PROVIDED). Useful to | ||
416 | make dependency graphs more appealing | ||
417 | -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS | ||
418 | Show debug logging for the specified logging domains | ||
419 | -P, --profile Profile the command and save reports. | ||
420 | -u UI, --ui=UI The user interface to use (knotty, ncurses or taskexp | ||
421 | - default knotty). | ||
422 | --token=XMLRPCTOKEN Specify the connection token to be used when | ||
423 | connecting to a remote server. | ||
424 | --revisions-changed Set the exit code depending on whether upstream | ||
425 | floating revisions have changed or not. | ||
426 | --server-only Run bitbake without a UI, only starting a server | ||
427 | (cooker) process. | ||
428 | -B BIND, --bind=BIND The name/address for the bitbake xmlrpc server to bind | ||
429 | to. | ||
430 | -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT | ||
431 | Set timeout to unload bitbake server due to | ||
432 | inactivity, set to -1 means no unload, default: | ||
433 | Environment variable BB_SERVER_TIMEOUT. | ||
434 | --no-setscene Do not run any setscene tasks. sstate will be ignored | ||
435 | and everything needed, built. | ||
436 | --setscene-only Only run setscene tasks, don't run any real tasks. | ||
437 | --remote-server=REMOTE_SERVER | ||
438 | Connect to the specified server. | ||
439 | -m, --kill-server Terminate any running bitbake server. | ||
440 | --observe-only Connect to a server as an observing-only client. | ||
441 | --status-only Check the status of the remote bitbake server. | ||
442 | -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG | ||
443 | Writes the event log of the build to a bitbake event | ||
444 | json file. Use '' (empty string) to assign the name | ||
445 | automatically. | ||
446 | --runall=RUNALL Run the specified task for any recipe in the taskgraph | ||
447 | of the specified target (even if it wouldn't otherwise | ||
448 | have run). | ||
449 | --runonly=RUNONLY Run only the specified task within the taskgraph of | ||
450 | the specified targets (and any task dependencies those | ||
451 | tasks may have). | ||
452 | |||
453 | .. _bitbake-examples: | ||
454 | |||
455 | Examples | ||
456 | -------- | ||
457 | |||
458 | This section presents some examples showing how to use BitBake. | ||
459 | |||
460 | .. _example-executing-a-task-against-a-single-recipe: | ||
461 | |||
462 | Executing a Task Against a Single Recipe | ||
463 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
464 | |||
465 | Executing tasks for a single recipe file is relatively simple. You | ||
466 | specify the file in question, and BitBake parses it and executes the | ||
467 | specified task. If you do not specify a task, BitBake executes the | ||
468 | default task, which is "build". BitBake obeys inter-task dependencies | ||
469 | when doing so. | ||
470 | |||
471 | The following command runs the build task, which is the default task, on | ||
472 | the ``foo_1.0.bb`` recipe file: :: | ||
473 | |||
474 | $ bitbake -b foo_1.0.bb | ||
475 | |||
476 | The following command runs the clean task on the ``foo.bb`` recipe file: :: | ||
477 | |||
478 | $ bitbake -b foo.bb -c clean | ||
479 | |||
480 | .. note:: | ||
481 | |||
482 | The "-b" option explicitly does not handle recipe dependencies. Other | ||
483 | than for debugging purposes, it is instead recommended that you use | ||
484 | the syntax presented in the next section. | ||
485 | |||
486 | Executing Tasks Against a Set of Recipe Files | ||
487 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
488 | |||
489 | There are a number of additional complexities introduced when one wants | ||
490 | to manage multiple ``.bb`` files. Clearly there needs to be a way to | ||
491 | tell BitBake what files are available and, of those, which you want to | ||
492 | execute. There also needs to be a way for each recipe to express its | ||
493 | dependencies, both for build-time and runtime. There must be a way for | ||
494 | you to express recipe preferences when multiple recipes provide the same | ||
495 | functionality, or when there are multiple versions of a recipe. | ||
496 | |||
497 | The ``bitbake`` command, when not using "--buildfile" or "-b" only | ||
498 | accepts a "PROVIDES". You cannot provide anything else. By default, a | ||
499 | recipe file generally "PROVIDES" its "packagename" as shown in the | ||
500 | following example: :: | ||
501 | |||
502 | $ bitbake foo | ||
503 | |||
504 | This next example "PROVIDES" the | ||
505 | package name and also uses the "-c" option to tell BitBake to just | ||
506 | execute the ``do_clean`` task: :: | ||
507 | |||
508 | $ bitbake -c clean foo | ||
509 | |||
510 | Executing a List of Task and Recipe Combinations | ||
511 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
512 | |||
513 | The BitBake command line supports specifying different tasks for | ||
514 | individual targets when you specify multiple targets. For example, | ||
515 | suppose you had two targets (or recipes) ``myfirstrecipe`` and | ||
516 | ``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first | ||
517 | recipe and ``taskB`` for the second recipe: :: | ||
518 | |||
519 | $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB | ||
520 | |||
521 | Generating Dependency Graphs | ||
522 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
523 | |||
524 | BitBake is able to generate dependency graphs using the ``dot`` syntax. | ||
525 | You can convert these graphs into images using the ``dot`` tool from | ||
526 | `Graphviz <http://www.graphviz.org>`__. | ||
527 | |||
528 | When you generate a dependency graph, BitBake writes two files to the | ||
529 | current working directory: | ||
530 | |||
531 | - ``task-depends.dot``: Shows dependencies between tasks. These | ||
532 | dependencies match BitBake's internal task execution list. | ||
533 | |||
534 | - ``pn-buildlist``: Shows a simple list of targets that are to be | ||
535 | built. | ||
536 | |||
537 | To stop depending on common depends, use the "-I" depend option and | ||
538 | BitBake omits them from the graph. Leaving this information out can | ||
539 | produce more readable graphs. This way, you can remove from the graph | ||
540 | ``DEPENDS`` from inherited classes such as ``base.bbclass``. | ||
541 | |||
542 | Here are two examples that create dependency graphs. The second example | ||
543 | omits depends common in OpenEmbedded from the graph: :: | ||
544 | |||
545 | $ bitbake -g foo | ||
546 | |||
547 | $ bitbake -g -I virtual/kernel -I eglibc foo | ||
548 | |||
549 | Executing a Multiple Configuration Build | ||
550 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
551 | |||
552 | BitBake is able to build multiple images or packages using a single | ||
553 | command where the different targets require different configurations | ||
554 | (multiple configuration builds). Each target, in this scenario, is | ||
555 | referred to as a "multiconfig". | ||
556 | |||
557 | To accomplish a multiple configuration build, you must define each | ||
558 | target's configuration separately using a parallel configuration file in | ||
559 | the build directory. The location for these multiconfig configuration | ||
560 | files is specific. They must reside in the current build directory in a | ||
561 | sub-directory of ``conf`` named ``multiconfig``. Following is an example | ||
562 | for two separate targets: | ||
563 | |||
564 | .. image:: figures/bb_multiconfig_files.png | ||
565 | :align: center | ||
566 | |||
567 | The reason for this required file hierarchy is because the ``BBPATH`` | ||
568 | variable is not constructed until the layers are parsed. Consequently, | ||
569 | using the configuration file as a pre-configuration file is not possible | ||
570 | unless it is located in the current working directory. | ||
571 | |||
572 | Minimally, each configuration file must define the machine and the | ||
573 | temporary directory BitBake uses for the build. Suggested practice | ||
574 | dictates that you do not overlap the temporary directories used during | ||
575 | the builds. | ||
576 | |||
577 | Aside from separate configuration files for each target, you must also | ||
578 | enable BitBake to perform multiple configuration builds. Enabling is | ||
579 | accomplished by setting the | ||
580 | :term:`BBMULTICONFIG` variable in the | ||
581 | ``local.conf`` configuration file. As an example, suppose you had | ||
582 | configuration files for ``target1`` and ``target2`` defined in the build | ||
583 | directory. The following statement in the ``local.conf`` file both | ||
584 | enables BitBake to perform multiple configuration builds and specifies | ||
585 | the two extra multiconfigs: :: | ||
586 | |||
587 | BBMULTICONFIG = "target1 target2" | ||
588 | |||
589 | Once the target configuration files are in place and BitBake has been | ||
590 | enabled to perform multiple configuration builds, use the following | ||
591 | command form to start the builds: :: | ||
592 | |||
593 | $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ] | ||
594 | |||
595 | Here is an example for two extra multiconfigs: ``target1`` and ``target2``: :: | ||
596 | |||
597 | $ bitbake mc::target mc:target1:target mc:target2:target | ||
598 | |||
599 | .. _bb-enabling-multiple-configuration-build-dependencies: | ||
600 | |||
601 | Enabling Multiple Configuration Build Dependencies | ||
602 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
603 | |||
604 | Sometimes dependencies can exist between targets (multiconfigs) in a | ||
605 | multiple configuration build. For example, suppose that in order to | ||
606 | build an image for a particular architecture, the root filesystem of | ||
607 | another build for a different architecture needs to exist. In other | ||
608 | words, the image for the first multiconfig depends on the root | ||
609 | filesystem of the second multiconfig. This dependency is essentially | ||
610 | that the task in the recipe that builds one multiconfig is dependent on | ||
611 | the completion of the task in the recipe that builds another | ||
612 | multiconfig. | ||
613 | |||
614 | To enable dependencies in a multiple configuration build, you must | ||
615 | declare the dependencies in the recipe using the following statement | ||
616 | form: :: | ||
617 | |||
618 | task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" | ||
619 | |||
620 | To better show how to use this statement, consider an example with two | ||
621 | multiconfigs: ``target1`` and ``target2``: :: | ||
622 | |||
623 | image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task" | ||
624 | |||
625 | In this example, the | ||
626 | ``from_multiconfig`` is "target1" and the ``to_multiconfig`` is "target2". The | ||
627 | task on which the image whose recipe contains image_task depends on the | ||
628 | completion of the rootfs_task used to build out image2, which is | ||
629 | associated with the "target2" multiconfig. | ||
630 | |||
631 | Once you set up this dependency, you can build the "target1" multiconfig | ||
632 | using a BitBake command as follows: :: | ||
633 | |||
634 | $ bitbake mc:target1:image1 | ||
635 | |||
636 | This command executes all the tasks needed to create ``image1`` for the "target1" | ||
637 | multiconfig. Because of the dependency, BitBake also executes through | ||
638 | the ``rootfs_task`` for the "target2" multiconfig build. | ||
639 | |||
640 | Having a recipe depend on the root filesystem of another build might not | ||
641 | seem that useful. Consider this change to the statement in the image1 | ||
642 | recipe: :: | ||
643 | |||
644 | image_task[mcdepends] = "mc:target1:target2:image2:image_task" | ||
645 | |||
646 | In this case, BitBake must create ``image2`` for the "target2" build since | ||
647 | the "target1" build depends on it. | ||
648 | |||
649 | Because "target1" and "target2" are enabled for multiple configuration | ||
650 | builds and have separate configuration files, BitBake places the | ||
651 | artifacts for each build in the respective temporary build directories. | ||