summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-intro.xml
blob: 88c415cc585b97f77ada92abde818ae88e6f7918 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
<!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>BitBake User Manual</title>

    <section id="intro">
        <title>Introduction</title>

        <para>
            BitBake is a tool for executing tasks commonly performed by software
            developers when building systems on a daily basis.
            BitBake can build Systems consisting of numerous individual pieces
            of software, or can be used to build a single application.
            Example tasks that BitBake can execute are fetching source code,
            applying patches to source code, configuring, compiling, and
            packaging applications into a complete system, and managing metadata.
            BitBake abstracts the information for completing individual tasks
            into files known as recipes.
            Recipes contain all of the relevant information required by BitBake
            to complete a given task including dependencies, source file
            locations, etc.
            BitBake is similar to
            <ulink url='http://www.gnu.org/software/make/'>GNU Make</ulink>
            and other build tools.
        </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 <emphasis>buildroot</emphasis> 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, etc.
                    </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>
            </itemizedlist>
        </para>

        <para>
            Over time it has become apparent that some further requirements
            were necessary:
            <itemizedlist>
                <listitem><para>
                    Handle variants of a base recipe (native, sdk, multilib).
                    </para></listitem>
                <listitem><para>
                    Able to 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>
        </para>

        <para>
            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.
            It is highly extensible, supporting 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 does this using "makefiles". BitBake uses
            "recipes".
            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. Several concepts must be understood to be able
            to leverage the power of the tool.
        </para>

        <section id='recipes'>
            <title>Recipes</title>

            <para>
                A BitBake Recipe, denoted by the file extension
                <filename>.bb</filename> is the most
                basic metadata file.
                It tells 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 .bb extension are referred
                to as recipes.
                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".
            </para>
        </section>

        <section id='configuration-files'>
            <title>Configuration Files</title>

            <para>
                Configuration files, denoted by the
                <filename>.conf</filename> extension define
                various configuration variables that govern the project 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 bitbake.conf file,
                located within the bitbake source tree /conf directory.
            </para>
        </section>

        <section id='classes'>
            <title>Classes</title>

            <para>
                Class files, denoted by the
                <filename>.bbclass</filename> extension contain
                information that is useful to share between metadata files.
                The BitBake source tree comes with one class metadata file
                currently, called base.bbclass and it is found in the /classes
                directory.
                The base.bbclass is special in that any new classes that a
                developer adds to a project is required to inherit it
                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 classes are often overridden or extended by other classes
                added during the project development process.
            </para>
        </section>
    </section>
</chapter>