diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile | 49 | ||||
| -rw-r--r-- | doc/manual/html.css | 281 | ||||
| -rw-r--r-- | doc/manual/usermanual.xml | 222 |
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> |