<corpauthor>BitBake Team</corpauthor>
</authorgroup>
<copyright>
- <year>2004, 2005</year>
+ <year>2004, 2005, 2006</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>
+ <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.5/">http://creativecommons.org/licenses/by/2.5/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
</legalnotice>
</bookinfo>
<chapter>
<section>
<title>Appending (.=) and prepending (=.) without spaces</title>
<para><screen><varname>B</varname> = "bval"
-<varname>B</varname> += "additionaldata"
+<varname>B</varname> .= "additionaldata"
<varname>C</varname> = "cval"
-<varname>C</varname> =+ "test"</screen></para>
+<varname>C</varname> =. "test"</screen></para>
<para>In this example, <varname>B</varname> is now <literal>bvaladditionaldata</literal> and <varname>C</varname> is <literal>testcval</literal>. In contrast to the above Appending and Prepending operators no additional space
will be introduced.</para>
</section>
<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>Requiring Inclusion</title>
+ <para>In contrast to the <literal>include</literal> directive, <literal>require</literal> will
+raise an ParseError if the to be included file can not be found. Otherwise it will behave just like the <literal>
+include</literal> directive.</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>
<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>BitBake allows to install 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><screen>addhandler myclass_eventhandler
python myclass_eventhandler() {
from bb.event import NotHandled, getName
print "The file we run for is %s" % data.getVar('FILE', e.data, True)
return NotHandled
+}
</screen></para><para>
This event handler gets called every time an event is triggered. A global variable <varname>e</varname> is defined. <varname>e</varname>.data contains an instance of bb.data. With the getName(<varname>e</varname>)
method one can get the name of the triggered event.</para><para>The above event handler prints the name
</section>
</section>
</chapter>
+
+ <chapter>
+ <title>File Download support</title>
+ <section>
+ <title>Overview</title>
+ <para>BitBake provides support to download files this procedure is called fetching. The SRC_URI is normally used to indicate BitBake which files to fetch. The next sections will describe th available fetchers and the options they have. Each Fetcher honors a set of Variables and
+a per URI parameters separated by a <quote>;</quote> consisting of a key and a value. The semantic of the Variables and Parameters are defined by the Fetcher. BitBakes tries to have a consistent semantic between the different Fetchers.
+ </para>
+ </section>
+
+ <section>
+ <title>Local File Fetcher</title>
+ <para>The URN for the Local File Fetcher is <emphasis>file</emphasis>. The filename can be either absolute or relative. If the filename is relative <varname>FILESPATH</varname> and <varname>FILESDIR</varname> will be used to find the appropriate relative file depending on the <varname>OVERRIDES</varname>. Single files and complete directories can be specified.
+<screen><varname>SRC_URI</varname>= "file://relativefile.patch"
+<varname>SRC_URI</varname>= "file://relativefile.patch;this=ignored"
+<varname>SRC_URI</varname>= "file:///Users/ich/very_important_software"
+</screen>
+ </para>
+ </section>
+
+ <section>
+ <title>CVS File Fetcher</title>
+ <para>The URN for the CVS Fetcher is <emphasis>cvs</emphasis>. This Fetcher honors the variables <varname>DL_DIR</varname>, <varname>SRCDATE</varname>, <varname>FETCHCOMMAND_cvs</varname>, <varname>UPDATECOMMAND_cvs</varname>. <varname>DL_DIRS</varname> specifies where a temporary checkout is saved, <varname>SRCDATE</varname> specifies which date to use when doing the fetching, <varname>FETCHCOMMAND</varname> and <varname>UPDATECOMMAND</varname> specify which executables should be used when doing the CVS checkout or update.
+ </para>
+ <para>The supported Parameters are <varname>module</varname>, <varname>tag</varname>, <varname>date</varname>, <varname>method</varname>, <varname>localdir</varname>, <varname>rsh</varname>. The <varname>module</varname> specifies which module to check out, the <varname>tag</varname> describes which CVS TAG should be used for the checkout by default the TAG is empty. A <varname>date</varname> can be specified to override the SRCDATE of the configuration to checkout a specific date. <varname>method</varname> is by default <emphasis>pserver</emphasis>, if <emphasis>ext</emphasis> is used the <varname>rsh</varname> parameter will be evaluated and <varname>CVS_RSH</varname> will be set. Finally <varname>localdir</varname> is used to checkout into a special directory relative to <varname>CVSDIR></varname>.
+<screen><varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
+<varname>SRC_URI</varname> = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
+</screen>
+ </para>
+ </section>
+
+ <section>
+ <title>HTTP/FTP Fetcher</title>
+ <para>The URNs for the HTTP/FTP are <emphasis>http</emphasis>, <emphasis>https</emphasis> and <emphasis>ftp</emphasis>. This Fetcher honors the variables <varname>DL_DIR</varname>, <varname>FETCHCOMMAND_wget</varname>, <varname>PREMIRRORS</varname>, <varname>MIRRORS</varname>. The <varname>DL_DIR</varname> defines where to store the fetched file, <varname>FETCHCOMMAND</varname> contains the command used for fetching. <quote>${URI}</quote> and <quote>${FILES}</quote> will be replaced by the uri and basename of the to be fetched file. <varname>PREMIRRORS</varname>
+will be tried first when fetching a file if that fails the actual file will be tried and finally all <varname>MIRRORS</varname> will be tried.
+ </para>
+ <para>The only supported Parameter is <varname>md5sum</varname>. After a fetch the <varname>md5sum</varname> of the file will be calculated and the two sums will be compared.
+ </para>
+ <para><screen><varname>SRC_URI</varname> = "http://oe.handhelds.org/not_there.aac;md5sum=12343"
+<varname>SRC_URI</varname> = "ftp://oe.handhelds.org/not_there_as_well.aac;md5sum=1234"
+<varname>SRC_URI</varname> = "ftp://you@oe.handheld.sorg/home/you/secret.plan;md5sum=1234"
+</screen></para>
+ </section>
+
+ <section>
+ <title>SVK Fetcher</title>
+ <para>
+ <emphasis>Currently NOT suppoered</emphasis>
+ </para>
+ </section>
+
+ <section>
+ <title>SVN Fetcher</title>
+ <para>The URN for the SVN Fetcher is <emphasis>svn</emphasis>.
+ </para>
+ <para>The Variables <varname>FETCHCOMMAND_svn</varname>, <varname>DL_DIR</varname> are used by the SVN Fetcher. <varname>FETCHCOMMAND</varname> contains the subversion command, <varname>DL_DIR</varname> is the directory where tarballs will be saved.
+ </para>
+ <para>The supported Parameters are <varname>proto</varname>, <varname>rev</varname>. <varname>proto</varname> is the subversion prototype, <varname>rev</varname> is the subversions revision.
+ </para>
+ <para><screen><varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn;module=vip;proto=http;rev=667"
+<varname>SRC_URI</varname> = "svn://svn.oe.handhelds.org/svn/;module=opie;proto=svn+ssh;date=20060126"
+</screen></para>
+ </section>
+
+ <section>
+ <title>GIT Fetcher</title>
+ <para>The URN for the GIT Fetcher is <emphasis>git</emphasis>.
+ </para>
+ <para>The Variables <varname>DL_DIR</varname>, <varname>GITDIR</varname> are used. <varname>DL_DIR</varname> will be used to store the checkedout version. <varname>GITDIR</varname> will be used as the base directory where the git tree is cloned to.
+ </para>
+ <para>The Parameters are <emphasis>tag</emphasis>, <emphasis>protocol</emphasis>. <emphasis>tag</emphasis> is a git tag, the default is <quote>master</quote>. <emphasis>protocol</emphasis> is the git protocol to use and defaults to <quote>rsync</quote>.
+ </para>
+ <para><screen><varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
+<varname>SRC_URI</varname> = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
+ </screen></para>
+ </section>
+
+ </chapter>
+
+
<chapter>
<title>Commands</title>
<section>
<title>bbread</title>
<para>bbread is a command for displaying BitBake metadata. When run with no arguments, it has the core parse 'conf/bitbake.conf', as located in BBPATH, and displays that. If you supply a file on the commandline, such as a .bb, then it parses that afterwards, using the aforementioned configuration metadata.</para>
+ <para><emphasis>NOTE: the stand a lone bbread command was removed. Instead of bbread use bitbake -e.
+ </emphasis></para>
</section>
<section>
<title>bitbake</title>
options:
--version show program's version number and exit
-h, --help show this help message and exit
- -bBUILDFILE, --buildfile=BUILDFILE
+ -b BUILDFILE, --buildfile=BUILDFILE
execute the task against this .bb file, rather than a
package from BBFILES.
-k, --continue continue as much as possible after an error. While the
- target that failed, and those that depend on it, cannot
- be remade, the other dependencies of these targets can
- be processed all the same.
+ target that failed, and those that depend on it,
+ cannot be remade, the other dependencies of these
+ targets can be processed all the same.
-f, --force force run of specified cmd, regardless of stamp status
- -cCMD, --cmd=CMD Specify task to execute
- -rFILE, --read=FILE read the specified file before bitbake.conf
+ -i, --interactive drop into the interactive mode also called the BitBake
+ shell.
+ -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
+ the specified task for the providee and the packages
+ it depends on, i.e. 'compile' does not implicitly call
+ stage for the dependencies (IOW: use only if you know
+ what you are doing). Depending on the base.bbclass a
+ listtaks tasks is defined and will show available
+ tasks
+ -r FILE, --read=FILE read the specified file before bitbake.conf
-v, --verbose output more chit-chat to the terminal
- -D, --debug Increase the debug level
+ -D, --debug Increase the debug level. You can specify this more
+ than once.
-n, --dry-run don't execute, just go through the motions
-p, --parse-only quit after parsing the BB files (developers only)
-d, --disable-psyco disable using the psyco just-in-time compiler (not
recommended)
- -s, --show-versions show current and preferred versions of all packages</screen>
+ -s, --show-versions show current and preferred versions of all packages
+ -e, --environment show the global or per-package environment (this is
+ what used to be bbread)
+ -g, --graphviz emit the dependency trees of the specified packages in
+ the dot syntax
+ -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
+ Stop processing at the given list of dependencies when
+ generating dependency graphs. This can help to make
+ the graph more appealing
+
+</screen>
</para>
<para>
<example>
<screen><prompt>$ </prompt>bitbake virtual/whatever</screen>
<screen><prompt>$ </prompt>bitbake -c clean virtual/whatever</screen>
</example>
+ <example>
+ <title>Generating dependency graphs</title>
+ <para>BitBake is able to generate dependency graphs using the dot syntax. These graphs can be converted
+to images using the <application>dot</application> application from <ulink url="http://www.graphviz.org">graphviz</ulink>.
+Three files will be written into the current working directory, <emphasis>depends.dot</emphasis> containing <varname>DEPENDS</varname> variables, <emphasis>rdepends.dot</emphasis> containing <varname>RDEPENDS</varname> and <emphasis>alldepends.dot</emphasis> containing all depends. 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.</para>
+ <screen><prompt>$ </prompt>bitbake -g blah</screen>
+ <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen>
+ </example>
</para>
</section>
<section>
<title>Depending on another .bb</title>
<para>a.bb:
<screen>PN = "package-a"
- DEPENDS += "package-b"</screen>
+DEPENDS += "package-b"</screen>
</para>
<para>b.bb:
<screen>PN = "package-b"</screen>
projects / vuplus_bitbake / blobdiff