From 4a433280ab82c46ce2e9152ef392c3b06399d6f9 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Thu, 30 Oct 2025 15:13:02 +0100 Subject: [PATCH] ref-manual/structure.rst: update the description of local.conf and bblayers.conf The local.conf file is now mostly empty with the default way of setting up the environment (with bitbake-setup), and this file is meant to hold local user configurations, rather than an extensive list of variables. Adjust the description to reflect the intended way of using this configuration file. Also, for both local.conf and bblayers.conf, rephrase the current usage of the template files (.sample files) to _not_ imply that it is the default way the OpenEmbedded build system sets things up. (From yocto-docs rev: 24f24d07fd688825b2ec39dcf0daf8203577f87a) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/ref-manual/structure.rst | 32 +++++++++++--------------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst index 2640f461d6..a2f2fd4507 100644 --- a/documentation/ref-manual/structure.rst +++ b/documentation/ref-manual/structure.rst @@ -269,22 +269,19 @@ This directory should not be shared between builds. ``build/conf/local.conf`` ------------------------- -This configuration file contains all the local user configurations for -your build environment. The ``local.conf`` file contains documentation -on the various configuration options. Any variable set here overrides -any variable set elsewhere within the environment unless that variable -is hard-coded within a file (e.g. by using '=' instead of '?='). Some -variables are hard-coded for various reasons but such variables are -relatively rare. +This configuration file contains the local user configurations for the build +environment. -At a minimum, you would normally edit this file to select the target -:term:`MACHINE`, which package types you wish to use -(:term:`PACKAGE_CLASSES`), and the location from -which you want to access downloaded files (:term:`DL_DIR`). +You could for example experiment with setting (or adding to) +:term:`DISTRO_FEATURES` or :term:`IMAGE_FEATURES`, or adjust build +configurations for specific recipes by setting the :term:`PACKAGECONFIG` +variables for them. If you would like to publish and share changes made to this +file, it is recommended to put them into a distro :term:`configuration file`, or +to create layer :term:`configuration fragments ` from +changes made here. -If ``local.conf`` is not present when you start the build, the -OpenEmbedded build system creates it from ``local.conf.sample`` when you -``source`` the top-level build environment setup script +The :term:`OpenEmbedded Build System` can create it from a ``local.conf.sample`` +file when you ``source`` the top-level build environment setup script :ref:`structure-core-script`. The source ``local.conf.sample`` file used depends on the @@ -321,12 +318,11 @@ which are directory trees, traversed (or walked) by BitBake. The ``bblayers.conf`` file uses the :term:`BBLAYERS` variable to list the layers BitBake tries to find. -If ``bblayers.conf`` is not present when you start the build, the -OpenEmbedded build system creates it from ``bblayers.conf.sample`` when -you ``source`` the top-level build environment setup script (i.e. +The OpenEmbedded build system can create it from a ``bblayers.conf.sample`` file +when you ``source`` the top-level build environment setup script (i.e. :ref:`structure-core-script`). -As with the ``local.conf`` file, the source ``bblayers.conf.sample`` +As with the :ref:`structure-build-conf-local.conf` file, the source ``bblayers.conf.sample`` file used depends on the :term:`TEMPLATECONF` script variable, which defaults to ``meta-poky/conf/templates/default`` when you are building from the Yocto Project development environment, and to ``meta/conf/templates/default`` when you are