BitBake用户手册：详解、概念与命令指南

需积分: 15 130 浏览量更新于2024-07-09 收藏 506KB PDF 举报

BitBake User Manual 是一份详尽的文档，介绍了 BitBake 这个用于构建软件包的自动化工具。BitBake 由 Richard Purdie、Chris Larson 和 Phil Blundell 开发，自 2004 年以来持续更新，遵循 Creative Commons Attribution License 许可，允许用户在保留原作者署名的前提下自由使用和分享。 1. **概述** - BitBake 的介绍部分概述了其设计理念和目标，强调了其在嵌入式开发环境中的关键作用，如 OpenEmbedded 构建系统。 - BitBake 的核心概念包括： - **配方 (Recipes)**：描述如何构建软件包的详细指令集，包括所需的源代码、依赖项和构建步骤。 - **配置文件**：如.bb 文件，用于定义层（Layers）、变量和任务执行顺序等。 - **类 (Classes)**：自定义功能模块，对构建过程进行扩展或定制。 - **层 (Layers)**：组织和分发 BitBake 需求和构建逻辑的结构单元。 - **附加文件 (AppendFiles)**：提供额外的配置或变量设置，增强定制性。 2. **执行流程** - BitBake 的执行涉及解析基础配置元数据、定位和解析配方、处理偏好和提供者、管理依赖关系、生成任务列表、执行任务、以及校验文件完整性。 - 执行阶段详细到任务调度，从基础配置的解析开始，到依赖关系的处理，再到最终的文件校验。 3. **语法和运算符** - BitBake 的语法简洁但强大，包括基本变量设置、变量展开、默认值设定（= 和 ??=），以及立即变量赋值等操作。这部分内容对于编写和理解配方至关重要。 4. **命令行使用** - BitBake 命令行提供了丰富的选项和用法，包括命令的使用和示例，帮助用户高效地控制构建过程。通过阅读这份手册，读者可以深入了解如何使用 BitBake 构建和管理复杂的软件包，学习其背后的逻辑，以及如何调整和扩展其功能以适应特定项目需求。无论是初学者还是高级用户，这份文档都是理解和优化 BitBake 工作流程的宝贵资源。

For each directory (layer) in this list, a conf/layer.conf file is searched for and parsed with the

LAYERDIR variable being set to the directory where the layer was found. The idea is these files

automatically setup BBPATH and other variables correctly for a given build directory.

BitBake then expects to find the conf/bitbake.conf file somewhere in the user-specified BBPATH.

That configuration file generally has include directives to pull in any other metadata such as files specific to the

architecture, the machine, the local environment, and so forth.

Only variable definitions and include directives are allowed in .conf files. Some variables directly influence

BitBake's behavior. These variables might have been set from the environment depending on the environment

variables previously mentioned or set in the configuration files. The "Variables Glossary" chapter presents a full

list of variables.

After parsing configuration files, BitBake uses its rudimentary inheritance mechanism, which is through class

files, to inherit some standard classes. BitBake parses a class when the inherit directive responsible for getting

that class is encountered.

The base.bbclass file is always included. Other classes that are specified in the configuration using the

INHERIT variable are also included. BitBake searches for class files in a "classes" subdirectory under the

paths in BBPATH in the same way as configuration files.

A good way to get an idea of the configuration files and the class files used in your execution environment is to

run the following BitBake command:

$ bitbake -e > mybb.log

Examining the top of the mybb.log shows you the many configuration files and class files used in your

execution environment.

Note

You need to be aware of how BitBake parses curly braces. If a recipe uses a closing

curly brace within the function and the character has no leading spaces, BitBake

produces a parsing error. If you use a pair of curly brace in a shell function, the

closing curly brace must not be located at the start of the line without leading spaces.

Here is an example that causes BitBake to produce a parsing error:

fakeroot create_shar() {

cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh

usage()

{

echo "test"

###### The following "}" at the start of the line causes a parsing error ######

}

EOF

}

