sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

bitbake: user-manual-intro.xml: General edits to Introduction chapter. 

I performed a general edit to this chapter.  Some significant changes
include changing the chapter's title to "Overview" when it was titled
"BitBake User Manual", doing some consolidation of text to eliminate
a couple sections that described methods to obtain a copy of BitBake,
and various improvements as needed.

(Bitbake rev: f635c4b36af79b8572095083a392fb58c11198c9)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2014-02-03 07:29:54 -06:00 committed by Richard Purdie
parent 3cdf800334
commit a2e5746f29
1 changed files with 105 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
bitbake/doc/user-manual/user-manual-intro.xml
View File

@ -2,7 +2,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<chapter id="user-manual-intro"> <chapter id="user-manual-intro">
<title>BitBake User Manual</title> <title>Overview</title>
<section id="intro"> <section id="intro">
<title>Introduction</title> <title>Introduction</title>
@ -63,7 +63,7 @@
<itemizedlist> <itemizedlist>
<listitem><para>BitBake, a generic task executor</para></listitem> <listitem><para>BitBake, a generic task executor</para></listitem>
<listitem><para>OpenEmbedded, a metadata set utilized by <listitem><para>OpenEmbedded, a metadata set utilized by
BitBake.</para></listitem> BitBake</para></listitem>
</itemizedlist> </itemizedlist>
Today, BitBake is the primary basis of the Today, BitBake is the primary basis of the
<ulink url="http://www.openembedded.org/">OpenEmbedded</ulink> <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
@ -97,51 +97,50 @@
Support running any number of tasks within a given Support running any number of tasks within a given
package, including, but not limited to, fetching package, including, but not limited to, fetching
upstream sources, unpacking them, patching them, upstream sources, unpacking them, patching them,
configuring them, etc. configuring them, and so forth.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Must be Linux distribution agnostic (both build and Be Linux distribution agnostic for both build and
target). target systems.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Must be architecture agnostic Be architecture agnostic.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Must support multiple build and target operating systems Support multiple build and target operating systems
(including Cygwin, the BSDs, etc). (e.g. Cygwin, the BSDs, and so forth).
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Must be able to be self contained, rather than tightly Be self contained, rather than tightly
integrated into the build machine's root integrated into the build machine's root
filesystem. filesystem.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
There must be a way to handle conditional metadata Handle conditional metadata on the target architecture,
(on target architecture, operating system, operating system, distribution, and machine.
distribution, machine).
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
It must be easy for the person using the tools to Be easy to use the tools to supply local metadata and packages
supply their own local metadata and packages against which to operate.
to operate against.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Must make it easy to collaborate between multiple Be easy to use BitBake to collaborate between multiple
projects using BitBake for their builds. projects for their builds.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Should provide an inheritance mechanism to share Provide an inheritance mechanism that share
common metadata between many packages. common metadata between many packages.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
Over time it has become apparent that some further requirements Over time it became apparent that some further requirements
were necessary: were necessary:
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
Handle variants of a base recipe (native, sdk, multilib). Handle variants of a base recipe (e.g. native, sdk,
and multilib).
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Able to split metadata into layers and allow layers Split metadata into layers and allow layers
to override each other. to override each other.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
@ -155,7 +154,7 @@
with extensions being made to the basic functionality to with extensions being made to the basic functionality to
reflect the additional requirements. reflect the additional requirements.
Flexibility and power have always been the priorities. Flexibility and power have always been the priorities.
It is highly extensible, supporting embedded Python code and BitBake is highly extensible and supports embedded Python code and
execution of any arbitrary tasks. execution of any arbitrary tasks.
</para> </para>
</section> </section>
@ -169,23 +168,30 @@
what tasks are required to run, and executes those tasks. what tasks are required to run, and executes those tasks.
Similar to GNU Make, BitBake controls how software is Similar to GNU Make, BitBake controls how software is
built. built.
GNU Make does this using "makefiles". BitBake uses GNU Make achieves its control through "makefiles".
"recipes". BitBake uses "recipes".
</para>
<para>
BitBake extends the capabilities of a simple BitBake extends the capabilities of a simple
tool like GNU make by allowing for much more complex tasks tool like GNU Make by allowing for much more complex tasks
to be completed, such as assembling entire embedded Linux to be completed, such as assembling entire embedded Linux
distributions. Several concepts must be understood to be able distributions.
to leverage the power of the tool. </para>
<para>
The remainder of this section introduces several concepts
that should be understood in order to better leverage
the power of BitBake.
</para> </para>
<section id='recipes'> <section id='recipes'>
<title>Recipes</title> <title>Recipes</title>
<para> <para>
A BitBake Recipe, denoted by the file extension BitBake Recipes, which are denoted by the file extension
<filename>.bb</filename> is the most <filename>.bb</filename>, are the most basic metadata files.
basic metadata file. These recipe files provide BitBake the following:
These recipe files tell BitBake the following:
<itemizedlist> <itemizedlist>
<listitem><para>Descriptive information about the package</para></listitem> <listitem><para>Descriptive information about the package</para></listitem>
<listitem><para>The version of the recipe</para></listitem> <listitem><para>The version of the recipe</para></listitem>
@ -193,19 +199,21 @@
<listitem><para>Where the source code resides</para></listitem> <listitem><para>Where the source code resides</para></listitem>
<listitem><para>Whether the source code requires any patches</para></listitem> <listitem><para>Whether the source code requires any patches</para></listitem>
<listitem><para>How to compile the source code</para></listitem> <listitem><para>How to compile the source code</para></listitem>
<listitem><para>Where on the target machine to install the package being compiled</para></listitem> <listitem><para>Where on the target machine to install the
package being compiled</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
Within the context of BitBake, or any project utilizing BitBake Within the context of BitBake, or any project utilizing BitBake
as it's build system, files with the <filename>.bb</filename> as it's build system, files with the <filename>.bb</filename>
extension are referred extension are referred to as recipes.
to as recipes. <note>
The term "package" is also commonly used to describe recipes. The term "package" is also commonly used to describe recipes.
However, since the same word is used to describe packaged However, since the same word is used to describe packaged
output from a project, it is best to maintain a single output from a project, it is best to maintain a single
descriptive term, "recipes". descriptive term, "recipes".
</note>
</para> </para>
</section> </section>
@ -213,18 +221,18 @@
<title>Configuration Files</title> <title>Configuration Files</title>
<para> <para>
Configuration files, denoted by the Configuration files, which are denoted by the
<filename>.conf</filename> extension define <filename>.conf</filename> extension, define
various configuration variables that govern the project build various configuration variables that govern the project's build
process. process.
These files fall into several areas that define These files fall into several areas that define
machine configuration options, distribution configuration machine configuration options, distribution configuration
options, compiler tuning options, general common options, compiler tuning options, general common
configuration options and user configuration options. configuration options, and user configuration options.
The main configuration file is the sample The main configuration file is the sample
<filename>bitbake.conf</filename> file, <filename>bitbake.conf</filename> file, which is
located within the bitbake source tree located within the BitBake source tree
<filename>/conf</filename> directory. <filename>conf</filename> directory.
</para> </para>
</section> </section>
@ -232,20 +240,21 @@
<title>Classes</title> <title>Classes</title>
<para> <para>
Class files, denoted by the Class files, which are denoted by the
<filename>.bbclass</filename> extension contain <filename>.bbclass</filename> extension, contain
information that is useful to share between metadata files. information that is useful to share between metadata files.
The BitBake source tree comes with one class metadata file The BitBake source tree currently comes with one class metadata file
currently, called <filename>base.bbclass</filename> and it is called <filename>base.bbclass</filename>.
found in the <filename>/classes</filename> directory. You can find this file in the
<filename>classes</filename> directory.
The <filename>base.bbclass</filename> is special in that any The <filename>base.bbclass</filename> is special in that any
new classes that a developer adds to a project is required to new classes that a developer adds to a project are required to
inherit it automatically. inherit <filename>base.bbclass</filename> automatically.
This class contains definitions for standard basic tasks such This class contains definitions for standard basic tasks such
as fetching, unpacking, configuring (empty by default), as fetching, unpacking, configuring (empty by default),
compiling (runs any Makefile present), installing (empty by compiling (runs any Makefile present), installing (empty by
default) and packaging (empty by default). default) and packaging (empty by default).
These classes are often overridden or extended by other classes These tasks are often overridden or extended by other classes
added during the project development process. added during the project development process.
</para> </para>
</section> </section>
@ -255,82 +264,53 @@
<title>Obtaining BitBake</title> <title>Obtaining BitBake</title>
<para> <para>
There are several ways to obtain BitBake. You can obtain BitBake several different ways:
These include installing using your Linux distribution's <itemizedlist>
package management system (not recommended), downloading <listitem><para><emphasis>Installation using your Distribution
a snapshot from the BitBake source Package Management System:</emphasis>
code repository, or using Git to clone the BitBake source This method is not
code repository. recommended because the BitBake version, in most
The recommended method for daily BitBake use is to download cases provided by your distribution, is several
a stable release from the BitBake source code repository. releases behind a snapshot of the BitBake repository.
Using your distribution's version as provided in the package </para></listitem>
management system is generally not <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
recommended as in most cases, such as with the Ubuntu and Downloading a snapshot of BitBake from the
Fedora distributions, the version provided is several releases source code repository is the recommended method
behind the repository snapshot version and is missing as you are assured of having the most recent stable
important bug fixes and enhancements. Similarly, daily use BitBake release.</para>
of the latest clone of the Git repository is not recommended <para>The following example downloads a snapshot of
as it can be unstable. BitBake version 1.17.0:
However, the Git repository clone will provide the User <literallayout class='monospaced'>
with the absolute latest version of BitBake.
</para>
</section>
<section id='downloading-a-snapshot-from-the-bitbake-source-tree'>
<title>Downloading a Snapshot from the BitBake Source Tree</title>
<para>
The recommended method for obtaining and using BitBake on
a daily basis is to download the most
recent stable snapshot from the Git source code repository
as follows:
<literallayout class='monospaced'>
$ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
$ tar zxpvf bitbake-1.17.0.tar.gz $ tar zxpvf bitbake-1.17.0.tar.gz
</literallayout> </literallayout>
After extraction of the tarball using the tar utility, After extraction of the tarball using the tar utility,
you will have a directory entitled you have a directory entitled
<filename>bitbake-1.17.0</filename>. <filename>bitbake-1.17.0</filename>.
</para> </para></listitem>
</section> <listitem><para><emphasis>Cloning BitBake:</emphasis>
Using Git to clone the BitBake source code repository
<section id='cloning-the-bitbake-git-repository'> is also a recommended method when you need the absolute latest
<title>Cloning the BitBake Git Repository</title> BitBake source.
Realize that using this method could expose you to areas of
<para> BitBake that are under development.</para>
To obtain the latest BitBake source code from the <para>Here is an example:
BitBake Git repository: <literallayout class='monospaced'>
<literallayout class='monospaced'>
$ git clone git://git.openembedded.org/bitbake $ git clone git://git.openembedded.org/bitbake
</literallayout> </literallayout>
This will clone the BitBake Git repository into a This command clones the BitBake Git repository into a
directory called <filename>bitbake</filename>. directory called <filename>bitbake</filename>.
Alternatively, you can Alternatively, you can
designate a directory after the git clone command designate a directory after the
if you'd prefer to call the new directory something <filename>git clone</filename> command
other than <filename>bitbake</filename>. if you want to call the new directory something
For example: other than <filename>bitbake</filename>.
<literallayout class='monospaced'> Here is an example that names the directory
<filename>bbdev</filename>:
<literallayout class='monospaced'>
$ git clone git://git.openembedded.org/bitbake bbdev $ git clone git://git.openembedded.org/bitbake bbdev
</literallayout> </literallayout></para></listitem>
This would clone the Git repository into a local directory </itemizedlist>
called <filename>bbdev</filename>.
Please note that although this method of obtaining the
source code will provide the absolute latest version,
it is under active development and may not be as stable
as a released snapshot.
</para>
</section>
<section id='summary'>
<title>Summary</title>
<para>
At this point you should have a general idea of the concepts
that BitBake was built on and how the
source code is organized.
You should have a working version of BitBake installed
and understand how to setup your environment.
</para> </para>
</section> </section>
</chapter> </chapter>