diff options
Diffstat (limited to 'doc/manual/usermanual.xml')
| -rw-r--r-- | doc/manual/usermanual.xml | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/doc/manual/usermanual.xml b/doc/manual/usermanual.xml new file mode 100644 index 000000000..d47d5ded6 --- /dev/null +++ b/doc/manual/usermanual.xml @@ -0,0 +1,222 @@ +<?xml version="1.0"?> +<!-- + ex:ts=4:sw=4:sts=4:et + -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<book> + <bookinfo> + <title>BitBake User Manual</title> + <authorgroup> + <corpauthor>BitBake Team</corpauthor> + </authorgroup> + <copyright> + <year>2004</year> + <holder>Chris Larson</holder> + <holder>Phil Blundell</holder> + </copyright> + <legalnotice> + <para>This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <ulink url="http://creativecommons.org/licenses/by/2.0/">http://creativecommons.org/licenses/by/2.0/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para> + </legalnotice> + </bookinfo> + <chapter> + <title>Introduction</title> + <section> + <title>Overview</title> + <para>BitBake is, at its simplest, a tool for executing +tasks and managing metadata. As such, its similarities to GNU make and other +build tools are readily apparent. It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink> project, which is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus and Familiar.</para> + </section> + <section> + <title>Background and Goals</title> + <para>Prior to BitBake, no other build tool adequately met +the needs of an aspiring embedded Linux distribution. All of the +buildsystems used by traditional desktop Linux distributions lacked +important functionality, and none of the ad-hoc +<emphasis>buildroot</emphasis> systems, prevalent in the +embedded space, were scalable or maintainable.</para> + + <para>Some important goals for BitBake were: + <itemizedlist> + <listitem><para>Handle crosscompilation.</para></listitem> + <listitem><para>Handle interpackage dependencies (build time on target architecture, build time on native architecture, and runtime).</para></listitem> + <listitem><para>Support running any number of tasks within a given package, including, but not limited to, fetching upstream sources, unpacking them, patching them, configuring them, et cetera.</para></listitem> + <listitem><para>Must be linux distribution agnostic (both build and target).</para></listitem> + <listitem><para>Must be architecture agnostic</para></listitem> + <listitem><para>Must support multiple build and target operating systems (including cygwin, the BSDs, etc).</para></listitem> + <listitem><para>Must be able to be self contained, rather than tightly integrated into the build machine's root filesystem.</para></listitem> + <listitem><para>There must be a way to handle conditional metadata (on target architecture, operating system, distribution, machine).</para></listitem> + <listitem><para>It must be easy for the person using the tools to supply their own local metadata and packages to operate against.</para></listitem> + <listitem><para>Must make it easy to collaborate +between multiple projects using BitBake for their +builds.</para></listitem> + <listitem><para>Should provide an inheritance mechanism to +share common metadata between many packages.</para></listitem> + <listitem><para>Et cetera...</para></listitem> + </itemizedlist> + </para> + <para>BitBake satisfies all these and many more. Flexibility and power have always been the priorities. It is highly extensible, supporting embedded Python code and execution of any arbitrary tasks.</para> + </section> + </chapter> + <chapter> + <title>Metadata</title> + <section> + <title>Description</title> + <itemizedlist> + <para>BitBake metadata can be classified into 3 major areas:</para> + <listitem> + <para>Configuration Files</para> + </listitem> + <listitem> + <para>.bb Files</para> + </listitem> + <listitem> + <para>Classes</para> + </listitem> + </itemizedlist> + <para>What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported in any of the aforementioned areas will be documented as such.</para> + <section> + <title>Basic variable setting</title> + <para><screen><varname>VARIABLE</varname> = "value"</screen></para> + <para>In this example, <varname>VARIABLE</varname> is <literal>value</literal>.</para> + </section> + <section> + <title>Variable expansion</title> + <para>BitBake supports variables referencing one another's contents using a syntax which is similar to shell scripting</para> + <para><screen><varname>A</varname> = "aval" +<varname>B</varname> = "pre${A}post"</screen></para> + <para>This results in <varname>A</varname> containing <literal>aval</literal> and <varname>B</varname> containing <literal>preavalpost</literal>.</para> + </section> + <section> + <title>Immediate variable expansion (:=)</title> + <para>:= results in a variable's contents being expanded immediately, rather than when the variable is actually used.</para> + <para><screen><varname>T</varname> = "123" +<varname>A</varname> := "${B} ${A} test ${T}" +<varname>T</varname> = "456" +<varname>B</varname> = "${T} bval" + +<varname>C</varname> = "cval" +<varname>C</varname> := "${C}append"</screen></para> + <para>In that example, <varname>A</varname> would contain <literal> test 123</literal>, <varname>B</varname> would contain <literal>456 bval</literal>, and <varname>C</varname> would be <literal>cvalappend</literal>.</para> + </section> + <section> + <title>Appending (+=) and prepending (=+)</title> + <para><screen><varname>B</varname> = "bval" +<varname>B</varname> += "additionaldata" +<varname>C</varname> = "cval" +<varname>C</varname> =+ "test"</screen></para> + <para>In this example, <varname>B</varname> is now <literal>bval additionaldata</literal> and <varname>C</varname> is <literal>test cval</literal>.</para> + </section> + <section> + <title>Conditional metadata set</title> + <para>OVERRIDES is a <quote>:</quote> seperated variable containing each item you want to satisfy conditions. So, if you have a variable which is conditional on <quote>arm</quote>, and <quote>arm</quote> is in OVERRIDES, then the <quote>arm</quote> specific version of the variable is used rather than the non-conditional version. Example:</para> + <para><screen><varname>OVERRIDES</varname> = "architecture:os:machine" +<varname>TEST</varname> = "defaultvalue" +<varname>TEST_os</varname> = "osspecificvalue" +<varname>TEST_condnotinoverrides</varname> = "othercondvalue"</screen></para> + <para>In this example, <varname>TEST</varname> would be <literal>osspecificvalue</literal>, due to the condition <quote>os</quote> being in <varname>OVERRIDES</varname>.</para> + </section> + <section> + <title>Conditional appending</title> + <para>BitBake also supports appending and prepending to variables based on whether something is in OVERRIDES. Example:</para> + <para><screen><varname>DEPENDS</varname> = "glibc ncurses" +<varname>OVERRIDES</varname> = "machine:local" +<varname>DEPENDS_append_machine</varname> = " libmad"</screen></para> + <para>In this example, <varname>DEPENDS</varname> is set to <literal>glibc ncurses libmad</literal>.</para> + </section> + <section> + <title>Inclusion</title> + <para>Next, there is the <literal>include</literal> directive, which causes BitBake to parse in whatever file you specify, and insert it at that location, which is not unlike <command>make</command>. However, if the path specified on the <literal>include</literal> line is a relative path, BitBake will locate the first one it can find within <envar>BBPATH</envar>.</para> + </section> + <section> + <title>Python variable expansion</title> + <para><screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen></para> + <para>This would result in the <varname>DATE</varname> variable containing today's date.</para> + </section> + <section> + <title>Defining executable metadata</title> + <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> + <para><screen>do_mytask () { + echo "Hello, world!" +}</screen></para> + <para>This is essentially identical to setting a variable, except that this variable happens to be executable shell code.</para> + <para><screen>python do_printdate () { + import time + print time.strftime('%Y%m%d', time.gmtime()) +}</screen></para> + <para>This is the similar to the previous, but flags it as python so that BitBake knows it is python code.</para> + </section> + <section> + <title>Defining python functions into the global python namespace</title> + <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> + <para><screen>def get_depends(bb, d): + if bb.data.getVar('SOMECONDITION', d, 1): + return "dependencywithcond" + else: + return "dependency" + +<varname>SOMECONDITION</varname> = "1" +<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen></para> + <para>This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.</para> + </section> + <section> + <title>Inheritance</title> + <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> + <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> + </section> + <section> + <title>Tasks</title> + <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> + <para>In BitBake, each step that needs to be run for a given .bb is known as a task. There is a command <literal>addtask</literal> to add new tasks (must be a defined python executable metadata and must start with <quote>do_</quote>) and describe intertask dependencies.</para> + <para><screen>python do_printdate () { + import time + print time.strftime('%Y%m%d', time.gmtime()) +} + +addtask printdate before do_build</screen></para> + <para>This defines the necessary python function and adds it as a task which is now a dependency of do_build (the default task). If anyone executes the do_build task, that will result in do_printdate being run first.</para> + </section> + <section> + <title>Events</title> + <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para> + <para>BitBake also implements a means of registering event handlers. Events are triggered at certain points during operation, such as, the beginning of operation against a given .bb, the start of a given task, task failure, task success, et cetera. The intent was to make it easy to do things like email notifications on build failure.</para> + <para><emphasis>[Insert instructions on how to add event handlers here]</emphasis></para> + </section> + </section> + <section> + <title>Parsing</title> + <section> + <title>Configuration Files</title> + <para>The first of the classifications of metadata in BitBake is configuration metadata. This metadata is global, and therefore affects <emphasis>all</emphasis> packages and tasks which are executed. Currently, BitBake has hardcoded knowledge of a single configuration file. It expects to find 'conf/bitbake.conf' somewhere in the user specified <envar>BBPATH</envar>. That configuration file generally has include directives to pull in any other metadata (generally files specific to architecture, machine, <emphasis>local</emphasis> and so on.</para> + <para>Only variable definitions and include directives are allowed in .conf files.</para> + </section> + <section> + <title>Classes</title> + <para>BitBake classes are our rudamentary inheritence mechanism. As briefly mentioned in the metadata introduction, they're parsed when an <literal>inherit</literal> directive is encountered, and they are located in classes/ relative to the dirs in <envar>BBPATH</envar>.</para> + </section> + <section> + <title>.bb Files</title> + <para>A BitBake (.bb) file is a logical unit of tasks to be executed. Normally this is a package to be built. Inter-.bb dependencies are obeyed. The files themselves are located via the <varname>BBFILES</varname> variable, which is set to a space seperated list of .bb files, and does handle wildcards.</para> + </section> + </section> + </chapter> + <chapter> + <title>Commands</title> + <section> + <title>bbread</title> + <para>test</para> + </section> + <section> + <title>bbmake</title> + <para>test</para> + </section> + </chapter> + <appendix> + <title>Reference</title> + <section> + <title>Required Metadata</title> + <para>test</para> + </section> + </appendix> +</book> |