Writing the recipe this way avoids the error:

2.2. Locating and Parsing Recipes

During the configuration phase, BitBake will have set BBFILES. BitBake now uses it to construct a list of

recipes to parse, along with any append files (.bbappend) to apply. BBFILES is a space-separated list of

available files and supports wildcards. An example would be:

BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"

BitBake parses each recipe and append file located with BBFILES and stores the values of various variables

into the datastore.

Note

fakeroot create_shar() {

cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh

usage()

{

echo "test"

######The following "}" with a leading space at the start of the line avoids the er

}

EOF

}

Append files are applied in the order they are encountered in BBFILES.
For each file, a fresh copy of the base configuration is made, then the recipe is parsed line by line. Any inherit
statements cause BitBake to find and then parse class files (.bbclass) using BBPATH as the search path.
Finally, BitBake parses in order any append files found in BBFILES.
One common convention is to use the recipe filename to define pieces of metadata. For example, in
bitbake.conf the recipe name and version set PN and PV:
     PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[1] or '1.0'}" 
     PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[0] or 'defaultpkgname'}" 
            
In this example, a recipe called "something_1.2.3.bb" sets PN to "something" and PV to "1.2.3".
By the time parsing is complete for a recipe, BitBake has a list of tasks that the recipe defines and a set of
data consisting of keys and values as well as dependency information about the tasks.
BitBake does not need all of this information. It only needs a small subset of the information to make decisions
about the recipe. Consequently, BitBake caches the values in which it is interested and does not store the rest
of the information. Experience has shown it is faster to re-parse the metadata than to try and write it out to
the disk and then reload it.
Where possible, subsequent BitBake commands reuse this cache of recipe information. The validity of this
cache is determined by first computing a checksum of the base configuration data (see
BB_HASHCONFIG_WHITELIST) and then checking if the checksum matches. If that checksum matches
what is in the cache and the recipe and class files have not changed, Bitbake is able to use the cache. BitBake
then reloads the cached information about the recipe instead of reparsing it from scratch.
Recipe file collections exist to allow the user to have multiple repositories of .bb files that contain the same
exact package. For example, one could easily use them to make one's own local copy of an upstream
repository, but with custom modifications that one does not want upstream. Here is an example:
    BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" 
    BBFILE_COLLECTIONS = "upstream local" 
    BBFILE_PATTERN_upstream = "^/stuff/openembedded/" 
    BBFILE_PATTERN_local = "^/stuff/openembedded.modified/" 
    BBFILE_PRIORITY_upstream = "5" 
    BBFILE_PRIORITY_local = "10" 
            
Note
The layers mechanism is now the preferred method of collecting code. While the
collections code remains, its main use is to set layer priorities and to deal with overlap
(conflicts) between layers.
2.3. Preferences and Providers
Assuming BitBake has been instructed to execute a target and that all the recipe files have been parsed,
BitBake starts to figure out how to build the target. BitBake starts by looking through the PROVIDES set in
recipe files. The default PROVIDES for a recipe is its name (PN), however, a recipe can provide multiple
things.
As an example of adding an extra provider, suppose a recipe named foo_1.0.bb contained the following:
     PROVIDES += "virtual/bar_1.0" 
            
The recipe now provides both "foo_1.0" and "virtual/bar_1.0". The "virtual/" namespace is often used to
denote cases where multiple providers are expected with the user choosing between them. Kernels and
toolchain components are common cases of this in OpenEmbedded.
Sometimes a target might have multiple providers. A common example is "virtual/kernel", which is provided
by each kernel recipe. Each machine often selects the best kernel provider by using a line similar to the
following in the machine configuration file:
     PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" 
            
The default PREFERRED_PROVIDER is the provider with the same name as the target. Bitbake iterates
through each target it needs to build and resolves them and their dependencies using this process.
Understanding how providers are chosen is made complicated by the fact that multiple versions might exist.
BitBake defaults to the highest version of a provider. Version comparisons are made using the same method as
Debian. You can use the PREFERRED_VERSION variable to specify a particular version. You can influence
the order by using the DEFAULT_PREFERENCE variable. By default, files have a preference of "0". Setting
the DEFAULT_PREFERENCE to "-1" makes the recipe unlikely to be used unless it is explicitly referenced.

