aboutsummaryrefslogtreecommitdiffstats
path: root/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/Makefile49
-rw-r--r--doc/manual/html.css281
-rw-r--r--doc/manual/usermanual.xml222
3 files changed, 552 insertions, 0 deletions
diff --git a/doc/manual/Makefile b/doc/manual/Makefile
new file mode 100644
index 000000000..84373db74
--- /dev/null
+++ b/doc/manual/Makefile
@@ -0,0 +1,49 @@
+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 = 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): lint FORCE
+
+$(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),clean-$(i)):
+ rm -rf $(patsubst clean-%,%,$@)
+
+FORCE:
diff --git a/doc/manual/html.css b/doc/manual/html.css
new file mode 100644
index 000000000..6eedfd318
--- /dev/null
+++ b/doc/manual/html.css
@@ -0,0 +1,281 @@
+/* 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/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>