mirror of
https://git.yoctoproject.org/poky
synced 2026-04-25 06:32:12 +02:00
a2e5746f29
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>
317 lines
15 KiB
XML
317 lines
15 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter id="user-manual-intro">
|
|
<title>Overview</title>
|
|
|
|
<section id="intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
fundamentally, BitBake is a generic task execution
|
|
engine that allows shell and Python tasks to be run
|
|
efficiently and in parallel while working within
|
|
complex inter-task dependency constraints.
|
|
One of BitBake's main users, OpenEmbedded, takes this core
|
|
and builds embedded Linux software stacks using
|
|
a task-oriented approach.
|
|
</para>
|
|
|
|
<para>
|
|
Conceptually, BitBake is similar to GNU Make in
|
|
some regards but has significant differences:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
BitBake executes tasks according to provided
|
|
metadata that builds up the tasks.
|
|
Metadata is stored in recipe (<filename>.bb</filename>),
|
|
configuration (<filename>.conf</filename>), and class
|
|
(<filename>.bbclass</filename>) files and provides
|
|
BitBake with instructions on what tasks to run and
|
|
the dependencies between those tasks.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
BitBake includes a fetcher library for obtaining source
|
|
code from various places such as source control
|
|
systems or websites.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
The instructions for each unit to be built (e.g. a piece
|
|
of software) are known as recipe files and
|
|
contain all the information about the unit
|
|
(dependencies, source file locations, checksums, description
|
|
and so on).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
BitBake includes a client/server abstraction and can
|
|
be used from a command line or used as a service over XMLRPC and
|
|
has several different user interfaces.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="history-and-goals">
|
|
<title>History and Goals</title>
|
|
|
|
<para>
|
|
BitBake was originally a part of the OpenEmbedded project.
|
|
It was inspired by the Portage package management system
|
|
used by the Gentoo Linux distribution.
|
|
On December 7, 2004, OpenEmbedded project team member,
|
|
Chris Larson split the project into two distinct pieces:
|
|
<itemizedlist>
|
|
<listitem><para>BitBake, a generic task executor</para></listitem>
|
|
<listitem><para>OpenEmbedded, a metadata set utilized by
|
|
BitBake</para></listitem>
|
|
</itemizedlist>
|
|
Today, BitBake is the primary basis of the
|
|
<ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
|
|
project, which is being used to build and maintain a
|
|
number of projects and embedded Linux distributions
|
|
such as the Angstrom Distribution and the Yocto
|
|
Project.
|
|
</para>
|
|
|
|
<para>
|
|
Prior to BitBake, no other build tool adequately met the needs of
|
|
an aspiring embedded Linux distribution.
|
|
All of the build systems used by traditional desktop Linux
|
|
distributions lacked important functionality, and none of the
|
|
ad-hoc buildroot systems, prevalent in the
|
|
embedded space, were scalable or maintainable.
|
|
</para>
|
|
|
|
<para>
|
|
Some important original goals for BitBake were:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Handle cross-compilation.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Handle inter-package 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, and so forth.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Be Linux distribution agnostic for both build and
|
|
target systems.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Be architecture agnostic.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Support multiple build and target operating systems
|
|
(e.g. Cygwin, the BSDs, and so forth).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Be self contained, rather than tightly
|
|
integrated into the build machine's root
|
|
filesystem.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Handle conditional metadata on the target architecture,
|
|
operating system, distribution, and machine.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Be easy to use the tools to supply local metadata and packages
|
|
against which to operate.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Be easy to use BitBake to collaborate between multiple
|
|
projects for their builds.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Provide an inheritance mechanism that share
|
|
common metadata between many packages.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
Over time it became apparent that some further requirements
|
|
were necessary:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Handle variants of a base recipe (e.g. native, sdk,
|
|
and multilib).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Split metadata into layers and allow layers
|
|
to override each other.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Allow representation of a given set of input variables
|
|
to a task as a checksum.
|
|
Based on that checksum, allow acceleration of builds
|
|
with prebuilt components.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
BitBake satisfies all the original requirements and many more
|
|
with extensions being made to the basic functionality to
|
|
reflect the additional requirements.
|
|
Flexibility and power have always been the priorities.
|
|
BitBake is highly extensible and supports embedded Python code and
|
|
execution of any arbitrary tasks.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="Concepts">
|
|
<title>Concepts</title>
|
|
|
|
<para>
|
|
BitBake is a program written in the Python language.
|
|
At the highest level, BitBake interprets metadata, decides
|
|
what tasks are required to run, and executes those tasks.
|
|
Similar to GNU Make, BitBake controls how software is
|
|
built.
|
|
GNU Make achieves its control through "makefiles".
|
|
BitBake uses "recipes".
|
|
</para>
|
|
|
|
<para>
|
|
BitBake extends the capabilities of a simple
|
|
tool like GNU Make by allowing for much more complex tasks
|
|
to be completed, such as assembling entire embedded Linux
|
|
distributions.
|
|
</para>
|
|
|
|
<para>
|
|
The remainder of this section introduces several concepts
|
|
that should be understood in order to better leverage
|
|
the power of BitBake.
|
|
</para>
|
|
|
|
<section id='recipes'>
|
|
<title>Recipes</title>
|
|
|
|
<para>
|
|
BitBake Recipes, which are denoted by the file extension
|
|
<filename>.bb</filename>, are the most basic metadata files.
|
|
These recipe files provide BitBake the following:
|
|
<itemizedlist>
|
|
<listitem><para>Descriptive information about the package</para></listitem>
|
|
<listitem><para>The version of the recipe</para></listitem>
|
|
<listitem><para>When dependencies exist</para></listitem>
|
|
<listitem><para>Where the source code resides</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>Where on the target machine to install the
|
|
package being compiled</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Within the context of BitBake, or any project utilizing BitBake
|
|
as it's build system, files with the <filename>.bb</filename>
|
|
extension are referred to as recipes.
|
|
<note>
|
|
The term "package" is also commonly used to describe recipes.
|
|
However, since the same word is used to describe packaged
|
|
output from a project, it is best to maintain a single
|
|
descriptive term, "recipes".
|
|
</note>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='configuration-files'>
|
|
<title>Configuration Files</title>
|
|
|
|
<para>
|
|
Configuration files, which are denoted by the
|
|
<filename>.conf</filename> extension, define
|
|
various configuration variables that govern the project's build
|
|
process.
|
|
These files fall into several areas that define
|
|
machine configuration options, distribution configuration
|
|
options, compiler tuning options, general common
|
|
configuration options, and user configuration options.
|
|
The main configuration file is the sample
|
|
<filename>bitbake.conf</filename> file, which is
|
|
located within the BitBake source tree
|
|
<filename>conf</filename> directory.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='classes'>
|
|
<title>Classes</title>
|
|
|
|
<para>
|
|
Class files, which are denoted by the
|
|
<filename>.bbclass</filename> extension, contain
|
|
information that is useful to share between metadata files.
|
|
The BitBake source tree currently comes with one class metadata file
|
|
called <filename>base.bbclass</filename>.
|
|
You can find this file in the
|
|
<filename>classes</filename> directory.
|
|
The <filename>base.bbclass</filename> is special in that any
|
|
new classes that a developer adds to a project are required to
|
|
inherit <filename>base.bbclass</filename> automatically.
|
|
This class contains definitions for standard basic tasks such
|
|
as fetching, unpacking, configuring (empty by default),
|
|
compiling (runs any Makefile present), installing (empty by
|
|
default) and packaging (empty by default).
|
|
These tasks are often overridden or extended by other classes
|
|
added during the project development process.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id='obtaining-bitbake'>
|
|
<title>Obtaining BitBake</title>
|
|
|
|
<para>
|
|
You can obtain BitBake several different ways:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>Installation using your Distribution
|
|
Package Management System:</emphasis>
|
|
This method is not
|
|
recommended because the BitBake version, in most
|
|
cases provided by your distribution, is several
|
|
releases behind a snapshot of the BitBake repository.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
|
|
Downloading a snapshot of BitBake from the
|
|
source code repository is the recommended method
|
|
as you are assured of having the most recent stable
|
|
BitBake release.</para>
|
|
<para>The following example downloads a snapshot of
|
|
BitBake version 1.17.0:
|
|
<literallayout class='monospaced'>
|
|
$ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
|
|
$ tar zxpvf bitbake-1.17.0.tar.gz
|
|
</literallayout>
|
|
After extraction of the tarball using the tar utility,
|
|
you have a directory entitled
|
|
<filename>bitbake-1.17.0</filename>.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>Cloning BitBake:</emphasis>
|
|
Using Git to clone the BitBake source code repository
|
|
is also a recommended method when you need the absolute latest
|
|
BitBake source.
|
|
Realize that using this method could expose you to areas of
|
|
BitBake that are under development.</para>
|
|
<para>Here is an example:
|
|
<literallayout class='monospaced'>
|
|
$ git clone git://git.openembedded.org/bitbake
|
|
</literallayout>
|
|
This command clones the BitBake Git repository into a
|
|
directory called <filename>bitbake</filename>.
|
|
Alternatively, you can
|
|
designate a directory after the
|
|
<filename>git clone</filename> command
|
|
if you want to call the new directory something
|
|
other than <filename>bitbake</filename>.
|
|
Here is an example that names the directory
|
|
<filename>bbdev</filename>:
|
|
<literallayout class='monospaced'>
|
|
$ git clone git://git.openembedded.org/bitbake bbdev
|
|
</literallayout></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</chapter>
|