User configuration helps define the build. Through user configuration, you can tell BitBake the target architecture for which you are building the image, where to store downloaded source, and other build properties.
The following figure shows an expanded representation of the "User Configuration" box of the general Yocto Project Development Environment figure:
![]() |
BitBake needs some basic configuration files in order to complete
a build.
These files are *.conf
files.
The minimally necessary ones reside as example files in the
Source Directory.
For simplicity, this section refers to the Source Directory as
the "Poky Directory."
When you clone the poky
Git repository or you
download and unpack a Yocto Project release, you can set up the
Source Directory to be named anything you want.
For this discussion, the cloned repository uses the default
name poky
.
The meta-yocto
layer inside Poky contains
a conf
directory that has example
configuration files.
These example files are used as a basis for creating actual
configuration files when you source the build environment
script
(i.e.
oe-init-build-env
or
oe-init-build-env-memres
).
Sourcing the build environment script creates a
Build Directory
if one does not already exist.
BitBake uses the Build Directory for all its work during builds.
The Build Directory has a conf
directory that
contains default versions of your local.conf
and bblayers.conf
configuration files.
These default configuration files are created only if versions
do not already exist in the Build Directory at the time you
source the build environment setup script.
Because the Poky repository is fundamentally an aggregation of
existing repositories, some users might be familiar with running
the oe-init-build-env
or
oe-init-build-env-memres
script in the context
of separate OpenEmbedded-Core and BitBake repositories rather than a
single Poky repository.
This discussion assumes the script is executed from within a cloned
or unpacked version of Poky.
Depending on where the script is sourced, different sub-scripts
are called to set up the Build Directory (Yocto or OpenEmbedded).
Specifically, the script
scripts/oe-setup-builddir
inside the
poky directory sets up the Build Directory and seeds the directory
(if necessary) with configuration files appropriate for the
Yocto Project development environment.
scripts/oe-setup-builddir
script
uses the $TEMPLATECONF
variable to
determine which sample configuration files to locate.
The local.conf
file provides many
basic variables that define a build environment.
Here is a list of a few.
To see the default configurations in a local.conf
file created by the build environment script, see the
local.conf.sample
in the
meta-yocto
layer:
Parallelism Options:
Controlled by the
BB_NUMBER_THREADS
and
PARALLEL_MAKE
variables.
Target Machine Selection:
Controlled by the
MACHINE
variable.
Download Directory:
Controlled by the
DL_DIR
variable.
Shared State Directory:
Controlled by the
SSTATE_DIR
variable.
Build Output:
Controlled by the
TMPDIR
variable.
conf/local.conf
file can also be set in the
conf/site.conf
and
conf/auto.conf
configuration files.
The bblayers.conf
file tells BitBake what
layers you want considered during the build.
By default, the layers listed in this file include layers
minimally needed by the build system.
However, you must manually add any custom layers you have created.
You can find more information on working with the
bblayers.conf
file in the
"Enabling Your Layer"
section in the Yocto Project Development Manual.
The files site.conf
and
auto.conf
are not created by the environment
initialization script.
If you want these configuration files, you must create them
yourself:
site.conf
:
You can use the conf/site.conf
configuration file to configure multiple build directories.
For example, suppose you had several build environments and
they shared some common features.
You can set these default build properties here.
A good example is perhaps the level of parallelism you want
to use through the
BB_NUMBER_THREADS
and
PARALLEL_MAKE
variables.
One useful scenario for using the
conf/site.conf
file is to extend your
BBPATH
variable to include the path to a
conf/site.conf
.
Then, when BitBake looks for Metadata using
BBPATH
, it finds the
conf/site.conf
file and applies your
common configurations found in the file.
To override configurations in a particular build directory,
alter the similar configurations within that build
directory's conf/local.conf
file.
auto.conf
:
This file is not hand-created.
Rather, the file is usually created and written to by
an autobuilder.
The settings put into the file are typically the same as
you would find in the conf/local.conf
or the conf/site.conf
files.
You can edit all configuration files to further define any particular build environment. This process is represented by the "User Configuration Edits" box in the figure.
When you launch your build with the
bitbake
command, BitBake
sorts out the configurations to ultimately define your build
environment.
target