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 workflow 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
build/conf
directory of 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-poky
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
oe-init-build-env
,
which is the build environment script.
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
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-poky
layer:
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.
Distribution Policy:
Controlled by the
DISTRO
variable.
Packaging Format:
Controlled by the
PACKAGE_CLASSES
variable.
SDK Target Architecture:
Controlled by the
SDKMACHINE
variable.
Extra Image Packages:
Controlled by the
EXTRA_IMAGE_FEATURES
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 Tasks Manual.
The files site.conf
and
auto.conf
are not created by the
environment initialization script.
If you want the site.conf
file, you
need to create that yourself.
The auto.conf
file is typically created by
an autobuilder:
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 packaging format to use
through the
PACKAGE_CLASSES
variable.
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
:
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.
It is important to understand that the
OpenEmbedded build system
reads the configuration files in a specific order:
target
site.conf
, auto.conf
,
and local.conf
.
And, the build system applies the normal assignment statement
rules as described in the
"Syntax and Operators"
chapter of the BitBake User Manual.
Because the files are parsed in a specific order, variable
assignments for the same variable could be affected.
For example, if the auto.conf
file and
the local.conf
set
variable1
to different values,
because the build system parses local.conf
after auto.conf
,
variable1
is assigned the value from
the local.conf
file.