Setting the DEFAULT_PREFERENCE to "1" makes it likely the recipe is used. PREFERRED_VERSION
overrides any DEFAULT_PREFERENCE setting. DEFAULT_PREFERENCE is often used to mark newer
and more experimental recipe versions until they have undergone sufficient testing to be considered stable.
When there are multiple “versions” of a given recipe, BitBake defaults to selecting the most recent version,
unless otherwise specified. If the recipe in question has a DEFAULT_PREFERENCE set lower than the
other recipes (default is 0), then it will not be selected. This allows the person or persons maintaining the
repository of recipe files to specify their preference for the default selected version. In addition, the user can
specify their preferred version.
If the first recipe is named a_1.1.bb, then the PN variable will be set to “a”, and the PV variable will be set
to 1.1.
If we then have a recipe named a_1.2.bb, BitBake will choose 1.2 by default. However, if we define the
following variable in a .conf file that BitBake parses, we can change that.
     PREFERRED_VERSION_a = "1.1" 
            
In summary, BitBake has created a list of providers, which is prioritized, for each target.
2.4. Dependencies
Each target BitBake builds consists of multiple tasks such as fetch, unpack, patch, configure, and
compile. For best performance on multi-core systems, BitBake considers each task as an independent
entity with its own set of dependencies.
Dependencies are defined through several variables. You can find information about variables BitBake uses in
the Variables Glossary near the end of this manual. At a basic level, it is sufficient to know that BitBake uses
the DEPENDS and RDEPENDS variables when calculating dependencies.
For more information on how BitBake handles dependencies, see the "Dependencies" section.
2.5. The Task List
Based on the generated list of providers and the dependency information, BitBake can now calculate exactly
what tasks it needs to run and in what order it needs to run them. The "Executing Tasks" section has more
information on how BitBake chooses which task to execute next.
The build now starts with BitBake forking off threads up to the limit set in the BB_NUMBER_THREADS
variable. BitBake continues to fork threads as long as there are tasks ready to run, those tasks have all their
dependencies met, and the thread threshold has not been exceeded.
It is worth noting that you can greatly speed up the build time by properly setting the
BB_NUMBER_THREADS variable.
As each task completes, a timestamp is written to the directory specified by the STAMP variable. On
subsequent runs, BitBake looks in the build directory within tmp/stampsand does not rerun tasks that are
already completed unless a timestamp is found to be invalid. Currently, invalid timestamps are only considered
on a per recipe file basis. So, for example, if the configure stamp has a timestamp greater than the compile
timestamp for a given target, then the compile task would rerun. Running the compile task again, however,
has no effect on other providers that depend on that target.
The exact format of the stamps is partly configurable. In modern versions of BitBake, a hash is appended to
the stamp so that if the configuration changes, the stamp becomes invalid and the task is automatically rerun.
This hash, or signature used, is governed by the signature policy that is configured (see the "Checksums
(Signatures)" section for information). It is also possible to append extra metadata to the stamp using the
"stamp-extra-info" task flag. For example, OpenEmbedded uses this flag to make some tasks machine-specific.
Note
Some tasks are marked as "nostamp" tasks. No timestamp file is created when these
tasks are run. Consequently, "nostamp" tasks are always rerun.
For more information on tasks, see the "Tasks" section.
2.6. Executing Tasks
Tasks can either be a shell task or a Python task. For shell tasks, BitBake writes a shell script to
${T}/run.do_taskname.pid and then executes the script. The generated shell script contains all the
exported variables, and the shell functions with all variables expanded. Output from the shell script goes to the
file ${T}/log.do_taskname.pid. Looking at the expanded shell functions in the run file and the
output in the log files is a useful debugging technique.