summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--bitbake/doc/user-manual/user-manual-bitbakecommand.xml353
1 files changed, 245 insertions, 108 deletions
diff --git a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
index 3cf779b12c..d3f4595d84 100644
--- a/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
+++ b/bitbake/doc/user-manual/user-manual-bitbakecommand.xml
@@ -1,16 +1,24 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
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 <section> 6
7 <title>Introduction</title> 7 <section>
8 <para>bitbake is the primary command in the system. It facilitates executing tasks in a single .bb file, or executing a given task on a set of multiple .bb files, accounting for interdependencies amongst them.</para> 8 <title>Introduction</title>
9 </section> 9
10 <section> 10 <para>
11 <title>Usage and syntax</title> 11 bitbake is the primary command in the system.
12 <para> 12 It facilitates executing tasks in a single .bb
13 <screen><prompt>$ </prompt>bitbake --help 13 file, or executing a given task on a set of multiple
14 .bb files, accounting for interdependencies
15 amongst them.
16 </para>
17 </section>
18 <section>
19 <title>Usage and syntax</title>
20 <para>
21 <screen><prompt>$ </prompt>bitbake --help
14Usage: bitbake [options] [recipename/target ...] 22Usage: bitbake [options] [recipename/target ...]
15 23
16 Executes the specified task (default is 'build') for a given set of target recipes (.bb files). 24 Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
@@ -80,101 +88,230 @@ Options:
80 -m, --kill-server Terminate the remote server. 88 -m, --kill-server Terminate the remote server.
81 --observe-only Connect to a server as an observing-only client. 89 --observe-only Connect to a server as an observing-only client.
82 --status-only Check the status of the remote bitbake server. 90 --status-only Check the status of the remote bitbake server.
83</screen> 91 </screen>
84 </para> 92 </para>
85 <para> 93 <para>
86 <example> 94
87 <title>Executing a task against a single .bb</title> 95 <example>
88 <para>Executing tasks for a single file is relatively simple. You specify the file in question, and BitBake parses it and executes the specified task (or <quote>build</quote> by default). It obeys intertask dependencies when doing so.</para> 96
89 <para><quote>clean</quote> task:</para> 97 <title>Executing a task against a single .bb</title>
90 <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb -c clean</screen></para> 98
91 <para><quote>build</quote> task:</para> 99 <para>
92 <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb</screen></para> 100 Executing tasks for a single file is relatively simple.
93 </example> 101 You specify the file in question, and BitBake parses
94 </para> 102 it and executes the specified task (or <quote>build</quote> by default).
103 It obeys intertask dependencies when doing so.
104 </para>
105
106 <para><quote>clean</quote> task:</para>
107 <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb -c clean</screen></para>
108 <para><quote>build</quote> task:</para>
109 <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb</screen></para>
110 </example>
111 </para>
112 <para>
113 <example>
114 <title>Executing tasks against a set of .bb files</title>
115 <para>
116 There are a number of additional complexities introduced
117 when one wants to manage multiple .bb
118 files.
119 Clearly there needs to be a way to tell BitBake what
120 files are available, and of those, which we
121 want to execute at this time
122 There also needs to be a way for each .bb
123 to express its dependencies, both for build time and
124 runtime.
125 There must be a way for the user to express their preferences
126 when multiple .bb's provide the same functionality, or when
127 there are multiple versions of a .bb.
128 </para>
129
130 <para>
131 The next section, Metadata, outlines how to specify such things.
132 </para>
133
134 <para>
135 Note that the bitbake command, when not using
136 --buildfile, accepts a <varname>PROVIDER</varname>, not a filename or
137 anything else.
138 By default, a .bb generally PROVIDES its
139 packagename, packagename-version, and packagename-version-revision.
140 </para>
141 <screen><prompt>$ </prompt>bitbake blah</screen>
142 <screen><prompt>$ </prompt>bitbake blah-1.0</screen>
143 <screen><prompt>$ </prompt>bitbake blah-1.0-r0</screen>
144 <screen><prompt>$ </prompt>bitbake -c clean blah</screen>
145 <screen><prompt>$ </prompt>bitbake virtual/whatever</screen>
146 <screen><prompt>$ </prompt>bitbake -c clean virtual/whatever</screen>
147 </example>
148 <example>
149 <title>Generating dependency graphs</title>
95 <para> 150 <para>
96 <example> 151 BitBake is able to generate dependency graphs using
97 <title>Executing tasks against a set of .bb files</title> 152 the dot syntax.
98 <para>There are a number of additional complexities introduced when one wants to manage multiple .bb files. Clearly there needs to be a way to tell BitBake what files are available, and of those, which we want to execute at this time. There also needs to be a way for each .bb to express its dependencies, both for build time and runtime. There must be a way for the user to express their preferences when multiple .bb's provide the same functionality, or when there are multiple versions of a .bb.</para> 153 These graphs can be converted to images using the <application>dot</application>
99 <para>The next section, Metadata, outlines how to specify such things.</para> 154 application from
100 <para>Note that the bitbake command, when not using --buildfile, accepts a <varname>PROVIDER</varname>, not a filename or anything else. By default, a .bb generally PROVIDES its packagename, packagename-version, and packagename-version-revision.</para> 155 <ulink url="http://www.graphviz.org">Graphviz</ulink>.
101 <screen><prompt>$ </prompt>bitbake blah</screen> 156 Two files will be written into the current working directory,
102 <screen><prompt>$ </prompt>bitbake blah-1.0</screen> 157 <emphasis>depends.dot</emphasis> containing dependency information
103 <screen><prompt>$ </prompt>bitbake blah-1.0-r0</screen> 158 at the package level and <emphasis>task-depends.dot</emphasis>
104 <screen><prompt>$ </prompt>bitbake -c clean blah</screen> 159 containing a breakdown of the dependencies at the task level.
105 <screen><prompt>$ </prompt>bitbake virtual/whatever</screen> 160 To stop depending on common depends, one can use the <prompt>-I depend</prompt>
106 <screen><prompt>$ </prompt>bitbake -c clean virtual/whatever</screen> 161 to omit these from the graph.
107 </example> 162 This can lead to more readable graphs.
108 <example> 163 This way, <varname>DEPENDS</varname> from inherited classes
109 <title>Generating dependency graphs</title> 164 such as base.bbclass can be removed from the
110 <para>BitBake is able to generate dependency graphs using the dot syntax. These graphs can be converted 165 graph.
111to images using the <application>dot</application> application from <ulink url="http://www.graphviz.org">Graphviz</ulink>. 166 </para>
112Two files will be written into the current working directory, <emphasis>depends.dot</emphasis> containing dependency information at the package level and <emphasis>task-depends.dot</emphasis> containing a breakdown of the dependencies at the task level. To stop depending on common depends, one can use the <prompt>-I depend</prompt> to omit these from the graph. This can lead to more readable graphs. This way, <varname>DEPENDS</varname> from inherited classes such as base.bbclass can be removed from the graph.</para> 167 <screen><prompt>$ </prompt>bitbake -g blah</screen>
113 <screen><prompt>$ </prompt>bitbake -g blah</screen> 168 <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen>
114 <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen> 169 </example>
115 </example> 170 </para>
116 </para> 171 </section>
117 </section> 172
118 <section> 173 <section>
119 <title>Special variables</title> 174 <title>Special variables</title>
120 <para>Certain variables affect BitBake operation:</para> 175
121 <section> 176 <para>
122 <title><varname>BB_NUMBER_THREADS</varname></title> 177 Certain variables affect BitBake operation:
123 <para> The number of threads BitBake should run at once (default: 1).</para> 178 </para>
124 </section> 179
125 </section> 180 <section>
126 <section> 181 <title><varname>BB_NUMBER_THREADS</varname></title>
127 <title>Metadata</title> 182
128 <para>As you may have seen in the usage information, or in the information about .bb files, the <varname>BBFILES</varname> variable is how the BitBake tool locates its files. This variable is a space separated list of files that are available, and supports wildcards. 183 <para>
129 <example> 184 The number of threads BitBake should run at once (default: 1).
130 <title>Setting BBFILES</title> 185 </para>
131 <programlisting><varname>BBFILES</varname> = "/path/to/bbfiles/*.bb"</programlisting> 186 </section>
132 </example></para> 187 </section>
133 <para>With regard to dependencies, it expects the .bb to define a <varname>DEPENDS</varname> variable, which contains a space separated list of <quote>package names</quote>, which themselves are the <varname>PN</varname> variable. The <varname>PN</varname> variable is, in general, set to a component of the .bb filename by default.</para> 188
134 <example> 189 <section>
135 <title>Depending on another .bb</title> 190 <title>Metadata</title>
136 <para>a.bb: 191 <para>
137 <screen>PN = "package-a" 192 As you may have seen in the usage information, or in the
193 information about .bb files, the
194 <varname>BBFILES</varname> variable is how the BitBake
195 tool locates its files.
196 This variable is a space separated list of files
197 that are available, and supports wildcards.
198 <example>
199 <title>Setting BBFILES</title>
200
201 <programlisting><varname>BBFILES</varname> = "/path/to/bbfiles/*.bb"</programlisting>
202 </example></para>
203 <para>
204 With regard to dependencies, it expects the
205 .bb to define a
206 <varname>DEPENDS</varname> variable, which contains a
207 space separated list of <quote>package names</quote>, which themselves
208 are the <varname>PN</varname> variable. The
209 <varname>PN</varname> variable is, in general,
210 set to a component of the .bb
211 filename by default.
212 </para>
213
214 <example>
215 <title>Depending on another .bb</title>
216
217 <para>
218a.bb:
219<screen>PN = "package-a"
138DEPENDS += "package-b"</screen> 220DEPENDS += "package-b"</screen>
139 </para> 221 </para>
140 <para>b.bb: 222 <para>
141 <screen>PN = "package-b"</screen> 223b.bb:
142 </para> 224<screen>PN = "package-b"</screen>
143 </example> 225 </para>
144 <example> 226 </example>
145 <title>Using PROVIDES</title> 227
146 <para>This example shows the usage of the <varname>PROVIDES</varname> variable, which allows a given .bb to specify what functionality it provides.</para> 228 <example>
147 <para>package1.bb: 229 <title>Using PROVIDES</title>
148 <screen>PROVIDES += "virtual/package"</screen> 230
149 </para> 231 <para>
150 <para>package2.bb: 232This example shows the usage of the <varname>PROVIDES</varname> variable, which allows a given .bb to specify what functionality it provides.
151 <screen>DEPENDS += "virtual/package"</screen> 233</para>
152 </para> 234 <para>
153 <para>package3.bb: 235package1.bb:
154 <screen>PROVIDES += "virtual/package"</screen> 236<screen>PROVIDES += "virtual/package"</screen>
155 </para> 237 </para>
156 <para>As you can see, we have two different .bb's that provide the same functionality (virtual/package). Clearly, there needs to be a way for the person running BitBake to control which of those providers gets used. There is, indeed, such a way.</para> 238 <para>
157 <para>The following would go into a .conf file, to select package1: 239package2.bb:
158 <screen>PREFERRED_PROVIDER_virtual/package = "package1"</screen> 240<screen>DEPENDS += "virtual/package"</screen>
159 </para> 241 </para>
160 </example> 242 <para>
161 <example> 243package3.bb:
162 <title>Specifying version preference</title> 244<screen>PROVIDES += "virtual/package"</screen>
163 <para>When there are multiple <quote>versions</quote> of a given package, BitBake defaults to selecting the most recent version, unless otherwise specified. If the .bb in question has a <varname>DEFAULT_PREFERENCE</varname> set lower than the other .bb's (default is 0), then it will not be selected. This allows the person or persons maintaining the repository of .bb files to specify their preference for the default selected version. In addition, the user can specify their preferred version.</para> 245 </para>
164 <para>If the first .bb is named <filename>a_1.1.bb</filename>, then the <varname>PN</varname> variable will be set to <quote>a</quote>, and the <varname>PV</varname> variable will be set to 1.1.</para> 246 <para>
165 <para>If we then have an <filename>a_1.2.bb</filename>, BitBake will choose 1.2 by default. However, if we define the following variable in a .conf that BitBake parses, we can change that. 247 As you can see, we have two different
166 <screen>PREFERRED_VERSION_a = "1.1"</screen> 248 .bb's that provide the same functionality
167 </para> 249 (virtual/package).
168 </example> 250 Clearly, there needs to be a way for the person running
169 <example> 251 BitBake to control which of those providers
170 <title>Using <quote>bbfile collections</quote></title> 252 gets used.
171 <para>bbfile collections exist to allow the user to have multiple repositories of bbfiles that contain the same exact package. For example, one could easily use them to make one's own local copy of an upstream repository, but with custom modifications that one does not want upstream. Usage:</para> 253 There is, indeed, such a way.
172 <screen>BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" 254 </para>
173BBFILE_COLLECTIONS = "upstream local" 255 <para>
174BBFILE_PATTERN_upstream = "^/stuff/openembedded/" 256The following would go into a .conf file, to select package1:
175BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" 257<screen>PREFERRED_PROVIDER_virtual/package = "package1"</screen>
176BBFILE_PRIORITY_upstream = "5" 258 </para>
177BBFILE_PRIORITY_local = "10"</screen> 259 </example>
178 </example> 260
179 </section> 261 <example>
180 </chapter> 262 <title>Specifying version preference</title>
263
264 <para>
265 When there are multiple <quote>versions</quote> of a given package,
266 BitBake defaults to selecting the most recent version,
267 unless otherwise specified.
268 If the .bb in question has a
269 <varname>DEFAULT_PREFERENCE</varname> set lower than
270 the other .bb's (default is 0), then it will not be
271 selected.
272 This allows the person or persons maintaining
273 the repository of .bb files to specify
274 their preference for the default selected version.
275 In addition, the user can specify their preferred version.
276 </para>
277
278 <para>
279 If the first .bb is named
280 <filename>a_1.1.bb</filename>, then the
281 <varname>PN</varname> variable will be set to
282 <quote>a</quote>, and the <varname>PV</varname> variable will be
283 set to 1.1.
284 </para>
285
286 <para>
287 If we then have an <filename>a_1.2.bb</filename>, BitBake
288 will choose 1.2 by default.
289 However, if we define the following variable in a
290 .conf that BitBake parses, we
291 can change that.
292 <screen>PREFERRED_VERSION_a = "1.1"</screen>
293 </para>
294 </example>
295 <example>
296
297 <title>Using <quote>bbfile collections</quote></title>
298
299 <para>
300 bbfile collections exist to allow the user to
301 have multiple repositories of
302 bbfiles that contain the same
303 exact package.
304 For example, one could easily use them to make one's
305 own local copy of an upstream repository, but with
306 custom modifications that one does not want upstream.
307 Usage:
308 </para>
309 <screen> BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
310 BBFILE_COLLECTIONS = "upstream local"
311 BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
312 BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
313 BBFILE_PRIORITY_upstream = "5"
314 BBFILE_PRIORITY_local = "10"</screen>
315 </example>
316 </section>
317</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 13:54:31 +0000