diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml index f013ee6f45..8ce046a340 100644 --- a/bitbake/doc/user-manual/user-manual-intro.xml +++ b/bitbake/doc/user-manual/user-manual-intro.xml @@ -2,7 +2,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - BitBake User Manual + Overview
Introduction @@ -63,7 +63,7 @@ BitBake, a generic task executor OpenEmbedded, a metadata set utilized by - BitBake. + BitBake Today, BitBake is the primary basis of the OpenEmbedded @@ -97,51 +97,50 @@ 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. + configuring them, and so forth. - Must be Linux distribution agnostic (both build and - target). + Be Linux distribution agnostic for both build and + target systems. - Must be architecture agnostic + Be architecture agnostic. - Must support multiple build and target operating systems - (including Cygwin, the BSDs, etc). + Support multiple build and target operating systems + (e.g. Cygwin, the BSDs, and so forth). - Must be able to be self contained, rather than tightly + Be self contained, rather than tightly integrated into the build machine's root filesystem. - There must be a way to handle conditional metadata - (on target architecture, operating system, - distribution, machine). + Handle conditional metadata on the target architecture, + operating system, distribution, and machine. - It must be easy for the person using the tools to - supply their own local metadata and packages - to operate against. + Be easy to use the tools to supply local metadata and packages + against which to operate. - Must make it easy to collaborate between multiple - projects using BitBake for their builds. + Be easy to use BitBake to collaborate between multiple + projects for their builds. - Should provide an inheritance mechanism to share + Provide an inheritance mechanism that share common metadata between many packages. - Over time it has become apparent that some further requirements + Over time it became apparent that some further requirements were necessary: - Handle variants of a base recipe (native, sdk, multilib). + Handle variants of a base recipe (e.g. native, sdk, + and multilib). - Able to split metadata into layers and allow layers + Split metadata into layers and allow layers to override each other. @@ -155,7 +154,7 @@ 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 + BitBake is highly extensible and supports embedded Python code and execution of any arbitrary tasks.
@@ -169,23 +168,30 @@ 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". + GNU Make achieves its control through "makefiles". + BitBake uses "recipes". + + + 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 - distributions. Several concepts must be understood to be able - to leverage the power of the tool. + distributions. + + + + The remainder of this section introduces several concepts + that should be understood in order to better leverage + the power of BitBake.
Recipes - A BitBake Recipe, denoted by the file extension - .bb is the most - basic metadata file. - These recipe files tell BitBake the following: + BitBake Recipes, which are denoted by the file extension + .bb, are the most basic metadata files. + These recipe files provide BitBake the following: Descriptive information about the package The version of the recipe @@ -193,19 +199,21 @@ Where the source code resides Whether the source code requires any patches How to compile the source code - Where on the target machine to install the package being compiled + Where on the target machine to install the + package being compiled 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". + 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". +
@@ -213,18 +221,18 @@ Configuration Files - Configuration files, denoted by the - .conf extension define - various configuration variables that govern the project build + Configuration files, which are denoted by the + .conf 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. + configuration options, and user configuration options. The main configuration file is the sample - bitbake.conf file, - located within the bitbake source tree - /conf directory. + bitbake.conf file, which is + located within the BitBake source tree + conf directory. @@ -232,20 +240,21 @@ Classes - Class files, denoted by the - .bbclass extension contain + Class files, which are denoted by the + .bbclass 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 BitBake source tree currently comes with one class metadata file + called base.bbclass. + You can find this file 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. + new classes that a developer adds to a project are required to + inherit base.bbclass 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 + These tasks are often overridden or extended by other classes added during the project development process. @@ -255,82 +264,53 @@ Obtaining BitBake - There are several ways to obtain BitBake. - These include installing using your Linux distribution's - package management system (not recommended), downloading - a snapshot from the BitBake source - code repository, or using Git to clone the BitBake source - code repository. - The recommended method for daily BitBake use is to download - a stable release from the BitBake source code repository. - Using your distribution's version as provided in the package - management system is generally not - recommended as in most cases, such as with the Ubuntu and - Fedora distributions, the version provided is several releases - behind the repository snapshot version and is missing - important bug fixes and enhancements. Similarly, daily use - of the latest clone of the Git repository is not recommended - as it can be unstable. - However, the Git repository clone will provide the User - with the absolute latest version of BitBake. - - - -
- Downloading a Snapshot from the BitBake Source Tree - - - 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: - + You can obtain BitBake several different ways: + + Installation using your Distribution + Package Management System: + 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. + + Taking a snapshot of BitBake: + 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. + The following example downloads a snapshot of + BitBake version 1.17.0: + $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz $ tar zxpvf bitbake-1.17.0.tar.gz - - After extraction of the tarball using the tar utility, - you will have a directory entitled - bitbake-1.17.0. - -
- -
- Cloning the BitBake Git Repository - - - To obtain the latest BitBake source code from the - BitBake Git repository: - + + After extraction of the tarball using the tar utility, + you have a directory entitled + bitbake-1.17.0. + + Cloning BitBake: + 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. + Here is an example: + $ git clone git://git.openembedded.org/bitbake - - This will clone the BitBake Git repository into a - directory called bitbake. - Alternatively, you can - designate a directory after the git clone command - if you'd prefer to call the new directory something - other than bitbake. - For example: - + + This command clones the BitBake Git repository into a + directory called bitbake. + Alternatively, you can + designate a directory after the + git clone command + if you want to call the new directory something + other than bitbake. + Here is an example that names the directory + bbdev: + $ git clone git://git.openembedded.org/bitbake bbdev - - This would clone the Git repository into a local directory - called bbdev. - 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. - -
- -
- Summary - - - 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. + +