summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/ref-bitbake.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual/ref-bitbake.xml')
-rw-r--r--documentation/poky-ref-manual/ref-bitbake.xml269
1 files changed, 135 insertions, 134 deletions
diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
index cf019aabcd..1a98b048be 100644
--- a/documentation/poky-ref-manual/ref-bitbake.xml
+++ b/documentation/poky-ref-manual/ref-bitbake.xml
@@ -28,15 +28,15 @@
28 <title>Parsing</title> 28 <title>Parsing</title>
29 29
30 <para> 30 <para>
31 The first thing BitBake does is work out its configuration by 31 BitBake parses configuration files, classes, and <filename>.bb</filename> files.
32 looking for a file called <filename>bitbake.conf</filename>. 32 </para>
33 BitBake examines the <varname>BBPATH</varname> environment 33
34 variable looking for a <filename class="directory">conf/</filename> 34 <para>
35 directory that contains a <filename>bitbake.conf</filename> file. 35 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
36 BitBake adds the first <filename>bitbake.conf</filename> file found in 36 Poky keeps this file in <filename class="directory">meta/conf/</filename>.
37 <varname>BBPATH</varname> (similar to the PATH environment variable). 37 BitBake finds it by examining the <varname>BBPATH</varname> environment
38 For Poky, <filename>bitbake.conf</filename> is found in <filename 38 variable and looking for the <filename class="directory">meta/conf/</filename>
39 class="directory">meta/conf/</filename>. 39 directory.
40 </para> 40 </para>
41 41
42 <para> 42 <para>
@@ -75,12 +75,12 @@
75 </para> 75 </para>
76 76
77 <para> 77 <para>
78 After the parsing of the configuration files is complete, the 78 After classes are included, the
79 variable <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> 79 variable <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm>
80 is set, usually in 80 is set, usually in
81 <filename>local.conf</filename>, and defines the list of places to search for 81 <filename>local.conf</filename>, and defines the list of places to search for
82 <filename class="extension">.bb</filename> files. 82 <filename class="extension">.bb</filename> files.
83 By default this specifies the <filename class="directory">meta/packages/ 83 By default, the BBFILES variable specifies the <filename class="directory">meta/packages/
84 </filename> directory within Poky, but other directories such as 84 </filename> directory within Poky, but other directories such as
85 <filename class="directory">meta-extras/</filename> can be included 85 <filename class="directory">meta-extras/</filename> can be included
86 too. 86 too.
@@ -92,19 +92,19 @@
92 BitBake parses each <filename class="extension">.bb</filename> file in BBFILES and 92 BitBake parses each <filename class="extension">.bb</filename> file in BBFILES and
93 stores the values of various variables. 93 stores the values of various variables.
94 In summary, for each <filename class="extension">.bb</filename> 94 In summary, for each <filename class="extension">.bb</filename>
95 file the configuration + base class of variables are set, followed 95 file the configuration plus the base class of variables are set, followed
96 by the data in the <filename class="extension">.bb</filename> file 96 by the data in the <filename class="extension">.bb</filename> file
97 itself, followed by any inherit commands that 97 itself, followed by any inherit commands that
98 <filename class="extension">.bb</filename> file might contain. 98 <filename class="extension">.bb</filename> file might contain.
99 </para> 99 </para>
100 100
101 <para> 101 <para>
102 Parsing <filename class="extension">.bb</filename> files is a time 102 Because parsing <filename class="extension">.bb</filename> files is a time
103 consuming process, so a cache is kept to speed up subsequent parsing. 103 consuming process, a cache is kept to speed up subsequent parsing.
104 This cache is invalid if the timestamp of the <filename class="extension">.bb</filename> 104 This cache is invalid if the timestamp of the <filename class="extension">.bb</filename>
105 file itself has changed, or if the timestamps of any of the include, 105 file itself changes, or if the timestamps of any of the include,
106 configuration or class files the <filename class="extension">.bb</filename> 106 configuration or class files the <filename class="extension">.bb</filename>
107 file depends on have changed. 107 file depends on changes.
108 </para> 108 </para>
109 </section> 109 </section>
110 110
@@ -113,58 +113,53 @@
113 113
114 <para> 114 <para>
115 Once all the <filename class="extension">.bb</filename> files have been 115 Once all the <filename class="extension">.bb</filename> files have been
116 parsed, BitBake will proceed to build "poky-image-sato" (or whatever was 116 parsed, BitBake starts to build the target (poky-image-sato in the previous section's
117 specified on the commandline) and looks for providers of that target. 117 example) and looks for providers of that target.
118 Once a provider is selected, BitBake resolves all the dependencies for 118 Once a provider is selected, BitBake resolves all the dependencies for
119 the target. In the case of "poky-image-sato", it would lead to 119 the target.
120 <filename>task-base.bb</filename> 120 In the case of "poky-image-sato", it would lead to <filename>task-base.bb</filename>,
121 which in turn would lead to packages like <application>Contacts</application>, 121 which in turn leads to packages like <application>Contacts</application>,
122 <application>Dates</application>, <application>BusyBox</application> 122 <application>Dates</application> and <application>BusyBox</application>.
123 and these in turn depend on glibc and the toolchain. 123 These packages in turn depend on glibc and the toolchain.
124 </para> 124 </para>
125 125
126 <para> 126 <para>
127 Sometimes a target might have multiple providers and a common example 127 Sometimes a target might have multiple providers.
128 is "virtual/kernel" that is provided by each kernel package. Each machine 128 An common example is "virtual/kernel", which is provided by each kernel package.
129 will often elect the best provider of its kernel with a line like the 129 Each machine often elects the best kernel provider by using a line similar to the
130 following in the machine configuration file: 130 following in the machine configuration file:
131 </para> 131 </para>
132 <programlisting><glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel = "linux-rp"</programlisting> 132
133 <programlisting>
134PREFERRED_PROVIDER_virtual/kernel = "linux-rp"
135 </programlisting>
136
133 <para> 137 <para>
134 The default <glossterm><link linkend='var-PREFERRED_PROVIDER'> 138 The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>
135 PREFERRED_PROVIDER</link></glossterm> is the provider with the same name as 139 is the provider with the same name as the target.
136 the target.
137 </para> 140 </para>
138 141
139 <para> 142 <para>
140 Understanding how providers are chosen is complicated by the fact 143 Understanding how providers are chosen is made complicated by the fact
141 multiple versions might be present. BitBake defaults to the highest 144 that multiple versions might exist.
142 version of a provider by default. Version comparisons are made using 145 BitBake defaults to the highest version of a provider.
143 the same method as Debian. The <glossterm><link 146 Version comparisons are made using the same method as Debian.
144 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> 147 You can use the <glossterm><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm>
145 variable can be used to specify a particular version 148 variable to specify a particular version (usually in the distro configuration).
146 (usually in the distro configuration) but the order can 149 You can influence the order by using the
147 also be influenced by the <glossterm><link 150 <glossterm><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
148 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 151 variable.
149 variable. By default files 152 By default, files have a preference of "0".
150 have a preference of "0". Setting the 153 Setting the DEFAULT_PREFERENCE to "-1" makes the package unlikely to be used unless it is
151 <glossterm><link 154 explicitly referenced.
152 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> to "-1" will 155 Setting the DEFAULT_PREFERENCE to "1" makes it likely the package is used.
153 make a package unlikely to be used unless it was explicitly referenced and 156 PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting.
154 "1" makes it likely the package will be used. 157 DEFAULT_PREFERENCE is often used to mark newer and more experimental package
155 <glossterm><link 158 versions until they have undergone sufficient testing to be considered stable.
156 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides
157 any <glossterm><link
158 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
159 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
160 is often used to mark more
161 experimental new versions of packages until they've undergone sufficient
162 testing to be considered stable.
163 </para> 159 </para>
164 160
165 <para> 161 <para>
166 The end result is that internally, BitBake has now built a list of 162 In summary, BitBake has created a list of providers, which is prioritized, for each target.
167 providers for each target it needs in order of priority.
168 </para> 163 </para>
169 </section> 164 </section>
170 165
@@ -172,18 +167,20 @@
172 <title>Dependencies</title> 167 <title>Dependencies</title>
173 168
174 <para> 169 <para>
175 Each target BitBake builds consists of multiple tasks (e.g. fetch, 170 Each target BitBake builds consists of multiple tasks such as fetch, unpack, patch, configure,
176 unpack, patch, configure, compile etc.). For best performance on 171 and compile.
177 multi-core systems, BitBake considers each task as an independent 172 For best performance on multi-core systems, BitBake considers each task as an independent
178 entity with a set of dependencies. There are many variables that 173 entity with its own set of dependencies.
179 are used to signify these dependencies and more information can be found 174 </para>
180 about these in the <ulink url='http://bitbake.berlios.de/manual/'> 175
181 BitBake manual</ulink>. At a basic level it is sufficient to know 176 <para>
182 that BitBake uses the <glossterm><link 177 Dependencies are defined through several variables.
183 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and 178 You can find information about variables BitBake uses in the
184 <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when 179 <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
185 calculating dependencies and descriptions of these variables are 180 At a basic level it is sufficient to know that BitBake uses the
186 available through the links. 181 <glossterm><link linkend='var-DEPENDS'>DEPENDS</link></glossterm> and
182 <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when
183 calculating dependencies.
187 </para> 184 </para>
188 185
189 </section> 186 </section>
@@ -193,69 +190,75 @@
193 190
194 <para> 191 <para>
195 Based on the generated list of providers and the dependency information, 192 Based on the generated list of providers and the dependency information,
196 BitBake can now calculate exactly which tasks it needs to run and in what 193 BitBake can now calculate exactly what tasks it needs to run and in what
197 order. The build now starts with BitBake forking off threads up to 194 order it needs to run them.
198 the limit set in the <glossterm><link 195 The build now starts with BitBake forking off threads up to the limit set in the
199 linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable 196 <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable.
200 as long as there are tasks ready to run, i.e. tasks with all their 197 BitBake continues to fork threads as long as there are tasks ready to run,
201 dependencies met. 198 those taksks have all their dependencies met, and the thread threshold has not been
199 exceeded.
202 </para> 200 </para>
203 201
204 <para> 202 <para>
205 As each task completes, a timestamp is written to the directory 203 As each task completes, a timestamp is written to the directory specified by the
206 specified by the <glossterm><link 204 <glossterm><link linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually
207 linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually 205 <filename class="directory">build/tmp/stamps/*/</filename>).
208 <filename class="directory">build/tmp/stamps/*/</filename>). On 206 On subsequent runs, BitBake looks at the STAMPS directory and does not rerun
209 subsequent runs, BitBake looks at the <glossterm><link 207 tasks that are already completed unless a timestamp is found to be invalid.
210 linkend='var-STAMPS'>STAMPS</link></glossterm> 208 Currently, invalid timestamps are only considered on a per
211 directory and will not rerun 209 <filename class="extension">.bb</filename> file basis.
212 tasks its already completed unless a timestamp is found to be invalid. 210 So, for example, if the configure stamp has a timestamp greater than the
213 Currently, invalid timestamps are only considered on a per <filename 211 compile timestamp for a given target then the compile task would rerun.
214 class="extension">.bb</filename> file basis so if for example the configure stamp has a timestamp greater than the 212 Running the compile task again, however, has no effect on other providers
215 compile timestamp for a given target the compile task would rerun but this 213 that depend on that target.
216 has no effect on other providers depending on that target. This could 214 This behavior could change or become configurable in future versions of BitBake.
217 change or become configurable in future versions of BitBake. Some tasks
218 are marked as "nostamp" tasks which means no timestamp file will be written
219 and the task will always rerun.
220 </para> 215 </para>
221 216
222 <para>Once all the tasks have been completed BitBake exits.</para> 217 <note><para>
223 218 Some tasks are marked as "nostamp" tasks.
219 No timestamp file is created when these tasks are run.
220 Consequently, "nostamp" tasks are always rerun.
221 </para></note>
224 </section> 222 </section>
225 223
226 <section id='ref-bitbake-runtask'> 224 <section id='ref-bitbake-runtask'>
227 <title>Running a Task</title> 225 <title>Running a Task</title>
228 226
229 <para> 227 <para>
230 It's worth noting what BitBake does to run a task. A task can either 228 Tasks can either be a shell task or a python task.
231 be a shell task or a python task. For shell tasks, BitBake writes a 229 For shell tasks, BitBake writes a shell script to
232 shell script to <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> 230 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
233 and then executes the script. The generated 231 The generated shell script contains all the exported variables, and the shell functions
234 shell script contains all the exported variables, and the shell functions 232 with all variables expanded.
235 with all variables expanded. Output from the shell script is 233 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
236 sent to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. 234 Looking at the expanded shell functions in the run file and the output in the log files
237 Looking at the
238 expanded shell functions in the run file and the output in the log files
239 is a useful debugging technique. 235 is a useful debugging technique.
240 </para> 236 </para>
241 237
242 <para> 238 <para>
243 Python functions are executed internally to BitBake itself and 239 For Python tasks, BitBake executes the task internally and logs information to the
244 logging goes to the controlling terminal. Future versions of BitBake will 240 controlling terminal.
245 write the functions to files in a similar way to shell functions and 241 Future versions of BitBake will write the functions to files similar to the way
246 logging will also go to the log files in a similar way. 242 shell tasks are handled.
243 Logging will be handled in way similar to shell tasks as well.
247 </para> 244 </para>
245
246 <para>
247 Once all the tasks have been completed BitBake exits.
248 </para>
248 </section> 249 </section>
249 250
250 251
251 <section id='ref-bitbake-commandline'> 252 <section id='ref-bitbake-commandline'>
252 <title>Commandline</title> 253 <title>BitBake Command Line</title>
253 254
254 <para> 255 <para>
255 To quote from "bitbake --help": 256 Following is the bitbake manpage:
256 </para> 257 </para>
257 258
258 <screen>Usage: bitbake [options] [package ...] 259 <screen>
260$ bitbake --help
261Usage: bitbake [options] [package ...]
259 262
260Executes the specified task (default is 'build') for a given set of BitBake files. 263Executes the specified task (default is 'build') for a given set of BitBake files.
261It expects that BBFILES is defined, which is a space separated list of files to 264It expects that BBFILES is defined, which is a space separated list of files to
@@ -275,6 +278,8 @@ Options:
275 -a, --tryaltconfigs continue with builds by trying to use alternative 278 -a, --tryaltconfigs continue with builds by trying to use alternative
276 providers where possible. 279 providers where possible.
277 -f, --force force run of specified cmd, regardless of stamp status 280 -f, --force force run of specified cmd, regardless of stamp status
281 -i, --interactive drop into the interactive mode also called the BitBake
282 shell.
278 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes 283 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
279 the specified task for the providee and the packages 284 the specified task for the providee and the packages
280 it depends on, i.e. 'compile' does not implicitly call 285 it depends on, i.e. 'compile' does not implicitly call
@@ -287,9 +292,6 @@ Options:
287 -D, --debug Increase the debug level. You can specify this more 292 -D, --debug Increase the debug level. You can specify this more
288 than once. 293 than once.
289 -n, --dry-run don't execute, just go through the motions 294 -n, --dry-run don't execute, just go through the motions
290 -S, --dump-signatures
291 don't execute, just dump out the signature
292 construction information
293 -p, --parse-only quit after parsing the BB files (developers only) 295 -p, --parse-only quit after parsing the BB files (developers only)
294 -d, --disable-psyco disable using the psyco just-in-time compiler (not 296 -d, --disable-psyco disable using the psyco just-in-time compiler (not
295 recommended) 297 recommended)
@@ -298,46 +300,45 @@ Options:
298 what used to be bbread) 300 what used to be bbread)
299 -g, --graphviz emit the dependency trees of the specified packages in 301 -g, --graphviz emit the dependency trees of the specified packages in
300 the dot syntax 302 the dot syntax
301 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED 303 -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
302 Assume these dependencies don't exist and are already 304 Stop processing at the given list of dependencies when
303 provided (equivalent to ASSUME_PROVIDED). Useful to 305 generating dependency graphs. This can help to make
304 make dependency graphs more appealing 306 the graph more appealing
305 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS 307 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
306 Show debug logging for the specified logging domains 308 Show debug logging for the specified logging domains
307 -P, --profile profile the command and print a report 309 -P, --profile profile the command and print a report
308 -u UI, --ui=UI userinterface to use 310 </screen>
309 --revisions-changed Set the exit code depending on whether upstream
310 floating revisions have changed or not</screen>
311
312 </section> 311 </section>
313 312
314 <section id='ref-bitbake-fetchers'> 313 <section id='ref-bitbake-fetchers'>
315 <title>Fetchers</title> 314 <title>Fetchers</title>
316 315
317 <para> 316 <para>
318 As well as the containing the parsing and task/dependency handling 317 BitBake also contains a set of "fetcher" modules that allow
319 code, BitBake also contains a set of "fetcher" modules which allow 318 retrieval of source code from various types of sources.
320 fetching of source code from various types of sources. Example 319 For example, BitBake can get source code from a disk with the metadata, from websites,
321 sources might be from disk with the metadata, from websites, from 320 from remote shell accounts or from Source Code Management (SCM) systems
322 remote shell accounts or from SCM systems like cvs/subversion/git. 321 like <filename>cvs/subversion/git</filename>.
323 </para> 322 </para>
324 323
325 <para> 324 <para>
326 The fetchers are usually triggered by entries in 325 Fetchers are usually triggered by entries in
327 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. Information about the 326 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
328 options and formats of entries for specific fetchers can be found in the 327 You can find information about the options and formats of entries for specific
329 <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>. 328 fetchers in the <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
330 </para> 329 </para>
331 330
332 <para> 331 <para>
333 One useful feature for certain SCM fetchers is the ability to 332 One useful feature for certain SCM fetchers is the ability to
334 "auto-update" when the upstream SCM changes version. Since this 333 "auto-update" when the upstream SCM changes version.
335 requires certain functionality from the SCM only certain systems 334 Since this ability requires certain functionality from the SCM, not all
336 support it, currently Subversion, Bazaar and to a limited extent, Git. It 335 systems support it.
337 works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link> 336 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
338 </glossterm> variable. See the <link linkend='platdev-appdev-srcrev'> 337 This feature works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link></glossterm>
339 developing with an external SCM based project</link> section for more 338 variable.
340 information. 339 See the
340 <link linkend='platdev-appdev-srcrev'>Developing within Poky with an External SCM-based Package</link>
341 section for more information.
341 </para> 342 </para>
342 343
343 </section> 344 </section>