summaryrefslogtreecommitdiff
path: root/bitbake/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/manual')
-rw-r--r--bitbake/doc/manual/Makefile56
-rw-r--r--bitbake/doc/manual/html.css281
-rw-r--r--bitbake/doc/manual/usermanual.xml466
3 files changed, 0 insertions, 803 deletions
diff --git a/bitbake/doc/manual/Makefile b/bitbake/doc/manual/Makefile
deleted file mode 100644
index a43c025455..0000000000
--- a/bitbake/doc/manual/Makefile
+++ /dev/null
@@ -1,56 +0,0 @@
-topdir = .
-manual = $(topdir)/usermanual.xml
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(xmltotypes) $(htmltypes)
-xmltotypes = pdf txt
-htmltypes = html xhtml
-htmlxsl = $(if $(filter $@,$(foreach type,$(htmltypes),$(type)-nochunks)),http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl,http://docbook.sourceforge.net/release/xsl/current/$@/chunk.xsl)
-htmlcssfile = docbook.css
-htmlcss = $(topdir)/html.css
-# htmlcssfile =
-# htmlcss =
-cleanfiles = $(foreach i,$(types),$(topdir)/$(i))
-
-ifdef DEBUG
-define command
- $(1)
-endef
-else
-define command
- @echo $(2) $(3) $(4)
- @$(1) >/dev/null
-endef
-endif
-
-all: $(types)
-
-lint: $(manual) FORCE
- $(call command,xmllint --xinclude --postvalid --noout $(manual),XMLLINT $(manual))
-
-$(types) $(foreach type,$(htmltypes),$(type)-nochunks): lint FORCE
-
-$(foreach type,$(htmltypes),$(type)-nochunks): $(if $(htmlcss),$(htmlcss)) $(manual)
- @mkdir -p $@
-ifdef htmlcss
- $(call command,install -m 0644 $(htmlcss) $@/$(htmlcssfile),CP $(htmlcss) $@/$(htmlcssfile))
-endif
- $(call command,xsltproc --stringparam base.dir $@/ $(if $(htmlcssfile),--stringparam html.stylesheet $(htmlcssfile)) $(htmlxsl) $(manual) > $@/index.$(patsubst %-nochunks,%,$@),XSLTPROC $@ $(manual))
-
-$(htmltypes): $(if $(htmlcss),$(htmlcss)) $(manual)
- @mkdir -p $@
-ifdef htmlcss
- $(call command,install -m 0644 $(htmlcss) $@/$(htmlcssfile),CP $(htmlcss) $@/$(htmlcssfile))
-endif
- $(call command,xsltproc --stringparam base.dir $@/ $(if $(htmlcssfile),--stringparam html.stylesheet $(htmlcssfile)) $(htmlxsl) $(manual),XSLTPROC $@ $(manual))
-
-$(xmltotypes): $(manual)
- $(call command,xmlto --extensions -o $(topdir)/$@ $@ $(manual),XMLTO $@ $(manual))
-
-clean:
- rm -rf $(cleanfiles)
-
-$(foreach i,$(types) $(foreach type,$(htmltypes),$(type)-nochunks),clean-$(i)):
- rm -rf $(patsubst clean-%,%,$@)
-
-FORCE:
diff --git a/bitbake/doc/manual/html.css b/bitbake/doc/manual/html.css
deleted file mode 100644
index 6eedfd3189..0000000000
--- a/bitbake/doc/manual/html.css
+++ /dev/null
@@ -1,281 +0,0 @@
-/* Feuille de style DocBook du projet Traduc.org */
-/* DocBook CSS stylesheet of the Traduc.org project */
-
-/* (c) Jean-Philippe Guérard - 14 août 2004 */
-/* (c) Jean-Philippe Guérard - 14 August 2004 */
-
-/* Cette feuille de style est libre, vous pouvez la */
-/* redistribuer et la modifier selon les termes de la Licence */
-/* Art Libre. Vous trouverez un exemplaire de cette Licence sur */
-/* http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
-
-/* This work of art is free, you can redistribute it and/or */
-/* modify it according to terms of the Free Art license. You */
-/* will find a specimen of this license on the Copyleft */
-/* Attitude web site: http://artlibre.org as well as on other */
-/* sites. */
-/* Please note that the French version of this licence as shown */
-/* on http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
-/* is only official licence of this document. The English */
-/* is only provided to help you understand this licence. */
-
-/* La dernière version de cette feuille de style est toujours */
-/* disponible sur : http://tigreraye.org/style.css */
-/* Elle est également disponible sur : */
-/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
-
-/* The latest version of this stylesheet is available from: */
-/* http://tigreraye.org/style.css */
-/* It is also available on: */
-/* http://www.traduc.org/docs/HOWTO/lecture/style.css */
-
-/* N'hésitez pas à envoyer vos commentaires et corrections à */
-/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
-
-/* Please send feedback and bug reports to */
-/* Jean-Philippe Guérard <jean-philippe.guerard@tigreraye.org> */
-
-/* $Id: style.css,v 1.14 2004/09/10 20:12:09 fevrier Exp fevrier $ */
-
-/* Présentation générale du document */
-/* Overall document presentation */
-
-body {
- /*
- font-family: Apolline, "URW Palladio L", Garamond, jGaramond,
- "Bitstream Cyberbit", "Palatino Linotype", serif;
- */
- margin: 7%;
- background-color: white;
-}
-
-/* Taille du texte */
-/* Text size */
-
-* { font-size: 100%; }
-
-/* Gestion des textes mis en relief imbriqués */
-/* Embedded emphasis */
-
-em { font-style: italic; }
-em em { font-style: normal; }
-em em em { font-style: italic; }
-
-/* Titres */
-/* Titles */
-
-h1 { font-size: 200%; font-weight: 900; }
-h2 { font-size: 160%; font-weight: 900; }
-h3 { font-size: 130%; font-weight: bold; }
-h4 { font-size: 115%; font-weight: bold; }
-h5 { font-size: 108%; font-weight: bold; }
-h6 { font-weight: bold; }
-
-/* Nom de famille en petites majuscules (uniquement en français) */
-/* Last names in small caps (for French only) */
-
-*[class~="surname"]:lang(fr) { font-variant: small-caps; }
-
-/* Blocs de citation */
-/* Quotation blocs */
-
-div[class~="blockquote"] {
- border: solid 2px #AAA;
- padding: 5px;
- margin: 5px;
-}
-
-div[class~="blockquote"] > table {
- border: none;
-}
-
-/* Blocs litéraux : fond gris clair */
-/* Literal blocs: light gray background */
-
-*[class~="literallayout"] {
- background: #f0f0f0;
- padding: 5px;
- margin: 5px;
-}
-
-/* Programmes et captures texte : fond bleu clair */
-/* Listing and text screen snapshots: light blue background */
-
-*[class~="programlisting"], *[class~="screen"] {
- background: #f0f0ff;
- padding: 5px;
- margin: 5px;
-}
-
-/* Les textes à remplacer sont surlignés en vert pâle */
-/* Replaceable text in highlighted in pale green */
-
-*[class~="replaceable"] {
- background-color: #98fb98;
- font-style: normal; }
-
-/* Tables : fonds gris clair & bords simples */
-/* Tables: light gray background and solid borders */
-
-*[class~="table"] *[class~="title"] { width:100%; border: 0px; }
-
-table {
- border: 1px solid #aaa;
- border-collapse: collapse;
- padding: 2px;
- margin: 5px;
-}
-
-/* Listes simples en style table */
-/* Simples lists in table presentation */
-
-table[class~="simplelist"] {
- background-color: #F0F0F0;
- margin: 5px;
- border: solid 1px #AAA;
-}
-
-table[class~="simplelist"] td {
- border: solid 1px #AAA;
-}
-
-/* Les tables */
-/* Tables */
-
-*[class~="table"] table {
- background-color: #F0F0F0;
- border: solid 1px #AAA;
-}
-*[class~="informaltable"] table { background-color: #F0F0F0; }
-
-th,td {
- vertical-align: baseline;
- text-align: left;
- padding: 0.1em 0.3em;
- empty-cells: show;
-}
-
-/* Alignement des colonnes */
-/* Colunms alignment */
-
-td[align=center] , th[align=center] { text-align: center; }
-td[align=right] , th[align=right] { text-align: right; }
-td[align=left] , th[align=left] { text-align: left; }
-td[align=justify] , th[align=justify] { text-align: justify; }
-
-/* Pas de marge autour des images */
-/* No inside margins for images */
-
-img { border: 0; }
-
-/* Les liens ne sont pas soulignés */
-/* No underlines for links */
-
-:link , :visited , :active { text-decoration: none; }
-
-/* Prudence : cadre jaune et fond jaune clair */
-/* Caution: yellow border and light yellow background */
-
-*[class~="caution"] {
- border: solid 2px yellow;
- background-color: #ffffe0;
- padding: 1em 6px 1em ;
- margin: 5px;
-}
-
-*[class~="caution"] th {
- vertical-align: middle
-}
-
-*[class~="caution"] table {
- background-color: #ffffe0;
- border: none;
-}
-
-/* Note importante : cadre jaune et fond jaune clair */
-/* Important: yellow border and light yellow background */
-
-*[class~="important"] {
- border: solid 2px yellow;
- background-color: #ffffe0;
- padding: 1em 6px 1em;
- margin: 5px;
-}
-
-*[class~="important"] th {
- vertical-align: middle
-}
-
-*[class~="important"] table {
- background-color: #ffffe0;
- border: none;
-}
-
-/* Mise en évidence : texte légèrement plus grand */
-/* Highlights: slightly larger texts */
-
-*[class~="highlights"] {
- font-size: 110%;
-}
-
-/* Note : cadre bleu et fond bleu clair */
-/* Notes: blue border and light blue background */
-
-*[class~="note"] {
- border: solid 2px #7099C5;
- background-color: #f0f0ff;
- padding: 1em 6px 1em ;
- margin: 5px;
-}
-
-*[class~="note"] th {
- vertical-align: middle
-}
-
-*[class~="note"] table {
- background-color: #f0f0ff;
- border: none;
-}
-
-/* Astuce : cadre vert et fond vert clair */
-/* Tip: green border and light green background */
-
-*[class~="tip"] {
- border: solid 2px #00ff00;
- background-color: #f0ffff;
- padding: 1em 6px 1em ;
- margin: 5px;
-}
-
-*[class~="tip"] th {
- vertical-align: middle;
-}
-
-*[class~="tip"] table {
- background-color: #f0ffff;
- border: none;
-}
-
-/* Avertissement : cadre rouge et fond rouge clair */
-/* Warning: red border and light red background */
-
-*[class~="warning"] {
- border: solid 2px #ff0000;
- background-color: #fff0f0;
- padding: 1em 6px 1em ;
- margin: 5px;
-}
-
-*[class~="warning"] th {
- vertical-align: middle;
-}
-
-
-*[class~="warning"] table {
- background-color: #fff0f0;
- border: none;
-}
-
-/* Fin */
-/* The End */
-
diff --git a/bitbake/doc/manual/usermanual.xml b/bitbake/doc/manual/usermanual.xml
deleted file mode 100644
index 4db452747d..0000000000
--- a/bitbake/doc/manual/usermanual.xml
+++ /dev/null
@@ -1,466 +0,0 @@
-<?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, 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.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>
- <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>Appending (.=) and prepending (=.) without spaces</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>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>
- <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>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>
- <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, True):
- 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 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
- from bb import data
-
- print "The name of the Event is %s" % getName(e)
- 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
-of the event and the content of the <varname>FILE</varname> variable.</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>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 (the special value of "now" will cause the checkout to be updated on every build), <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. The special value of "now" will cause the checkout to be updated on every build.<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 supported</emphasis>
- </para>
- </section>
-
- <section>
- <title>SVN Fetcher</title>
- <para>The URN for the SVN Fetcher is <emphasis>svn</emphasis>.
- </para>
- <para>This Fetcher honors the variables <varname>FETCHCOMMAND_svn</varname>, <varname>DL_DIR</varname>, <varname>SRCDATE</varname>. <varname>FETCHCOMMAND</varname> contains the subversion command, <varname>DL_DIR</varname> is the directory where tarballs will be saved, <varname>SRCDATE</varname> specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build).
- </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>
- <section>
- <title>Introduction</title>
- <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>
- </section>
- <section>
- <title>Usage and Syntax</title>
- <para>
- <screen><prompt>$ </prompt>bitbake --help
-usage: bitbake [options] [package ...]
-
-Executes the specified task (default is 'build') for a given set of BitBake files.
-It expects that BBFILES is defined, which is a space seperated list of files to
-be executed. BBFILES does support wildcards.
-Default BBFILES are the .bb files in the current directory.
-
-options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -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.
- -f, --force force run of specified cmd, regardless of stamp status
- -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
- listtasks 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. 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
- -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>
- <title>Executing a task against a single .bb</title>
- <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>
- <para><quote>clean</quote> task:</para>
- <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb -c clean</screen></para>
- <para><quote>build</quote> task:</para>
- <para><screen><prompt>$ </prompt>bitbake -b blah_1.0.bb</screen></para>
- </example>
- </para>
- <para>
- <example>
- <title>Executing tasks against a set