summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--bitbake/doc/user-manual/user-manual-intro.xml132
1 files changed, 70 insertions, 62 deletions
diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml
index 05a3fc8989..c1a9aed3a5 100644
--- a/bitbake/doc/user-manual/user-manual-intro.xml
+++ b/bitbake/doc/user-manual/user-manual-intro.xml
@@ -19,7 +19,7 @@
19 <title>Introduction</title> 19 <title>Introduction</title>
20 20
21 <para> 21 <para>
22 fundamentally, BitBake is a generic task execution 22 Fundamentally, BitBake is a generic task execution
23 engine that allows shell and Python tasks to be run 23 engine that allows shell and Python tasks to be run
24 efficiently and in parallel while working within 24 efficiently and in parallel while working within
25 complex inter-task dependency constraints. 25 complex inter-task dependency constraints.
@@ -78,10 +78,9 @@
78 </itemizedlist> 78 </itemizedlist>
79 Today, BitBake is the primary basis of the 79 Today, BitBake is the primary basis of the
80 <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink> 80 <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
81 project, which is being used to build and maintain a 81 project, which is being used to build and maintain Linux
82 number of projects and embedded Linux distributions 82 distributions such as the Angstrom Distribution and which is used
83 such as the Angstrom Distribution and the Yocto 83 as the build tool for Linux projects such as the Yocto Project.
84 Project.
85 </para> 84 </para>
86 85
87 <para> 86 <para>
@@ -202,11 +201,11 @@
202 <para> 201 <para>
203 BitBake Recipes, which are denoted by the file extension 202 BitBake Recipes, which are denoted by the file extension
204 <filename>.bb</filename>, are the most basic metadata files. 203 <filename>.bb</filename>, are the most basic metadata files.
205 These recipe files provide BitBake the following: 204 These recipe files provide BitBake with the following:
206 <itemizedlist> 205 <itemizedlist>
207 <listitem><para>Descriptive information about the package</para></listitem> 206 <listitem><para>Descriptive information about the package</para></listitem>
208 <listitem><para>The version of the recipe</para></listitem> 207 <listitem><para>The version of the recipe</para></listitem>
209 <listitem><para>When dependencies exist</para></listitem> 208 <listitem><para>Existing Dependencies</para></listitem>
210 <listitem><para>Where the source code resides</para></listitem> 209 <listitem><para>Where the source code resides</para></listitem>
211 <listitem><para>Whether the source code requires any patches</para></listitem> 210 <listitem><para>Whether the source code requires any patches</para></listitem>
212 <listitem><para>How to compile the source code</para></listitem> 211 <listitem><para>How to compile the source code</para></listitem>
@@ -228,31 +227,6 @@
228 </para> 227 </para>
229 </section> 228 </section>
230 229
231 <section id='append-bbappend-files'>
232 <title>Append Files</title>
233
234 <para>
235 Append files, which are files that have the
236 <filename>.bbappend</filename> file extension, add or
237 extend build information to an existing
238 recipe file.
239 </para>
240
241 <para>
242 BitBake expects every append file to have a corresponding recipe file.
243 Furthermore, the append file and corresponding recipe file
244 must use the same root filename.
245 The filenames can differ only in the file type suffix used
246 (e.g. <filename>formfactor_0.0.bb</filename> and
247 <filename>formfactor_0.0.bbappend</filename>).
248 </para>
249
250 <para>
251 Information in append files overrides the information in the
252 similarly-named recipe file.
253 </para>
254 </section>
255
256 <section id='configuration-files'> 230 <section id='configuration-files'>
257 <title>Configuration Files</title> 231 <title>Configuration Files</title>
258 232
@@ -283,9 +257,9 @@
283 called <filename>base.bbclass</filename>. 257 called <filename>base.bbclass</filename>.
284 You can find this file in the 258 You can find this file in the
285 <filename>classes</filename> directory. 259 <filename>classes</filename> directory.
286 The <filename>base.bbclass</filename> is special in that any 260 The <filename>base.bbclass</filename> is special since it
287 new classes that a developer adds to a project are required to 261 is always included automatically for all recipes
288 inherit <filename>base.bbclass</filename> automatically. 262 and classes.
289 This class contains definitions for standard basic tasks such 263 This class contains definitions for standard basic tasks such
290 as fetching, unpacking, configuring (empty by default), 264 as fetching, unpacking, configuring (empty by default),
291 compiling (runs any Makefile present), installing (empty by 265 compiling (runs any Makefile present), installing (empty by
@@ -324,6 +298,31 @@
324 (<filename>.bbappend</filename>) file. 298 (<filename>.bbappend</filename>) file.
325 </para> 299 </para>
326 </section> 300 </section>
301
302 <section id='append-bbappend-files'>
303 <title>Append Files</title>
304
305 <para>
306 Append files, which are files that have the
307 <filename>.bbappend</filename> file extension, add or
308 extend build information to an existing
309 recipe file.
310 </para>
311
312 <para>
313 BitBake expects every append file to have a corresponding recipe file.
314 Furthermore, the append file and corresponding recipe file
315 must use the same root filename.
316 The filenames can differ only in the file type suffix used
317 (e.g. <filename>formfactor_0.0.bb</filename> and
318 <filename>formfactor_0.0.bbappend</filename>).
319 </para>
320
321 <para>
322 Information in append files overrides the information in the
323 similarly-named recipe file.
324 </para>
325 </section>
327 </section> 326 </section>
328 327
329 <section id='obtaining-bitbake'> 328 <section id='obtaining-bitbake'>
@@ -332,35 +331,22 @@
332 <para> 331 <para>
333 You can obtain BitBake several different ways: 332 You can obtain BitBake several different ways:
334 <itemizedlist> 333 <itemizedlist>
335 <listitem><para><emphasis>Installation using your Distribution
336 Package Management System:</emphasis>
337 This method is not
338 recommended because the BitBake version, in most
339 cases provided by your distribution, is several
340 releases behind a snapshot of the BitBake repository.
341 </para></listitem>
342 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
343 Downloading a snapshot of BitBake from the
344 source code repository is the recommended method
345 as you are assured of having the most recent stable
346 BitBake release.</para>
347 <para>The following example downloads a snapshot of
348 BitBake version 1.17.0:
349 <literallayout class='monospaced'>
350 $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
351 $ tar zxpvf bitbake-1.17.0.tar.gz
352 </literallayout>
353 After extraction of the tarball using the tar utility,
354 you have a directory entitled
355 <filename>bitbake-1.17.0</filename>.
356 </para></listitem>
357 <listitem><para><emphasis>Cloning BitBake:</emphasis> 334 <listitem><para><emphasis>Cloning BitBake:</emphasis>
358 Using Git to clone the BitBake source code repository 335 Using Git to clone the BitBake source code repository
359 is also a recommended method when you need the absolute latest 336 is the recommended method for obtaining BitBake.
360 BitBake source. 337 Cloning the repository makes it easy to get bug fixes
361 Realize that using this method could expose you to areas of 338 and have access to stable branches and the master
362 BitBake that are under development.</para> 339 branch.
363 <para>Here is an example: 340 Once you have cloned BitBake, you should use
341 the latest stable
342 branch for development since the master branch is for
343 BitBake development and might contain less stable changes.
344 </para>
345 <para>You usually need a version of BitBake
346 that matches the metadata you are using.
347 The metadata is generally backwards compatible but
348 not forward compatible.</para>
349 <para>Here is an example that clones the BitBake repository:
364 <literallayout class='monospaced'> 350 <literallayout class='monospaced'>
365 $ git clone git://git.openembedded.org/bitbake 351 $ git clone git://git.openembedded.org/bitbake
366 </literallayout> 352 </literallayout>
@@ -376,6 +362,28 @@
376 <literallayout class='monospaced'> 362 <literallayout class='monospaced'>
377 $ git clone git://git.openembedded.org/bitbake bbdev 363 $ git clone git://git.openembedded.org/bitbake bbdev
378 </literallayout></para></listitem> 364 </literallayout></para></listitem>
365 <listitem><para><emphasis>Installation using your Distribution
366 Package Management System:</emphasis>
367 This method is not
368 recommended because the BitBake version that is
369 provided by your distribution, in most cases,
370 is several
371 releases behind a snapshot of the BitBake repository.
372 </para></listitem>
373 <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
374 Downloading a snapshot of BitBake from the
375 source code repository gives you access to a known
376 branch or release of BitBake.</para>
377 <para>The following example downloads a snapshot of
378 BitBake version 1.17.0:
379 <literallayout class='monospaced'>
380 $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
381 $ tar zxpvf bitbake-1.17.0.tar.gz
382 </literallayout>
383 After extraction of the tarball using the tar utility,
384 you have a directory entitled
385 <filename>bitbake-1.17.0</filename>.
386 </para></listitem>
379 </itemizedlist> 387 </itemizedlist>
380 </para> 388 </para>
381 </section> 389 </section>