summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/manual/usermanual.xml54
1 files changed, 53 insertions, 1 deletions
diff --git a/bitbake/doc/manual/usermanual.xml b/bitbake/doc/manual/usermanual.xml
index 4db452747d..a79716a0aa 100644
--- a/bitbake/doc/manual/usermanual.xml
+++ b/bitbake/doc/manual/usermanual.xml
@@ -176,6 +176,12 @@ include</literal> directive.</para>
176 <para>This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.</para> 176 <para>This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.</para>
177 </section> 177 </section>
178 <section> 178 <section>
179 <title>Variable Flags</title>
180 <para>Variables can have associated flags which provide a way of tagging extra information onto a variable. Several flags are used internally by bitbake but they can be used externally too if needed. The standard operations mentioned above also work on flags.</para>
181 <para><screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen></para>
182 <para>In this example, <varname>VARIABLE</varname> has a flag, <varname>SOMEFLAG</varname> which is set to <literal>value</literal>.</para>
183 </section>
184 <section>
179 <title>Inheritance</title> 185 <title>Inheritance</title>
180 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> 186 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para>
181 <para>The <literal>inherit</literal> directive is a means of specifying what classes of functionality your .bb requires. It is a rudamentary form of inheritence. For example, you can easily abstract out the tasks involved in building a package that uses autoconf and automake, and put that into a bbclass for your packages to make use of. A given bbclass is located by searching for classes/filename.oeclass in <envar>BBPATH</envar>, where filename is what you inherited.</para> 187 <para>The <literal>inherit</literal> directive is a means of specifying what classes of functionality your .bb requires. It is a rudamentary form of inheritence. For example, you can easily abstract out the tasks involved in building a package that uses autoconf and automake, and put that into a bbclass for your packages to make use of. A given bbclass is located by searching for classes/filename.oeclass in <envar>BBPATH</envar>, where filename is what you inherited.</para>
@@ -213,6 +219,42 @@ of the event and the content of the <varname>FILE</varname> variable.</para>
213 </section> 219 </section>
214 </section> 220 </section>
215 <section> 221 <section>
222 <title>Dependency Handling</title>
223 <para>Bitbake 1.7.x onwards works with the metadata at the task level since this is optimal when dealing with multiple threads of execution. A robust method of specifing task dependencies is therefore needed. </para>
224 <section>
225 <title>Dependencies internal to the .bb file</title>
226 <para>Where the dependencies are internal to a given .bb file, the dependencies are handled by the previously detailed addtask directive.</para>
227 </section>
228
229 <section>
230 <title>DEPENDS</title>
231 <para>DEPENDS is taken to specify build time dependencies. The 'deptask' flag for tasks is used to signify the task of each DEPENDS which must have completed before that task can be executed.</para>
232 <para><screen>do_configure[deptask] = "do_populate_staging"</screen></para>
233 <para>means the do_populate_staging task of each item in DEPENDS must have completed before do_configure can execute.</para>
234 </section>
235 <section>
236 <title>RDEPENDS</title>
237 <para>RDEPENDS is taken to specify runtime dependencies. The 'rdeptask' flag for tasks is used to signify the task of each RDEPENDS which must have completed before that task can be executed.</para>
238 <para><screen>do_package_write[rdeptask] = "do_package"</screen></para>
239 <para>means the do_package task of each item in RDEPENDS must have completed before do_package_write can execute.</para>
240 </section>
241 <section>
242 <title>Recursive DEPENDS</title>
243 <para>These are specified with the 'recdeptask' flag and is used signify the task(s) of each DEPENDS which must have completed before that task can be executed. It applies recursively so also, the DEPENDS of each item in the original DEPENDS must be met and so on.</para>
244 </section>
245 <section>
246 <title>Recursive RDEPENDS</title>
247 <para>These are specified with the 'recrdeptask' flag and is used signify the task(s) of each RDEPENDS which must have completed before that task can be executed. It applies recursively so also, the RDEPENDS of each item in the original RDEPENDS must be met and so on. It also runs all DEPENDS first too.</para>
248 </section>
249 <section>
250 <title>Inter Task</title>
251 <para>The 'depends' flag for tasks is a more generic form of which allows an interdependency on specific tasks rather than specifying the data in DEPENDS or RDEPENDS.</para>
252 <para><screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen></para>
253 <para>means the do_populate_staging task of the target quilt-native must have completed before the do_patch can execute.</para>
254 </section>
255 </section>
256
257 <section>
216 <title>Parsing</title> 258 <title>Parsing</title>
217 <section> 259 <section>
218 <title>Configuration Files</title> 260 <title>Configuration Files</title>
@@ -371,6 +413,8 @@ options:
371 Stop processing at the given list of dependencies when 413 Stop processing at the given list of dependencies when
372 generating dependency graphs. This can help to make 414 generating dependency graphs. This can help to make
373 the graph more appealing 415 the graph more appealing
416 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
417 Show debug logging for the specified logging domains
374 418
375</screen> 419</screen>
376 </para> 420 </para>
@@ -401,13 +445,21 @@ options:
401 <title>Generating dependency graphs</title> 445 <title>Generating dependency graphs</title>
402 <para>BitBake is able to generate dependency graphs using the dot syntax. These graphs can be converted 446 <para>BitBake is able to generate dependency graphs using the dot syntax. These graphs can be converted
403to images using the <application>dot</application> application from <ulink url="http://www.graphviz.org">graphviz</ulink>. 447to images using the <application>dot</application> application from <ulink url="http://www.graphviz.org">graphviz</ulink>.
404Three files will be written into the current working directory, <emphasis>depends.dot</emphasis> containing <varname>DEPENDS</varname> variables, <emphasis>rdepends.dot</emphasis> and <emphasis>alldepends.dot</emphasis> containing both <varname>DEPENDS</varname> and <varname>RDEPENDS</varname>. 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. E.g. this way <varname>DEPENDS</varname> from inherited classes, e.g. base.bbclass, can be removed from the graph.</para> 448Two 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. E.g. this way <varname>DEPENDS</varname> from inherited classes, e.g. base.bbclass, can be removed from the graph.</para>
405 <screen><prompt>$ </prompt>bitbake -g blah</screen> 449 <screen><prompt>$ </prompt>bitbake -g blah</screen>
406 <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen> 450 <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen>
407 </example> 451 </example>
408 </para> 452 </para>
409 </section> 453 </section>
410 <section> 454 <section>
455 <title>Special variables</title>
456 <para>Certain variables affect bitbake operation:</para>
457 <section>
458 <title><varname>BB_NUMBER_THREADS</varname></title>
459 <para> The number of threads bitbake should run at once (default: 1).</para>
460 </section>
461 </section>
462 <section>
411 <title>Metadata</title> 463 <title>Metadata</title>
412 <para>As you may have seen in the usage information, or in the information about .bb files, the BBFILES variable is how the bitbake tool locates its files. This variable is a space seperated list of files that are available, and supports wildcards. 464 <para>As you may have seen in the usage information, or in the information about .bb files, the BBFILES variable is how the bitbake tool locates its files. This variable is a space seperated list of files that are available, and supports wildcards.
413 <example> 465 <example>