@@ -376,7 +376,7 @@ layer>`:
git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
#. **Add Your Layer to the Layer Configuration File:** Before you can use
- it, you must add the layer and its dependencies to your ``bblayers.conf``
+ it, you must add the layer and its dependencies to your :ref:`structure-build-conf-bblayers.conf`
file, which is found in the :term:`Build Directory` (``conf/``) directory.
For this, the ``bitbake-layers add-layer`` command can be used:
@@ -410,7 +410,7 @@ layer>`:
`Synaptics` license. See the :yocto_git:`ipcompliance.md
</meta-raspberrypi/tree/docs/ipcompliance.md>` document for more information.
Add the ``synaptics-killswitch`` value to the :term:`LICENSE_FLAGS_ACCEPTED`
- variable, in the ``conf/local.conf`` file of your build directory::
+ variable, in the :ref:`structure-build-conf-local.conf` file of your build directory::
LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"
@@ -78,7 +78,7 @@ section in the Yocto Project Development Tasks Manual.
The BSP layer's base directory (``meta-bsp_root_name``) is the root
directory of that Layer. This directory is what you add to the
:term:`BBLAYERS` variable in the
-``conf/bblayers.conf`` file found in your
+:ref:`structure-build-conf-bblayers.conf` file found in your
:term:`Build Directory`, which is
established after you run the OpenEmbedded build environment setup
script (i.e. :ref:`structure-core-script`).
@@ -802,7 +802,7 @@ workflow.
need to get the build environment ready by sourcing an environment
setup script (i.e. ``oe-init-build-env``) and you need to be sure two
key configuration files are configured appropriately: the
- ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must
+ :ref:`structure-build-conf-local.conf` and the :ref:`structure-build-conf-bblayers.conf` file. You must
make the OpenEmbedded build system aware of your new layer. See the
":ref:`dev-manual/layers:enabling your layer`"
section in the Yocto Project Development Tasks Manual for information
@@ -1098,7 +1098,7 @@ list describes them in order of preference:
#. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or
Other Types of Specially-Licensed Packages:* For each of those recipes, you can
- specify a matching license string in a ``local.conf`` variable named
+ specify a matching license string in a :ref:`structure-build-conf-local.conf` variable named
:term:`LICENSE_FLAGS_ACCEPTED`.
Specifying the matching license string signifies that you agree to
the license. Thus, the build system can build the corresponding
@@ -72,7 +72,7 @@ To unlock all recipes, do not specify any recipe::
Configuration file
------------------
-``bblock`` will dump the signatures in the ``build/conf/bblock.conf`` file,
+``bblock`` will dump the signatures in the :ref:`structure-build-conf-bblock.conf` file,
included by default in :oe_git:`meta/conf/bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`.
To dump the file, use the ``-d`` option::
@@ -304,8 +304,8 @@ The following list shows the files produced for SDKs:
specific to the extensible SDK although you can set it differently if
you would like to pull in specific files from the standard SDK.
- The default files are ``conf/local.conf``, ``conf/bblayers.conf``,
- ``conf/auto.conf``, ``conf/locked-sigs.inc``, and
+ The default files are :ref:`structure-build-conf-local.conf`, :ref:`structure-build-conf-bblayers.conf`,
+ :ref:`structure-build-conf-auto.conf`, ``conf/locked-sigs.inc``, and
``conf/devtool.conf``. Thus, for an extensible SDK, these files get
copied into the ``sdk-files`` directory.
@@ -708,7 +708,7 @@ the external directory and use it as is, not copy it.
To build from software that comes from an external source, all you need to do
is inherit the :ref:`ref-classes-externalsrc` class and then set
the :term:`EXTERNALSRC` variable to point to your external source code. Here
-are the statements to put in your ``local.conf`` file::
+are the statements to put in your :ref:`structure-build-conf-local.conf` file::
INHERIT += "externalsrc"
EXTERNALSRC:pn-myrecipe = "path-to-your-source-tree"
@@ -758,7 +758,7 @@ Follow these steps to populate your Downloads directory:
an empty location or one that does not yet exist.
#. *Generate Tarballs of the Source Git Repositories:* Edit your
- ``local.conf`` configuration file as follows::
+ :ref:`structure-build-conf-local.conf` configuration file as follows::
DL_DIR = "/home/your-download-dir/"
BB_GENERATE_MIRROR_TARBALLS = "1"
@@ -793,7 +793,7 @@ any machine and at any time.
Follow these steps to build your target using the files in the downloads
directory:
-#. *Using Local Files Only:* Inside your ``local.conf`` or distro
+#. *Using Local Files Only:* Inside your :ref:`structure-build-conf-local.conf` or distro
:term:`configuration file`, add the :term:`SOURCE_MIRROR_URL` variable,
inherit the :ref:`ref-classes-own-mirrors` class, and add the
:term:`BB_NO_NETWORK` variable::
@@ -26,7 +26,7 @@ layer. The following steps provide some more detail:
so that you can keep your Metadata and code for the distribution
separate. It is strongly recommended that you create and use your own
layer for configuration and code. Using your own layer as compared to
- just placing configurations in a ``local.conf`` configuration file
+ just placing configurations in a :ref:`structure-build-conf-local.conf` configuration file
makes it easier to reproduce the same build configuration when using
multiple build machines. See the
":ref:`dev-manual/layers:Creating Your Own Layer`"
@@ -39,7 +39,7 @@ layer. The following steps provide some more detail:
.. note::
- The :term:`DISTRO` variable in your ``local.conf`` file determines the
+ The :term:`DISTRO` variable in your :ref:`structure-build-conf-local.conf` file determines the
name of your distribution. You can also use the
:ref:`ref-fragments-builtin-core-distro` configuration fragment.
@@ -81,10 +81,10 @@ layer. The following steps provide some more detail:
- *Provide miscellaneous variables:* Be sure to define any other
variables for which you want to create a default or enforce as part
of the distribution configuration. You can include nearly any
- variable from the ``local.conf`` file. The variables you use are not
+ variable from the :ref:`structure-build-conf-local.conf` file. The variables you use are not
limited to the list in the previous bulleted item.
-- *Point to Your distribution configuration file:* In your ``local.conf``
+- *Point to Your distribution configuration file:* In your :ref:`structure-build-conf-local.conf`
file in the :term:`Build Directory`, set your :term:`DISTRO` variable to
point to your distribution's configuration file. For example, if your
distribution's configuration file is named ``mydistro.conf``, then
@@ -5,8 +5,8 @@ Creating a Custom Template Configuration Directory
If you are producing your own customized version of the build system for
use by other users, you might want to provide a custom build configuration
-that includes all the necessary settings and layers (i.e. ``local.conf`` and
-``bblayers.conf`` that are created in a new :term:`Build Directory`) and a custom
+that includes all the necessary settings and layers (i.e. :ref:`structure-build-conf-local.conf` and
+:ref:`structure-build-conf-bblayers.conf` that are created in a new :term:`Build Directory`) and a custom
message that is shown when setting up the build. This can be done by
creating one or more template configuration directories in your
custom distribution layer.
@@ -21,7 +21,7 @@ This can be done by using ``bitbake-layers save-build-conf``::
TEMPLATECONF=/srv/bitbake-builds/layers/meta-alex/conf/templates/test-1 . /srv/bitbake-builds/layers/openembedded-core/oe-init-build-env build-try-test-1
The above command takes the config files from the currently active :term:`Build Directory` under ``conf``,
-replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies
+replaces site-specific paths in :ref:`structure-build-conf-bblayers.conf` with ``##OECORE##``-relative paths, and copies
the config files into a specified layer under a specified template name.
To use those saved templates as a starting point for a build, users should point
@@ -44,7 +44,7 @@ would be::
If you look at a configuration template directory, you will
see the ``bblayers.conf.sample``, ``local.conf.sample``, ``conf-summary.txt`` and
``conf-notes.txt`` files. The build system uses these files to form the
-respective ``bblayers.conf`` file, ``local.conf`` file, and show
+respective :ref:`structure-build-conf-bblayers.conf` file, ``local.conf`` file, and show
users usage information about the build they're setting up
when running the ``oe-init-build-env`` setup script. These can be
edited further if needed to improve or change the build configurations
@@ -10,7 +10,7 @@ Customizing Images Using ``local.conf``
=======================================
Probably the easiest way to customize an image is to add a package by
-way of the ``local.conf`` configuration file. Because it is limited to
+way of the :ref:`structure-build-conf-local.conf` configuration file. Because it is limited to
local use, this method generally only allows you to add packages and is
not as flexible as creating your own customized image. When you add
packages using local variables this way, you need to realize that these
@@ -56,7 +56,7 @@ high-level image features by using the
variables. Although the functions for both variables are nearly
equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within
a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your
-``local.conf`` for temporary changes (which is found in the :term:`Build
+:ref:`structure-build-conf-local.conf` for temporary changes (which is found in the :term:`Build
Directory`) and a distro :term:`configuration file` for permanent changes.
To understand how these features work, the best reference is
@@ -91,7 +91,7 @@ image does not contain an SSH server.
You can customize your image and change these defaults. Edit the
:term:`IMAGE_FEATURES` variable in your recipe or use the
-:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file (or distro
+:term:`EXTRA_IMAGE_FEATURES` in your :ref:`structure-build-conf-local.conf` file (or distro
:term:`configuration file`) so that it configures the image you are working with
to include ``ssh-server-dropbear`` or ``ssh-server-openssh``.
@@ -113,7 +113,7 @@ variables>` did not work out as expected.
BitBake's ``bitbake-getvar`` command is used to display variable values after
parsing. The following command displays the variable value for :term:`OVERRIDES`
-after the configuration files (i.e. ``local.conf``, ``bblayers.conf``,
+after the configuration files (i.e. ``local.conf``, :ref:`structure-build-conf-bblayers.conf`,
``bitbake.conf`` and so forth) have been parsed::
$ bitbake-getvar OVERRIDES
@@ -787,7 +787,7 @@ In this example, compiling the "neard" package is causing the problem.
So the first thing to do is build "neard" locally. Before you start the
build, set the
:term:`PARALLEL_MAKE` variable
-in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a
+in your :ref:`structure-build-conf-local.conf` file to a high number (e.g. "-j 20"). Using a
high value for :term:`PARALLEL_MAKE` increases the chances of the race
condition showing up::
@@ -943,7 +943,7 @@ To run a ``debuginfod`` server, you need to do the following:
(it already is in :term:`OpenEmbedded-Core (OE-Core)` defaults and
:term:`Poky` reference distribution).
- If not, set in your distro :term:`configuration file` or in ``local.conf``::
+ If not, set in your distro :term:`configuration file` or in :ref:`structure-build-conf-local.conf`::
DISTRO_FEATURES:append = " debuginfod"
@@ -1010,7 +1010,7 @@ debugger.
#. *Configure your build system to construct the companion debug
filesystem:*
- In your ``local.conf`` file, set the following::
+ In your :ref:`structure-build-conf-local.conf` file, set the following::
IMAGE_GEN_DEBUGFS = "1"
IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
@@ -1029,7 +1029,7 @@ debugger.
#. *Configure the system to include gdbserver in the target filesystem:*
- Make the following addition in your ``local.conf`` file::
+ Make the following addition in your :ref:`structure-build-conf-local.conf` file::
EXTRA_IMAGE_FEATURES:append = " tools-debug"
@@ -1165,7 +1165,7 @@ debug on the target hardware.
To support this kind of debugging, you need do the following:
- Ensure that GDB is on the target. You can do this by making
- the following addition to your ``local.conf`` file::
+ the following addition to your :ref:`structure-build-conf-local.conf` file::
EXTRA_IMAGE_FEATURES:append = " tools-debug"
@@ -1174,7 +1174,7 @@ To support this kind of debugging, you need do the following:
IMAGE_INSTALL:append = " packagename-dbg"
- Alternatively, you can add the following to ``local.conf`` to include
+ Alternatively, you can add the following to :ref:`structure-build-conf-local.conf` to include
all the debug symbols::
EXTRA_IMAGE_FEATURES:append = " dbg-pkgs"
@@ -1183,7 +1183,7 @@ To support this kind of debugging, you need do the following:
To improve the debug information accuracy, you can reduce the level
of optimization used by the compiler. For example, when adding the
- following line to your ``local.conf`` file, you will reduce optimization
+ following line to your :ref:`structure-build-conf-local.conf` file, you will reduce optimization
from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION`
of "-O -fno-omit-frame-pointer"::
@@ -32,7 +32,7 @@ Table file. The
:term:`IMAGE_DEVICE_TABLES`
variable defines the Device Table to use and should be set in the
machine or distro :term:`configuration file`. Alternatively, you can set this
-variable in your ``local.conf`` configuration file.
+variable in your :ref:`structure-build-conf-local.conf` configuration file.
If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default
``device_table-minimal.txt`` is used::
@@ -64,7 +64,7 @@ To have more control over the device nodes, you can use a device manager like
``udev`` or ``busybox-mdev``. You choose the device manager by defining the
:term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` variable in your machine
or distro :term:`configuration file`. Alternatively, you can set this variable in
-your ``local.conf`` configuration file::
+your :ref:`structure-build-conf-local.conf` configuration file::
VIRTUAL-RUNTIME_dev_manager = "udev"
@@ -445,7 +445,7 @@ installers.
functionality of the SDK and the eSDK installers. Compared to the installers,
however, the SDK created with ``devtool ide-sdk`` is much more flexible.
For example, it is very easy to change the :term:`MACHINE` in the
-``local.conf`` file, update the layer meta data and then regenerate the SDK.
+:ref:`structure-build-conf-local.conf` file, update the layer meta data and then regenerate the SDK.
Let's take a look at an example of how to use ``devtool ide-sdk`` in each of
the two modes:
@@ -454,7 +454,7 @@ the two modes:
In order to use the ``devtool ide-sdk``, a few settings are needed. As a
starting example, the following lines of code can be added to the
- ``local.conf`` file::
+ :ref:`structure-build-conf-local.conf` file::
# Build the companion debug file system
IMAGE_GEN_DEBUGFS = "1"
@@ -7,7 +7,7 @@ Conserving Disk Space During Builds
===================================
To help conserve disk space during builds, you can add the following
-statement to your project's ``local.conf`` configuration file found in
+statement to your project's :ref:`structure-build-conf-local.conf` configuration file found in
the :term:`Build Directory`::
INHERIT += "rm_work"
@@ -27,7 +27,7 @@ Enabling and Using the Tool
By default, the error reporting tool is disabled. You can enable it by
inheriting the :ref:`ref-classes-report-error` class by adding the
-following statement to the end of your ``local.conf`` file in your
+following statement to the end of your :ref:`structure-build-conf-local.conf` file in your
:term:`Build Directory`::
INHERIT += "report-error"
@@ -35,7 +35,7 @@ following statement to the end of your ``local.conf`` file in your
By default, the error reporting feature stores information in
``${``\ :term:`LOG_DIR`\ ``}/error-report``.
However, you can specify a directory to use by adding the following to
-your ``local.conf`` file::
+your :ref:`structure-build-conf-local.conf` file::
ERR_REPORT_DIR = "path"
@@ -69,7 +69,7 @@ Disabling the Tool
==================
To disable the error reporting feature, simply remove or comment out the
-following statement from the end of your ``local.conf`` file in your
+following statement from the end of your :ref:`structure-build-conf-local.conf` file in your
:term:`Build Directory`::
INHERIT += "report-error"
@@ -12,7 +12,7 @@ follows:
steps to build and install the toolchain.
- Make sure you add the layer that contains the toolchain to your
- ``bblayers.conf`` file through the
+ :ref:`structure-build-conf-bblayers.conf` file through the
:term:`BBLAYERS` variable.
- Set the :term:`EXTERNAL_TOOLCHAIN` variable in your
@@ -75,7 +75,7 @@ Follow these general steps to create your layer without using tools:
Add your new layer with 'bitbake-layers add-layer meta-scottrif'
In order to use a layer with the :term:`OpenEmbedded Build System`, you
- need to add the layer to your ``bblayers.conf`` configuration
+ need to add the layer to your :ref:`structure-build-conf-bblayers.conf` configuration
file, as hinted by the previous command. See the
":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\`
script`" section for more information.
@@ -219,7 +219,7 @@ following list:
The dependency is created during any
build that includes the layer ``meta-one``. However, you might not
want this dependency for all machines. For example, suppose you
- are building for machine "two" but your ``bblayers.conf`` file has
+ are building for machine "two" but your :ref:`structure-build-conf-bblayers.conf` file has
the ``meta-one`` layer included. During the build, the
``base-files`` for machine "two" will also have the dependency on
``foo``.
@@ -267,7 +267,7 @@ following list:
The build for machine "one" will pick up your machine-specific file as
long as you have the file in
``meta-one/recipes-core/base-files/base-files/``. However, if you
- are building for a different machine and the ``bblayers.conf``
+ are building for a different machine and the :ref:`structure-build-conf-bblayers.conf`
file includes the ``meta-one`` layer and the location of your
machine-specific file is the first location where that file is
found according to :term:`FILESPATH`, builds for all machines will
@@ -466,7 +466,7 @@ Enabling Your Layer
Before the OpenEmbedded build system can use your new layer, you need to
enable it. To enable your layer, simply add your layer's path to the
-:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is
+:term:`BBLAYERS` variable in your :ref:`structure-build-conf-bblayers.conf` file, which is
found in the :term:`Build Directory`. The following example shows how to
enable your new ``meta-mylayer`` layer (note how your new layer exists
outside of the official ``poky`` repository which you would have checked
@@ -485,7 +485,7 @@ out earlier)::
"
BitBake parses each ``conf/layer.conf`` file from the top down as
-specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf``
+specified in the :term:`BBLAYERS` variable within the :ref:`structure-build-conf-bblayers.conf`
file. During the processing of each ``conf/layer.conf`` file, BitBake
adds the recipes, classes and configurations contained within the
particular layer to the source directory.
@@ -822,9 +822,9 @@ The following list describes the available commands:
- ``show-cross-depends:`` Lists dependency relationships between
recipes that cross layer boundaries.
-- ``add-layer:`` Adds a layer to ``bblayers.conf``.
+- ``add-layer:`` Adds a layer to :ref:`structure-build-conf-bblayers.conf`.
-- ``remove-layer:`` Removes a layer from ``bblayers.conf``
+- ``remove-layer:`` Removes a layer from :ref:`structure-build-conf-bblayers.conf`
- ``flatten:`` Flattens the layer configuration into a separate
output directory. Flattening your layer configuration builds a
@@ -870,13 +870,13 @@ The following list describes the available commands:
- ``layerindex-fetch``: Fetches a layer from a layer index, along
with its dependent layers, and adds the layers to the
- ``conf/bblayers.conf`` file.
+ :ref:`structure-build-conf-bblayers.conf` file.
- ``layerindex-show-depends``: Finds layer dependencies from the
layer index.
- ``save-build-conf``: Saves the currently active build configuration
- (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer.
+ (:ref:`structure-build-conf-local.conf`, :ref:`structure-build-conf-bblayers.conf`) as a template into a layer.
This template can later be used for setting up builds via :term:`TEMPLATECONF`.
For information about saving and using configuration templates, see
":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`".
@@ -893,7 +893,7 @@ Adding a Layer Using the ``bitbake-layers`` Script
==================================================
Once you create your general layer, you must add it to your
-``bblayers.conf`` file. Adding the layer to this configuration file
+:ref:`structure-build-conf-bblayers.conf` file. Adding the layer to this configuration file
makes the OpenEmbedded build system aware of your layer so that it can
search it for metadata.
@@ -904,7 +904,7 @@ Add your layer by using the ``bitbake-layers add-layer`` command::
Here is an example that adds a
layer named ``meta-scottrif`` to the configuration file. Following the
command that adds the layer is another ``bitbake-layers`` command that
-shows the layers that are in your ``bblayers.conf`` file:
+shows the layers that are in your :ref:`structure-build-conf-bblayers.conf` file:
.. code-block:: console
@@ -134,7 +134,7 @@ In order for a component restricted by a
:term:`LICENSE_FLAGS` definition to be enabled and included in an image, it
needs to have a matching entry in the global
:term:`LICENSE_FLAGS_ACCEPTED`
-variable, which is a variable typically defined in your ``local.conf``
+variable, which is a variable typically defined in your :ref:`structure-build-conf-local.conf`
file. For example, to enable the
``meta/recipes-multimedia/gstreamer/gstreamer1.0-plugins-ugly`` package of
:term:`OpenEmbedded-Core (OE-Core)`, you
@@ -251,7 +251,7 @@ defined in the
COMMERCIAL_VIDEO_PLUGINS ?= ""
If you want to enable these components, you can do so by making sure you have
-statements similar to the following in your ``local.conf`` configuration file::
+statements similar to the following in your :ref:`structure-build-conf-local.conf` configuration file::
COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
gst-plugins-ugly-mpegaudioparse"
@@ -361,7 +361,7 @@ create them with various levels of compliance in mind.
One way of doing this (but certainly not the only way) is to release
just the source as a tarball. You can do this by adding the following to
-the ``local.conf`` file found in the :term:`Build Directory`::
+the :ref:`structure-build-conf-local.conf` file found in the :term:`Build Directory`::
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
@@ -473,7 +473,7 @@ One thing a development organization might want to consider for end-user
convenience is to provide its own version of the
:oecore_path:`meta/conf/templates/default/bblayers.conf.sample` file to ensure that when
the end user utilizes the released build system to build an image, the
-development organization's layers are included in the ``bblayers.conf`` file
+development organization's layers are included in the :ref:`structure-build-conf-bblayers.conf` file
automatically::
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
@@ -38,7 +38,7 @@ details.
If you want to have a different limit from the rest of the build for a
recipe, it is also possible to achieve with the following line added to your
- ``local.conf`` :term:`configuration file`::
+ :ref:`structure-build-conf-local.conf` :term:`configuration file`::
PARALLEL_MAKE:pn-linux-yocto = "-j4"
@@ -20,7 +20,7 @@ To accomplish a multiple configuration build, you must define each
target's configuration separately using a parallel :term:`configuration file` in
the :term:`Build Directory` or configuration directory within a layer, and you
must follow a required file hierarchy. Additionally, you must enable the
-multiple configuration builds in your ``local.conf`` file.
+multiple configuration builds in your :ref:`structure-build-conf-local.conf` file.
Follow these steps to set up and execute multiple configuration builds:
@@ -74,7 +74,7 @@ Follow these steps to set up and execute multiple configuration builds:
- *Add the BitBake Multi-configuration Variable to the Local
Configuration File*: Use the
:term:`BBMULTICONFIG`
- variable in your ``conf/local.conf`` configuration file to specify
+ variable in your :ref:`structure-build-conf-local.conf` configuration file to specify
each multiconfig. Continuing with the example from the previous
figure, the :term:`BBMULTICONFIG` variable needs to enable two
multiconfigs: "x86" and "arm" by specifying each configuration file::
@@ -85,7 +85,7 @@ Follow these steps to set up and execute multiple configuration builds:
A "default" configuration already exists by definition. This
configuration is named: "" (i.e. empty string) and is defined by
- the variables coming from your ``local.conf``
+ the variables coming from your :ref:`structure-build-conf-local.conf`
file. Consequently, the previous example actually adds two
additional configurations to your build: "arm" and "x86" along
with "".
@@ -107,7 +107,7 @@ Follow these steps to set up and execute multiple configuration builds:
- A ``core-image-sato`` image that is configured through the ``arm.conf``
configuration file
- - A ``core-image-base`` that is configured through your ``local.conf``
+ - A ``core-image-base`` that is configured through your :ref:`structure-build-conf-local.conf`
configuration file
.. note::
@@ -178,7 +178,7 @@ Suggested best practices
========================
- :term:`TMPDIR` (other than the default set in bitbake.conf) is only set in
- ``local.conf`` by the user. This means that we should **not** manipulate
+ :ref:`structure-build-conf-local.conf` by the user. This means that we should **not** manipulate
:term:`TMPDIR` in any way within the Machine or Distro :term:`configuration
file`.
@@ -163,7 +163,7 @@ be consistent and correct with the latest changes.
The simplest form for a PR Service is for a single host development system
that builds the package feed (building system). For this scenario, you can
enable a local PR Service by setting :term:`PRSERV_HOST` in your
-``local.conf`` file in the :term:`Build Directory`::
+:ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`::
PRSERV_HOST = "localhost:0"
@@ -959,7 +959,7 @@ NPM packages:
part of the OpenEmbedded environment. You need to get the package by
cloning the :oe_git:`meta-openembedded </meta-openembedded>`
repository. Be sure to add the path to your local copy
- to your ``bblayers.conf`` file.
+ to your :ref:`structure-build-conf-bblayers.conf` file.
- ``devtool`` cannot detect native libraries in module dependencies.
Consequently, you must manually add packages to your recipe.
@@ -103,7 +103,7 @@ an entire Linux distribution, including the toolchain, from source.
Directory` contains all the files created during the build.
#. **Examine Your Local Configuration File:** When you set up the build
- environment, a local configuration file named ``local.conf`` becomes
+ environment, a local configuration file named :ref:`structure-build-conf-local.conf` becomes
available in a ``conf`` sub-directory of the :term:`Build Directory`. For
this example, the defaults are set to build for a ``qemux86-64`` target,
which is suitable for emulation. The package manager used is set to the RPM
@@ -96,14 +96,14 @@ The following steps describe how to set up the AUH utility:
undesirably.
#. *Make Configurations in Your Local Configuration File:* Several
- settings are needed in the ``local.conf`` file in the build
+ settings are needed in the :ref:`structure-build-conf-local.conf` file in the build
directory you just created for AUH. Make these following
configurations:
- If you want to enable :ref:`Build
History <dev-manual/build-quality:maintaining build output quality with \`\`buildhistory\`\`>`,
which is optional, you need the following lines in the
- ``conf/local.conf`` file::
+ :ref:`structure-build-conf-local.conf` file::
INHERIT =+ "buildhistory"
BUILDHISTORY_COMMIT = "1"
@@ -38,7 +38,7 @@ follows:
- There is support for large images.
-To use the x32 psABI, you need to edit your ``conf/local.conf``
+To use the x32 psABI, you need to edit your :ref:`structure-build-conf-local.conf`
configuration file as follows::
MACHINE = "qemux86-64"
@@ -93,7 +93,7 @@ section:
#. *Inform the BitBake Build Environment About Your Layer:* As directed
when you created your layer, you need to add the layer to the
:term:`BBLAYERS` variable in the
- ``bblayers.conf`` file as follows::
+ :ref:`structure-build-conf-bblayers.conf` file as follows::
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
@@ -148,7 +148,7 @@ section:
#. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is
set to "qemux86-64", which is fine if you are building for the QEMU emulator
in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE`
- variable appropriately in your ``conf/local.conf`` file found in the
+ variable appropriately in your :ref:`structure-build-conf-local.conf` file found in the
:term:`Build Directory` (i.e. ``bitbake-builds/build`` in this example).
Also, since you are preparing to work on the kernel image, you need
@@ -189,7 +189,7 @@ section:
#. *Inform the BitBake Build Environment About Your Layer:* As directed
when you created your layer, you need to add the layer to the
:term:`BBLAYERS` variable in the
- ``bblayers.conf`` file as follows::
+ :ref:`structure-build-conf-bblayers.conf` file as follows::
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
@@ -835,16 +835,16 @@ Section.
pick up the changes.
#. *Update Your local.conf File to Point to Your Source Files:* In
- addition to your ``local.conf`` file specifying to use
+ addition to your :ref:`structure-build-conf-local.conf` file specifying to use
"kernel-modules" and the "qemux86" machine, it must also point to the
updated kernel source files. Add
:term:`SRC_URI` and
:term:`SRCREV` statements similar
- to the following to your ``local.conf``::
+ to the following to your :ref:`structure-build-conf-local.conf`::
$ cd bitbake-builds/build/conf
- Add the following to the ``local.conf``::
+ Add the following to the :ref:`structure-build-conf-local.conf`::
SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
@@ -859,7 +859,7 @@ Section.
example, the branch is ``standard/base`` and the machine is ``qemux86``.
#. *Build the Image:* With the source modified, your changes staged and
- committed, and the ``local.conf`` file pointing to the kernel files,
+ committed, and the :ref:`structure-build-conf-local.conf` file pointing to the kernel files,
you can now use BitBake to build the image::
$ cd bitbake-builds/build
@@ -1193,7 +1193,7 @@ information on how to use the output as a configuration fragment.
Where do you put your configuration fragment files? You can place these
files in an area pointed to by
:term:`SRC_URI` as directed by your
-``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
+:ref:`structure-build-conf-bblayers.conf` file, which is located in your layer. The OpenEmbedded
build system picks up the configuration and adds it to the kernel's
configuration. For example, suppose you had a set of configuration
options in a file called ``myconfig.cfg``. If you put that file inside a
@@ -12,7 +12,7 @@ Local Configuration
-------------------
Differences include changes for
-:term:`SSTATE_MIRRORS` and ``bblayers.conf``.
+:term:`SSTATE_MIRRORS` and :ref:`structure-build-conf-bblayers.conf`.
.. _migration-1.3-sstate-mirrors:
@@ -42,7 +42,7 @@ The ``meta-yocto`` layer consists of two parts that correspond to the
Poky reference distribution and the reference hardware Board Support
Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``.
When running BitBake for the first time after upgrading, your
-``conf/bblayers.conf`` file will be updated to handle this change and
+:ref:`structure-build-conf-bblayers.conf` file will be updated to handle this change and
you will be asked to re-run or restart for the changes to take effect.
.. _1.3-recipes:
@@ -247,15 +247,15 @@ the :ref:`ref-classes-autotools` or ``autotools_stage`` classes.
``qemu-native`` now builds without SDL-based graphical output support by
default. The following additional lines are needed in your
-``local.conf`` to enable it::
+:ref:`structure-build-conf-local.conf` to enable it::
PACKAGECONFIG_pn-qemu-native = "sdl"
ASSUME_PROVIDED += "libsdl-native"
.. note::
- The default ``local.conf`` contains these statements. Consequently, if you
- are building a headless system and using a default ``local.conf``
+ The default :ref:`structure-build-conf-local.conf` contains these statements. Consequently, if you
+ are building a headless system and using a default :ref:`structure-build-conf-local.conf`
file, you will need comment these two lines out.
.. _migration-1.6-core-image-basic:
@@ -14,10 +14,10 @@ Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf``
The QEMU recipe now uses a number of
:term:`PACKAGECONFIG` options to enable various
optional features. The method used to set defaults for these options
-means that existing ``local.conf`` files will need to be modified to
+means that existing :ref:`structure-build-conf-local.conf` files will need to be modified to
append to :term:`PACKAGECONFIG` for ``qemu-native`` and ``nativesdk-qemu``
instead of setting it. In other words, to enable graphical output for
-QEMU, you should now have these lines in ``local.conf``::
+QEMU, you should now have these lines in :ref:`structure-build-conf-local.conf`::
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
@@ -195,7 +195,7 @@ configuration are now automatically removed from sysroot as well as
removed from any other place managed by shared state. This automatic
cleanup means that the build system now properly handles situations such
as renaming the build system side of recipes, removal of layers from
-``bblayers.conf``, and :term:`DISTRO_FEATURES`
+:ref:`structure-build-conf-bblayers.conf`, and :term:`DISTRO_FEATURES`
changes.
Additionally, work directories for old versions of recipes are now
@@ -251,7 +251,7 @@ The following changes have been made for the Poky distribution:
distribution. The ``meta-yocto-bsp`` layer retains its original name
since it provides reference machines for the Yocto Project and it is
otherwise unrelated to Poky. References to ``meta-yocto`` in your
- ``conf/bblayers.conf`` should automatically be updated, so you should
+ :ref:`structure-build-conf-bblayers.conf` should automatically be updated, so you should
not need to change anything unless you are relying on this naming
elsewhere.
@@ -87,7 +87,7 @@ existing ``classes`` subdirectory will continue to work in any context as before
Other than knowing where to look when manually browsing the class files, this is
not likely to require any changes to your configuration. However, if in your
configuration you were using some classes in the incorrect context, you will now
-receive an error during parsing. For example, the following in ``local.conf`` will
+receive an error during parsing. For example, the following in :ref:`structure-build-conf-local.conf` will
now cause an error::
INHERIT += "testimage"
@@ -164,7 +164,7 @@ Additionally, the :term:`LAYERSERIES_COMPAT` value for the devtool workspace
layer is now set at the time of creation, thus if you upgrade with the
workspace layer enabled and you wish to retain it, you will need to manually
update the :term:`LAYERSERIES_COMPAT` value in ``workspace/conf/layer.conf``
-(or remove the path from :term:`BBLAYERS` in ``conf/bblayers.conf`` and
+(or remove the path from :term:`BBLAYERS` in :ref:`structure-build-conf-bblayers.conf` and
delete/move the ``workspace`` directory out of the way if you no longer
need it).
@@ -183,7 +183,7 @@ possibly Internet reachable network interfaces. Thus, in this
release we limit qemu port forwarding to localhost (127.0.0.1).
However, if you need the qemu machine to be reachable from the
-network, then it can be enabled via ``conf/local.conf`` or machine
+network, then it can be enabled via :ref:`structure-build-conf-local.conf` or machine
config variable ``QB_SLIRP_OPT``::
QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::2222-:22"
@@ -242,7 +242,7 @@ New Features / Enhancements in 4.2
- bitbake-layers improvements:
- ``layerindex-fetch``: checkout layer(s) branch when clone exists
- - ``create``: add ``-a``/``--add-layer option`` to add layer to ``bblayers.conf`` after creating layer
+ - ``create``: add ``-a``/``--add-layer option`` to add layer to :ref:`structure-build-conf-bblayers.conf` after creating layer
- ``show-layers``: improve output layout
- Other BitBake improvements:
@@ -383,7 +383,7 @@ New Features / Enhancements in |yocto-ver|
was left off in the previous execution.
- ``knotty`` now hints the user if :term:`MACHINE` was not set in
- the ``local.conf`` file.
+ the :ref:`structure-build-conf-local.conf` file.
- ``utils``: add Go mod h1 checksum support, specific to Go modules. Use
with ``goh1``.
@@ -451,7 +451,7 @@ New Features / Enhancements in |yocto-ver|
- Share :ref:`overview-manual/concepts:Shared State` by default between
builds, by adding a definition for :term:`SSTATE_DIR` and
- :term:`BB_HASHSERVE_DB_DIR` in the ``site.conf`` file created by
+ :term:`BB_HASHSERVE_DB_DIR` in the :ref:`structure-build-conf-auto.conf` file created by
:ref:`bitbake:ref-bbsetup-command-init`
(:bitbake_rev:`a70c336790a9188aae67975fac6ca13579ad1d3e`)
@@ -273,23 +273,23 @@ Here is a non-exhaustive list:
.. note::
- Configurations set in the ``conf/local.conf`` file can also be set
- in the ``conf/site.conf`` and ``conf/auto.conf`` configuration files.
+ Configurations set in the :ref:`structure-build-conf-local.conf` file can also be set
+ in the :ref:`structure-build-conf-site.conf` and :ref:`structure-build-conf-auto.conf` configuration files.
-The ``bblayers.conf`` file tells BitBake what layers you want considered
+The :ref:`structure-build-conf-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
+working with the :ref:`structure-build-conf-bblayers.conf` file in the
":ref:`dev-manual/layers: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 it yourself. The ``auto.conf`` file is typically
+The files ``site.conf`` and :ref:`structure-build-conf-auto.conf` are not created by the
+environment initialization script. If you want the :ref:`structure-build-conf-auto.conf` file,
+you need to create it yourself. The :ref:`structure-build-conf-auto.conf` file is typically
created by an autobuilder:
-- *site.conf:* You can use the ``conf/site.conf`` configuration
+- *site.conf:* You can use the :ref:`structure-build-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
@@ -298,7 +298,7 @@ created by an autobuilder:
- *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``
+ you would find in the :ref:`structure-build-conf-local.conf` or the :ref:`structure-build-conf-site.conf`
files.
You can edit all configuration files to further define any particular
@@ -309,16 +309,16 @@ When you launch your build with the ``bitbake target`` command, BitBake
sorts out the configurations to ultimately define your build
environment. It is important to understand that the
:term:`OpenEmbedded Build System` reads the
-configuration files in a specific order: ``site.conf``, ``auto.conf``,
-and ``local.conf``. And, the build system applies the normal assignment
+configuration files in a specific order: ``site.conf``, :ref:`structure-build-conf-auto.conf`,
+and :ref:`structure-build-conf-local.conf`. And, the build system applies the normal assignment
statement rules as described in the
":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" 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.
+example, if the :ref:`structure-build-conf-auto.conf` file and the ``local.conf`` set variable1
+to different values, because the build system parses :ref:`structure-build-conf-local.conf`
+after :ref:`structure-build-conf-auto.conf`, variable1 is assigned the value from the
+:ref:`structure-build-conf-local.conf` file.
Metadata, Machine Configuration, and Policy Configuration
---------------------------------------------------------
@@ -389,7 +389,7 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers."
found in the OpenEmbedded Layer Index. Such layers are either
deprecated or experimental in nature.
-BitBake uses the ``conf/bblayers.conf`` file, which is part of the user
+BitBake uses the :ref:`structure-build-conf-bblayers.conf` file, which is part of the user
configuration, to find what layers it should be using as part of the
build.
@@ -400,7 +400,7 @@ A distribution layer provides policy configurations for your
distribution. Best practices dictate that you isolate these types of
configurations into their own layer. Settings you provide in
``conf/distro/distro.conf`` override similar settings that BitBake finds
-in your ``conf/local.conf`` file in the :term:`Build Directory`.
+in your :ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`.
The following list provides some explanation and references for what you
typically find in a distribution layer (recall that
@@ -538,7 +538,7 @@ source tree used by the group).
The canonical method through which to include a local project is to use the
:ref:`ref-classes-externalsrc` class to include that local project. You use
-either ``local.conf`` or a recipe's append file to override or set the
+either :ref:`structure-build-conf-local.conf` or a recipe's append file to override or set the
recipe to point to the local directory from which to fetch the source.
Source Control Managers (Optional)
@@ -43,7 +43,7 @@ an ``sdk`` image, perhaps one of::
$ bitbake core-image-rt-sdk
Alternatively, you can add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` line in
-your ``local.conf`` file::
+your :ref:`structure-build-conf-local.conf` file::
EXTRA_IMAGE_FEATURES:append = " tools-profile"
@@ -59,7 +59,7 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.:
You can prevent that by setting the
:term:`INHIBIT_PACKAGE_STRIP`
- variable to "1" in your ``local.conf`` when you build the image::
+ variable to "1" in your :ref:`structure-build-conf-local.conf` when you build the image::
INHIBIT_PACKAGE_STRIP = "1"
@@ -69,11 +69,11 @@ If you've already built a stripped image, you can generate debug
packages (xxx-dbg) which you can manually install as needed.
To generate debug info for packages, you can add ``dbg-pkgs`` to
-:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example::
+:term:`EXTRA_IMAGE_FEATURES` in :ref:`structure-build-conf-local.conf`. For example::
EXTRA_IMAGE_FEATURES:append = " dbg-pkgs"
Additionally, in order to generate the right type of debug info, we also need to
-set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
+set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the :ref:`structure-build-conf-local.conf` file::
PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
@@ -2708,7 +2708,7 @@ It is used to generate a JSON specification file from the features listed in
The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present
on the host system so that users can be notified of potential problems
that might affect their build. The class also performs basic user
-configuration checks from the ``local.conf`` configuration file to
+configuration checks from the :ref:`structure-build-conf-local.conf` configuration file to
prevent common mistakes that cause build failures. Distribution policy
usually determines whether to include this class.
@@ -312,7 +312,7 @@ the layer into which to write an append file::
The ``*.bbappend`` file is created at the
appropriate path within the specified layer directory, which may or may
-not be in your ``bblayers.conf`` file. If an append file already exists,
+not be in your :ref:`structure-build-conf-bblayers.conf` file. If an append file already exists,
the command updates it appropriately.
.. _devtool-checking-on-the-upgrade-status-of-a-recipe:
@@ -116,7 +116,7 @@ and so forth.)
This directory adds additional recipes and append files used by the
OpenEmbedded selftests to verify the behavior of the build system. You
-do not have to add this layer to your ``bblayers.conf`` file unless you
+do not have to add this layer to your :ref:`structure-build-conf-bblayers.conf` file unless you
want to run the selftests.
.. _structure-meta-skeleton:
@@ -310,7 +310,7 @@ file, it is recommended to put them into a distro :term:`configuration file`, or
to create layer :term:`configuration fragments <Configuration Fragment>` from
changes made here.
-The :term:`OpenEmbedded Build System` can create the ``local.conf`` file from a
+The :term:`OpenEmbedded Build System` can create the :ref:`structure-build-conf-local.conf` file from a
``local.conf.sample`` file when you ``source`` the top-level build environment
setup script :ref:`structure-core-script`.
@@ -343,7 +343,7 @@ file, it uses ``sed`` to substitute final
This configuration file defines
:ref:`layers <dev-manual/layers:understanding and creating layers>`,
which are directory trees, traversed (or walked) by BitBake. The
-``bblayers.conf`` file uses the :term:`BBLAYERS`
+:ref:`structure-build-conf-bblayers.conf` file uses the :term:`BBLAYERS`
variable to list the layers BitBake tries to find.
The OpenEmbedded build system can create it from a ``bblayers.conf.sample`` file
@@ -382,7 +382,7 @@ want to access downloaded files (:term:`DL_DIR`).
This file can be shared for multiple build directories. For example,
:doc:`bitbake-setup <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`
makes the :ref:`structure-build-conf-site.conf` file a symbolic link to a common
-``site.conf`` file::
+:ref:`structure-build-conf-auto.conf` file::
├── poky-master-poky-distro_poky-machine_qemux86-64/
│ └── build/
@@ -831,9 +831,9 @@ For reference information on classes, see the
This directory contains the core set of configuration files that start
from ``bitbake.conf`` and from which all other configuration files are
included. See the include statements at the end of the ``bitbake.conf``
-file and you will note that even ``local.conf`` is loaded from there.
+file and you will note that even :ref:`structure-build-conf-local.conf` is loaded from there.
While ``bitbake.conf`` sets up the defaults, you can often override
-these by using the (``local.conf``) file, machine file or the
+these by using the (:ref:`structure-build-conf-local.conf`) file, machine file or the
distribution configuration file.
.. _structure-meta-conf-machine:
@@ -266,11 +266,11 @@ universal, the list includes them just in case:
:term:`Container Layer`
A flexible definition that typically refers to a single Git checkout
which contains multiple (and typically related) sub-layers which can
- be included independently in your project's ``bblayers.conf`` file.
+ be included independently in your project's :ref:`structure-build-conf-bblayers.conf` file.
In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
- so you would never explicitly include it in a ``bblayers.conf`` file;
+ so you would never explicitly include it in a :ref:`structure-build-conf-bblayers.conf` file;
rather, you would include any number of its layer subdirectories, such as
:oe_git:`meta-oe </meta-openembedded/tree/meta-oe>`, :oe_git:`meta-python
</meta-openembedded/tree/meta-python>` and so on.
@@ -279,7 +279,7 @@ universal, the list includes them just in case:
:yocto_git:`meta-security </meta-security>`)
have a top-level directory that is itself an actual layer, as well as
a variety of sub-layers, both of which could be included in your
- ``bblayers.conf`` file.
+ :ref:`structure-build-conf-bblayers.conf` file.
In either case, the phrase "container layer" is simply used to describe
a directory structure which contains multiple valid OpenEmbedded layers.
@@ -432,7 +432,7 @@ system and gives an overview of their function and contents.
you to control the build based on these parameters.
Disk space monitoring is disabled by default. To enable monitoring,
- add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
+ add the :term:`BB_DISKMON_DIRS` variable to your :ref:`structure-build-conf-local.conf` file
found in the :term:`Build Directory`. Use the
following form:
@@ -480,7 +480,7 @@ system and gives an overview of their function and contents.
The first example works only if you also provide the
:term:`BB_DISKMON_WARNINTERVAL`
- variable in the ``conf/local.conf``. This example causes the build
+ variable in the :ref:`structure-build-conf-local.conf`. This example causes the build
system to immediately stop when either the disk space in
``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
below 100 Kbytes. Because two directories are provided with the
@@ -501,7 +501,7 @@ system and gives an overview of their function and contents.
:term:`BB_DISKMON_WARNINTERVAL`
Defines the disk space and free inode warning intervals. To set these
- intervals, define the variable in your ``conf/local.conf`` file in
+ intervals, define the variable in your :ref:`structure-build-conf-local.conf` file in
the :term:`Build Directory`.
If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
@@ -721,7 +721,7 @@ system and gives an overview of their function and contents.
server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
long the BitBake server stays resident between invocations.
- For example, the following statement in your ``local.conf`` file
+ For example, the following statement in your :ref:`structure-build-conf-local.conf` file
instructs the server to be unloaded after 20 seconds of inactivity::
BB_SERVER_TIMEOUT = "20"
@@ -885,7 +885,7 @@ system and gives an overview of their function and contents.
:term:`BBLAYERS`
Lists the layers to enable during the build. This variable is defined
- in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
+ in the :ref:`structure-build-conf-bblayers.conf` configuration file in the :term:`Build Directory`.
Here is an example::
BBLAYERS = " \
@@ -1981,7 +1981,7 @@ system and gives an overview of their function and contents.
:term:`COREBASE_FILES`
Lists files from the :term:`COREBASE` directory that
should be copied other than the layers listed in the
- ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
+ :ref:`structure-build-conf-bblayers.conf` file. The :term:`COREBASE_FILES` variable allows
to copy metadata from the OpenEmbedded build system
into the extensible SDK.
@@ -2626,7 +2626,7 @@ system and gives an overview of their function and contents.
variable.
You can set this directory by defining the :term:`DL_DIR` variable in the
- ``conf/local.conf`` file. This directory is self-maintaining and you
+ :ref:`structure-build-conf-local.conf` file. This directory is self-maintaining and you
should not have to touch it. By default, the directory is
``downloads`` in the :term:`Build Directory`::
@@ -2819,7 +2819,7 @@ system and gives an overview of their function and contents.
Directs BitBake to exclude a recipe from world builds (i.e.
``bitbake world``). During world builds, BitBake locates, parses and
builds all recipes found in every layer exposed in the
- ``bblayers.conf`` configuration file.
+ :ref:`structure-build-conf-bblayers.conf` configuration file.
To exclude a recipe from a world build using this variable, set the
variable to "1" in the recipe.
@@ -3868,7 +3868,7 @@ system and gives an overview of their function and contents.
If you specifically remove the locale ``en_US.UTF-8``, you must set
:term:`IMAGE_LINGUAS` appropriately.
- You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file for
+ You can set :term:`GLIBC_GENERATE_LOCALES` in your :ref:`structure-build-conf-local.conf` file for
local testing or in your distro :term:`configuration file`.
By default, all locales are generated::
@@ -4327,7 +4327,7 @@ system and gives an overview of their function and contents.
:term:`IMAGE_FEATURES`
The primary list of features to include in an image. Typically, you
configure this variable in an image recipe. Although you can use this
- variable from your ``local.conf`` file, which is found in the
+ variable from your :ref:`structure-build-conf-local.conf` file, which is found in the
:term:`Build Directory`, best practices dictate that you do
not.
@@ -4415,7 +4415,7 @@ system and gives an overview of their function and contents.
- Using :term:`IMAGE_INSTALL` with the
:ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
- BitBake operator within the ``/conf/local.conf`` file or from
+ BitBake operator within the :ref:`structure-build-conf-local.conf` file or from
within an image recipe is not recommended. Use of this operator in
these ways can cause ordering issues. Since
:ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a
@@ -4423,7 +4423,7 @@ system and gives an overview of their function and contents.
:ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
results in unexpected behavior when used within
- ``conf/local.conf``. Furthermore, the same operation from within an
+ :ref:`structure-build-conf-local.conf`. Furthermore, the same operation from within an
image recipe may or may not succeed depending on the specific
situation. In both these cases, the behavior is contrary to how
most users expect the ``+=`` operator to work.
@@ -7074,7 +7074,7 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your :ref:`structure-build-conf-local.conf` file::
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7103,7 +7103,7 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your :ref:`structure-build-conf-local.conf` file::
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7132,7 +7132,7 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your :ref:`structure-build-conf-local.conf` file::
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7507,7 +7507,7 @@ system and gives an overview of their function and contents.
places you in the right location so that you can manually resolve the
conflicts.
- Set this variable in your ``local.conf`` file.
+ Set this variable in your :ref:`structure-build-conf-local.conf` file.
:term:`PATCHTOOL`
Specifies the utility used to apply patches for a recipe during the
@@ -7898,7 +7898,7 @@ system and gives an overview of their function and contents.
Typically, you could add a specific server for the build system to
attempt before any others by adding something like the following to
- the ``local.conf`` configuration file in the
+ the :ref:`structure-build-conf-site.conf` configuration file in the
:term:`Build Directory`::
PREMIRRORS:prepend = "\
@@ -8629,7 +8629,7 @@ system and gives an overview of their function and contents.
ROOT_HOME ?= "/root"
You can also override the default by setting the variable in your distro
- configuration or in the ``local.conf`` file.
+ configuration or in the :ref:`structure-build-conf-local.conf` file.
:term:`ROOTFS`
Indicates a filesystem image to include as the root filesystem.
@@ -9382,7 +9382,7 @@ system and gives an overview of their function and contents.
build the recipe.
To prevent a recipe from being built, use the :term:`SKIP_RECIPE`
- variable in your ``local.conf`` file or distribution configuration.
+ variable in your :ref:`structure-build-conf-local.conf` file or distribution configuration.
Here is an example which prevents ``myrecipe`` from being built::
SKIP_RECIPE[myrecipe] = "Not supported by our organization."
@@ -10961,8 +10961,8 @@ system and gives an overview of their function and contents.
The layer's ``README`` file contains information on how to use the
Sourcery G++ Toolchain as an external toolchain. You will have to
- add the layer to your ``bblayers.conf`` file and then set the
- :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to
+ add the layer to your :ref:`structure-build-conf-bblayers.conf` file and then set the
+ :term:`EXTERNAL_TOOLCHAIN` variable in your :ref:`structure-build-conf-local.conf` file to
the location of the toolchain.
The fundamentals used for this example apply to any external
@@ -74,7 +74,7 @@ Local
-----
This section lists variables whose configuration context is the local
-configuration through the ``local.conf`` file.
+configuration through the :ref:`structure-build-conf-local.conf` file.
- :term:`DISTRO` (can also be set by the :ref:`ref-fragments-builtin-core-distro`
:term:`built-in fragment`)
@@ -53,7 +53,7 @@ build system applies them against :ref:`structure-build-conf-local.conf` and
class.
Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
-appended to the end of ``conf/local.conf`` within the produced SDK,
+appended to the end of :ref:`structure-build-conf-local.conf` within the produced SDK,
without any filtering. The ``sdk-extra.conf`` file is particularly
useful if you want to set a variable value just for the SDK and not the
OpenEmbedded build system used to create the SDK.
@@ -114,7 +114,7 @@ adjustments:
- If you have adjusted the list of files and directories that appear in
:term:`COREBASE` (other than
- layers that are enabled through ``bblayers.conf``), then you must
+ layers that are enabled through :ref:`structure-build-conf-bblayers.conf`), then you must
list these files in
:term:`COREBASE_FILES` so
that the files are copied into the SDK.
@@ -287,7 +287,7 @@ source, you need to do a number of things:
SDK and the SDK itself (i.e. the mirror is accessible in both
places or it will fail quickly on the OpenEmbedded build system
side, and its contents will not interfere with the build), then
- you can set the variable in your ``local.conf`` or custom distro
+ you can set the variable in your :ref:`structure-build-conf-local.conf` or custom distro
configuration file. You can then pass the variable to the SDK by
adding the following:
@@ -80,7 +80,7 @@ your build output more secure. The security flags are in the
Depending on the recipe, certain security flags are enabled and
disabled by default.
-Use the following line in your ``local.conf`` file or in your custom
+Use the following line in your :ref:`structure-build-conf-local.conf` file or in your custom
distro :term:`configuration file` to enable the security compiler and
linker flags for your build::
@@ -223,7 +223,7 @@ The final thing you need to do when setting :term:`TEST_TARGET` to
"SystemdbootTarget" is to set up the test image:
#. *Set up your local.conf file:* Make sure you have the following
- statements in your ``local.conf`` file::
+ statements in your :ref:`structure-build-conf-local.conf` file::
IMAGE_FSTYPES += "tar.gz"
IMAGE_CLASSES += "testimage"
@@ -244,7 +244,7 @@ power:
:term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host
and does power cycling. The test code passes one argument to that
command: off, on or cycle (off then on). Here is an example that
- could appear in your ``local.conf`` file::
+ could appear in your :ref:`structure-build-conf-local.conf` file::
TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
@@ -318,7 +318,7 @@ You can start the tests automatically or manually:
- *Automatically running tests:* To run the tests automatically after the
OpenEmbedded build system successfully creates an image, first set the
- :term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the
+ :term:`TESTIMAGE_AUTO` variable to "1" in your :ref:`structure-build-conf-local.conf` file in the
:term:`Build Directory`::
TESTIMAGE_AUTO = "1"
@@ -330,7 +330,7 @@ You can start the tests automatically or manually:
- *Manually running tests:* To manually run the tests, first globally
inherit the :ref:`ref-classes-testimage` class by editing your
- ``local.conf`` file::
+ :ref:`structure-build-conf-local.conf` file::
IMAGE_CLASSES += "testimage"
@@ -346,7 +346,7 @@ individual tests. Tests are usually grouped together by the area tested
You can add tests to any layer provided you place them in the proper
area and you extend :term:`BBPATH` in
-the ``local.conf`` file as normal. Be sure that tests reside in
+the :ref:`structure-build-conf-local.conf` file as normal. Be sure that tests reside in
``layer/lib/oeqa/runtime/cases``.
.. note::
@@ -356,7 +356,7 @@ the ``local.conf`` file as normal. Be sure that tests reside in
You can change the set of tests run by appending or overriding
:term:`TEST_SUITES` variable in
-``local.conf``. Each name in :term:`TEST_SUITES` represents a required test
+:ref:`structure-build-conf-local.conf`. Each name in :term:`TEST_SUITES` represents a required test
for the image. Test modules named within :term:`TEST_SUITES` cannot be
skipped even if a test is not suitable for an image (e.g. running the
RPM tests on an image without ``rpm``). Appending "auto" to
@@ -401,7 +401,7 @@ test execution off to a scheduler. You can only export tests that are
defined in :term:`TEST_SUITES`.
If your image is already built, make sure the following are set in your
-``local.conf`` file::
+:ref:`structure-build-conf-local.conf` file::
IMAGE_CLASSES += "testexport"
TEST_TARGET_IP = "IP-address-for-the-test-target"
@@ -58,7 +58,7 @@ Combining these two entries you can see that ``qemux86-64`` is a three step
build where ``bitbake BBTARGETS`` would be run, then ``bitbake SANITYTARGETS``
for each step; all for ``MACHINE="qemux86-64"`` but with differing
:term:`SDKMACHINE` settings. In step 1, an extra variable is added to the
-``auto.conf`` file to enable wic image generation.
+:ref:`structure-build-conf-auto.conf` file to enable wic image generation.
While not every detail of this is covered here, you can see how the
template mechanism allows quite complex configurations to be built up
@@ -222,7 +222,7 @@ following:
``bitbake-layers add-layer`` command (logging as stepXa)
#. Call the ``scripts/setup-config`` script to generate the necessary
- ``auto.conf`` configuration file for the build
+ :ref:`structure-build-conf-auto.conf` configuration file for the build
#. Run the ``bitbake BBTARGETS`` command (logging as stepXb)
@@ -32,7 +32,7 @@ through a :wikipedia:`REST <Representational_state_transfer>`
API, store the information about the layers in the Toaster database, and
then show the information to users. Users are then able to view that
information and build layers from Toaster itself without having to
-clone or edit the BitBake layers configuration file ``bblayers.conf``.
+clone or edit the BitBake layers configuration file :ref:`structure-build-conf-bblayers.conf`.
Tying a layer source into Toaster is convenient when you have many
custom layers that need to be built on a regular basis by a community of
@@ -66,7 +66,7 @@ Transitioning to a custom environment for systems development
64-bit x86-based machine, copy the conf/intel-corei7-64 definition and give
the machine a relevant name (think board name, not product name). Make sure
the layer configuration is dependent on the ``meta-intel`` layer (or at least,
- ``meta-intel`` remains in your ``bblayers.conf`` file). Now you can put your custom BSP
+ ``meta-intel`` remains in your :ref:`structure-build-conf-bblayers.conf` file). Now you can put your custom BSP
settings into your layer and you can re-use it for different applications.
#. **Write your own recipe to build additional software support that isn't
Locate the hardcoded strings for configuration files such as local.conf, bblayers.conf and such, and replace them with a reference link to our structure.rst document, which contains information about the purpose of these files. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/brief-yoctoprojectqs/index.rst | 4 +-- documentation/bsp-manual/bsp.rst | 6 ++-- documentation/dev-manual/bblock.rst | 2 +- documentation/dev-manual/build-quality.rst | 4 +-- documentation/dev-manual/building.rst | 6 ++-- documentation/dev-manual/custom-distribution.rst | 8 ++--- .../custom-template-configuration-directory.rst | 8 ++--- documentation/dev-manual/customizing-images.rst | 6 ++-- documentation/dev-manual/debugging.rst | 16 ++++----- documentation/dev-manual/device-manager.rst | 4 +-- documentation/dev-manual/devtool.rst | 4 +-- documentation/dev-manual/disk-space.rst | 2 +- documentation/dev-manual/error-reporting-tool.rst | 6 ++-- documentation/dev-manual/external-toolchain.rst | 2 +- documentation/dev-manual/layers.rst | 22 ++++++------ documentation/dev-manual/licenses.rst | 8 ++--- documentation/dev-manual/limiting-resources.rst | 2 +- documentation/dev-manual/multiconfig.rst | 10 +++--- documentation/dev-manual/packages.rst | 4 +-- documentation/dev-manual/poky-manual-setup.rst | 2 +- documentation/dev-manual/upgrading-recipes.rst | 4 +-- documentation/dev-manual/x32-psabi.rst | 2 +- documentation/kernel-dev/common.rst | 16 ++++----- documentation/migration-guides/migration-1.3.rst | 4 +-- documentation/migration-guides/migration-1.6.rst | 6 ++-- documentation/migration-guides/migration-1.7.rst | 4 +-- documentation/migration-guides/migration-2.0.rst | 2 +- documentation/migration-guides/migration-2.1.rst | 2 +- documentation/migration-guides/migration-4.1.rst | 2 +- documentation/migration-guides/migration-4.2.rst | 4 +-- .../migration-guides/release-notes-4.2.rst | 2 +- .../migration-guides/release-notes-5.2.rst | 2 +- .../migration-guides/release-notes-6.0.rst | 2 +- documentation/overview-manual/concepts.rst | 36 +++++++++---------- documentation/profile-manual/intro.rst | 8 ++--- documentation/ref-manual/classes.rst | 2 +- documentation/ref-manual/devtool-reference.rst | 2 +- documentation/ref-manual/structure.rst | 12 +++---- documentation/ref-manual/terms.rst | 6 ++-- documentation/ref-manual/variables.rst | 42 +++++++++++----------- documentation/ref-manual/varlocality.rst | 2 +- documentation/sdk-manual/appendix-customizing.rst | 6 ++-- documentation/security-manual/securing-images.rst | 2 +- documentation/test-manual/runtime-testing.rst | 14 ++++---- .../test-manual/understand-autobuilder.rst | 4 +-- documentation/toaster-manual/reference.rst | 2 +- .../transitioning-to-a-custom-environment.rst | 2 +- 47 files changed, 159 insertions(+), 159 deletions(-)