summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-bitbakecommand.xml')
-rw-r--r--bitbake/doc/user-manual/user-manual-bitbakecommand.xml341
1 files changed, 0 insertions, 341 deletions
diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
deleted file mode 100644
index 5c301a56f3..0000000000
--- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
+++ /dev/null
@@ -1,341 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="user-manual-command">
5 <title>The BitBake Command</title>
6
7 <para>
8 BitBake is the underlying piece of the build system.
9 Two excellent examples are the Yocto Project and the OpenEmbedded
10 build systems.
11 Each provide an environment in which to develop embedded Linux
12 images, and each use BitBake as their underlying build engine.
13 </para>
14
15 <para>
16 BitBake facilitates executing tasks in a single <filename>.bb</filename>
17 file, or executing a given task on a set of multiple
18 <filename>.bb</filename> files, accounting for interdependencies
19 amongst them.
20 This chapter presents the BitBake syntax, provides some execution
21 examples, and shows you how to control BitBake with key metadata.
22 </para>
23
24 <section id='usage-and-syntax'>
25 <title>Usage and syntax</title>
26
27 <para>
28 Following is the usage and syntax for BitBake:
29 <literallayout class='monospaced'>
30 $ bitbake -h
31Usage: bitbake [options] [recipename/target ...]
32
33 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
34 It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
35 will provide the layer, BBFILES and other configuration information.
36
37Options:
38 --version show program's version number and exit
39 -h, --help show this help message and exit
40 -b BUILDFILE, --buildfile=BUILDFILE
41 Execute tasks from a specific .bb recipe directly.
42 WARNING: Does not handle any dependencies from other
43 recipes.
44 -k, --continue Continue as much as possible after an error. While the
45 target that failed and anything depending on it cannot
46 be built, as much as possible will be built before
47 stopping.
48 -a, --tryaltconfigs Continue with builds by trying to use alternative
49 providers where possible.
50 -f, --force Force the specified targets/task to run (invalidating
51 any existing stamp file).
52 -c CMD, --cmd=CMD Specify the task to execute. The exact options
53 available depend on the metadata. Some examples might
54 be 'compile' or 'populate_sysroot' or 'listtasks' may
55 give a list of the tasks available.
56 -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
57 Invalidate the stamp for the specified task such as
58 'compile' and then run the default task for the
59 specified target(s).
60 -r PREFILE, --read=PREFILE
61 Read the specified file before bitbake.conf.
62 -R POSTFILE, --postread=POSTFILE
63 Read the specified file after bitbake.conf.
64 -v, --verbose Output more log message data to the terminal.
65 -D, --debug Increase the debug level. You can specify this more
66 than once.
67 -n, --dry-run Don't execute, just go through the motions.
68 -S, --dump-signatures
69 Don't execute, just dump out the signature
70 construction information.
71 -p, --parse-only Quit after parsing the BB recipes.
72 -s, --show-versions Show current and preferred versions of all recipes.
73 -e, --environment Show the global or per-package environment complete
74 with information about where variables were
75 set/changed.
76 -g, --graphviz Save dependency tree information for the specified
77 targets in the dot syntax.
78 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
79 Assume these dependencies don't exist and are already
80 provided (equivalent to ASSUME_PROVIDED). Useful to
81 make dependency graphs more appealing
82 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
83 Show debug logging for the specified logging domains
84 -P, --profile Profile the command and save reports.
85 -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp).
86 -t SERVERTYPE, --servertype=SERVERTYPE
87 Choose which server to use, process or xmlrpc.
88 --revisions-changed Set the exit code depending on whether upstream
89 floating revisions have changed or not.
90 --server-only Run bitbake without a UI, only starting a server
91 (cooker) process.
92 -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
93 --no-setscene Do not run any setscene tasks. sstate will be ignored
94 and everything needed, built.
95 --remote-server=REMOTE_SERVER
96 Connect to the specified server.
97 -m, --kill-server Terminate the remote server.
98 --observe-only Connect to a server as an observing-only client.
99 --status-only Check the status of the remote bitbake server.
100
101 </literallayout>
102 </para>
103 </section>
104
105 <section id='bitbake-examples'>
106 <title>Examples</title>
107
108 <para>
109 This section presents some examples showing how to use BitBake.
110 </para>
111
112 <section id='example-executing-a-task-against-a-single-recipe'>
113 <title>Executing a Task Against a Single Recipe</title>
114
115 <para>
116 Executing tasks for a single recipe file is relatively simple.
117 You specify the file in question, and BitBake parses
118 it and executes the specified task.
119 If you do not specify a task, BitBake executes the default
120 task, which is "build”.
121 BitBake obeys inter-task dependencies when doing
122 so.
123 </para>
124
125 <para>
126 The following command runs the clean task on the
127 <filename>foo_1.0.bb</filename> recipe file:
128 <literallayout class='monospaced'>
129 $ bitbake -b foo.bb -c clean
130 </literallayout>
131 The following command runs the build task, which is
132 the default task, on the <filename>foo_1.0.bb</filename>
133 recipe file:
134 <literallayout class='monospaced'>
135 $ bitbake -b foo_1.0.bb
136 </literallayout>
137 </para>
138 </section>
139
140 <section id='executing-tasks-against-a-set-of-recipe-files'>
141 <title>Executing Tasks Against a Set of Recipe Files</title>
142
143 <para>
144 There are a number of additional complexities introduced
145 when one wants to manage multiple <filename>.bb</filename>
146 files.
147 Clearly there needs to be a way to tell BitBake what
148 files are available, and of those, which you
149 want to execute.
150 There also needs to be a way for each recipe
151 to express its dependencies, both for build-time and
152 runtime.
153 There must be a way for you to express recipe preferences
154 when multiple recipes provide the same functionality, or when
155 there are multiple versions of a recipe.
156 </para>
157
158 <para>
159 The <filename>bitbake</filename> command, when not using
160 "--buildfile" or "-b" only accepts a "PROVIDER".
161 You cannot provide anything else.
162 By default, a recipe file generally "PROVIDES" its
163 "packagename", "packagename-version", and
164 "packagename-version-revision" as shown in the following
165 example:
166 <literallayout class='monospaced'>
167 $ bitbake foo
168
169 $ bitbake foo-1.0
170
171 $ bitbake foo-1.0-r0
172 </literallayout>
173 This next example "PROVIDES" the package name and also uses
174 the "-c" option to tell BitBake to just excute the
175 <filename>do_clean</filename> task:
176 <literallayout class='monospaced'>
177 $ bitbake -c clean foo
178 </literallayout>
179 </para>
180 </section>
181
182 <section id='generating-dependency-graphs'>
183 <title>Generating Dependency Graphs</title>
184
185 <para>
186 BitBake is able to generate dependency graphs using
187 the dot syntax.
188 You can convert these graphs into images using the dot
189 application from
190 <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
191 </para>
192
193 <para>
194 When you generate a dependency graph, BitBake writes two files
195 to the current working directory:
196 <filename>depends.dot</filename>, which contains dependency information
197 at the package level, and <filename>task-depends.dot</filename>,
198 which contains a breakdown of the dependencies at the task level.
199 </para>
200
201 <para>
202 To stop depending on common depends, use use the "-I" depend
203 option and BitBake omits them from the graph.
204 Leaving this information out can produce more readable graphs.
205 This way, you can remove from the graph
206 <filename>DEPENDS</filename> from inherited classes
207 such as <filename>base.bbclass</filename>.
208 </para>
209
210 <para>
211 Here are two exmples that create dependency graphs.
212 The second example omits common depends from the graph:
213 <literallayout class='monospaced'>
214 $ bitbake -g foo
215
216 $ bitbake -g -I virtual/whatever -I bloom foo
217 </literallayout>
218 </para>
219 </section>
220 </section>
221
222 <section id='controlling-bitbake'>
223 <title>Controlling BitBake</title>
224
225 <para>
226 Including variables in your recipe and class files help control
227 how BitBake operates.
228 </para>
229
230 <section id='execution-threads'>
231 <title>Execution Threads</title>
232
233 <para>
234 You can control how many thread BitBake supports by using the
235 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
236 variable.
237 You would set this in your <filename>local.conf</filename>
238 configuration file.
239 </para>
240 </section>
241
242 <section id='using-provides'>
243 <title>Using <filename>PROVIDES</filename></title>
244
245 <para>
246 This example shows the usage of the
247 <filename>PROVIDES</filename> variable, which allows a
248 given <filename>.bb</filename> to specify what
249 functionality it provides.
250 <literallayout class='monospaced'>
251 package1.bb:
252
253 PROVIDES += "virtual/package"
254
255 package2.bb:
256
257 DEPENDS += "virtual/package"
258
259 package3.bb:
260
261 PROVIDES += "virtual/package"
262 </literallayout>
263 As you can see, we have two different
264 recipes that provide the same functionality
265 (virtual/package).
266 Clearly, there needs to be a way for the person running
267 BitBake to control which of those providers
268 gets used.
269 There is, indeed, such a way.
270 </para>
271
272 <para>
273 The following would go into a <filename>.conf</filename>
274 file, to select package1:
275 <literallayout class='monospaced'>
276 PREFERRED_PROVIDER_virtual/package = "package1"
277 </literallayout>
278 </para>
279 </section>
280
281 <section id='specifying-version-preference'>
282 <title>Specifying Version Preference</title>
283
284 <para>
285 When there are multiple “versions” of a given package,
286 BitBake defaults to selecting the most recent
287 version, unless otherwise specified.
288 If the <filename>.bb</filename> in question has a
289 <filename>DEFAULT_PREFERENCE</filename> set lower than
290 the other recipes (default is 0), then it will not be
291 selected.
292 This allows the person or persons maintaining
293 the repository of <filename>.bb</filename> files to specify
294 their preference for the default selected version.
295 In addition, the user can specify their preferred version.
296 </para>
297
298 <para>
299 If the first <filename>.bb</filename> is named
300 <filename>a_1.1.bb</filename>, then the
301 <filename>PN</filename> variable will be set to
302 “a”, and the <filename>PV</filename> variable will be
303 set to 1.1.
304 </para>
305
306 <para>
307 If we then have an <filename>a_1.2.bb</filename>, BitBake
308 will choose 1.2 by default.
309 However, if we define the following variable in a
310 <filename>.conf</filename> file that BitBake parses, we
311 can change that.
312 <literallayout class='monospaced'>
313 PREFERRED_VERSION_a = "1.1"
314 </literallayout>
315 </para>
316 </section>
317
318 <section id='using-recipe-file-collections'>
319 <title>Using Recipe File Collections</title>
320
321 <para>
322 Recipe file collections exist to allow the user to
323 have multiple repositories of
324 <filename>.bb</filename> files that contain the same
325 exact package.
326 For example, one could easily use them to make one's
327 own local copy of an upstream repository, but with
328 custom modifications that one does not want upstream.
329 Here is an example:
330 <literallayout class='monospaced'>
331 BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
332 BBFILE_COLLECTIONS = "upstream local"
333 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
334 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
335 BBFILE_PRIORITY_upstream = "5"
336 BBFILE_PRIORITY_local = "10"
337 </literallayout>
338 </para>
339 </section>
340 </section>
341</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-06-15 16:18:55 +0000