diff options
author | Alexander Kanavin <alex.kanavin@gmail.com> | 2022-09-11 19:26:08 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2022-09-24 17:44:56 +0100 |
commit | cec7d36a8ab1f2f1fe13a8d01074f2ff27ad8564 (patch) | |
tree | 4eb98cba7e05560574e33fc88a044389d9be4c98 | |
parent | c66e7b9479c66b2ea1a174e124eb3b9d4e3fa094 (diff) | |
download | poky-cec7d36a8ab1f2f1fe13a8d01074f2ff27ad8564.tar.gz |
dev-manual: common-tasks.rst: rewrite the section about configuration templates
This now includes a description about how to create a template
with the newly added tooling, and drops the description
of .templateconf as a way to point to a custom template
(which is not correct: .templateconf is used only to point to a default
template in poky or core when TEMPLATECONF is not specified).
(From yocto-docs rev: d8e43d4ff4d6a0a4557d5dcedf11c1e45a223e72)
Signed-off-by: Alexander Kanavin <alex@linutronix.de>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/common-tasks.rst | 92 |
1 files changed, 36 insertions, 56 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 837824be38..cfbd0bef02 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst | |||
@@ -6466,71 +6466,51 @@ Creating a Custom Template Configuration Directory | |||
6466 | ================================================== | 6466 | ================================================== |
6467 | 6467 | ||
6468 | If you are producing your own customized version of the build system for | 6468 | If you are producing your own customized version of the build system for |
6469 | use by other users, you might want to customize the message shown by the | 6469 | use by other users, you might want to provide a custom build configuration |
6470 | setup script or you might want to change the template configuration | 6470 | that includes all the necessary settings and layers (i.e. ``local.conf`` and |
6471 | files (i.e. ``local.conf`` and ``bblayers.conf``) that are created in a | 6471 | ``bblayers.conf`` that are created in a new build directory) and a custom |
6472 | new build directory. | 6472 | message that is shown when setting up the build. This can be done by |
6473 | creating one or more template configuration directories in your | ||
6474 | custom distribution layer. | ||
6473 | 6475 | ||
6474 | The OpenEmbedded build system uses the environment variable | 6476 | This can be done by using ``bitbake-layers save-build-conf``:: |
6475 | :term:`TEMPLATECONF` to locate the directory from which it gathers | ||
6476 | configuration information that ultimately ends up in the | ||
6477 | :term:`Build Directory` ``conf`` directory. | ||
6478 | By default, :term:`TEMPLATECONF` is set as follows in the ``poky`` | ||
6479 | repository:: | ||
6480 | 6477 | ||
6481 | TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} | 6478 | $ bitbake-layers save-build-conf ../../meta-alex/ test-1 |
6482 | 6479 | NOTE: Starting bitbake server... | |
6483 | This is the | 6480 | NOTE: Configuration template placed into /srv/work/alex/meta-alex/conf/templates/test-1 |
6484 | directory used by the build system to find templates from which to build | 6481 | Please review the files in there, and particularly provide a configuration description in /srv/work/alex/meta-alex/conf/templates/test-1/conf-notes.txt |
6485 | some key configuration files. If you look at this directory, you will | 6482 | You can try out the configuration with |
6486 | see the ``bblayers.conf.sample``, ``local.conf.sample``, and | 6483 | TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 |
6487 | ``conf-notes.txt`` files. The build system uses these files to form the | ||
6488 | respective ``bblayers.conf`` file, ``local.conf`` file, and display the | ||
6489 | list of BitBake targets when running the setup script. | ||
6490 | |||
6491 | To override these default configuration files with configurations you | ||
6492 | want used within every new Build Directory, simply set the | ||
6493 | :term:`TEMPLATECONF` variable to your directory. The :term:`TEMPLATECONF` | ||
6494 | variable is set in the ``.templateconf`` file, which is in the top-level | ||
6495 | :term:`Source Directory` folder | ||
6496 | (e.g. ``poky``). Edit the ``.templateconf`` so that it can locate your | ||
6497 | directory. | ||
6498 | 6484 | ||
6499 | Best practices dictate that you should keep your template configuration | 6485 | The above command takes the config files from the currently active build directory under ``conf``, |
6500 | directory in your custom distribution layer. For example, suppose you | 6486 | replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies |
6501 | have a layer named ``meta-mylayer`` located in your home directory and | 6487 | the config files into a specified layer under a specified template name. |
6502 | you want your template configuration directory named ``myconf``. | ||
6503 | Changing the ``.templateconf`` as follows causes the OpenEmbedded build | ||
6504 | system to look in your directory and base its configuration files on the | ||
6505 | ``*.sample`` configuration files it finds. The final configuration files | ||
6506 | (i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in | ||
6507 | your Build Directory, but they are based on your ``*.sample`` files. | ||
6508 | :: | ||
6509 | 6488 | ||
6510 | TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} | 6489 | To use those saved templates as a starting point for a build, users should point |
6490 | to one of them with :term:`TEMPLATECONF` environment variable:: | ||
6511 | 6491 | ||
6512 | Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` | 6492 | TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 |
6513 | also resides in the default ``meta-poky/conf`` directory. The script | ||
6514 | that sets up the build environment (i.e. | ||
6515 | :ref:`structure-core-script`) uses this file to | ||
6516 | display BitBake targets as part of the script output. Customizing this | ||
6517 | ``conf-notes.txt`` file is a good way to make sure your list of custom | ||
6518 | targets appears as part of the script's output. | ||
6519 | 6493 | ||
6520 | Here is the default list of targets displayed as a result of running | 6494 | The OpenEmbedded build system uses the environment variable |
6521 | either of the setup scripts:: | 6495 | :term:`TEMPLATECONF` to locate the directory from which it gathers |
6496 | configuration information that ultimately ends up in the | ||
6497 | :term:`Build Directory` ``conf`` directory. | ||
6522 | 6498 | ||
6523 | You can now run 'bitbake <target>' | 6499 | If :term:`TEMPLATECONF` is not set, the default value is obtained |
6500 | from ``.templateconf`` file that is read from the same directory as | ||
6501 | ``oe-init-build-env`` script. For the Poky reference distribution this | ||
6502 | would be:: | ||
6524 | 6503 | ||
6525 | Common targets are: | 6504 | TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf/templates/default} |
6526 | core-image-minimal | ||
6527 | core-image-sato | ||
6528 | meta-toolchain | ||
6529 | meta-ide-support | ||
6530 | 6505 | ||
6531 | Changing the listed common targets is as easy as editing your version of | 6506 | If you look at a configuration template directory, you will |
6532 | ``conf-notes.txt`` in your custom template configuration directory and | 6507 | see the ``bblayers.conf.sample``, ``local.conf.sample``, and |
6533 | making sure you have :term:`TEMPLATECONF` set to your directory. | 6508 | ``conf-notes.txt`` files. The build system uses these files to form the |
6509 | respective ``bblayers.conf`` file, ``local.conf`` file, and show | ||
6510 | users a note about the build they're setting up | ||
6511 | when running the ``oe-init-build-env`` setup script. These can be | ||
6512 | edited further if needed to improve or change the build configurations | ||
6513 | available to the users. | ||
6534 | 6514 | ||
6535 | Conserving Disk Space | 6515 | Conserving Disk Space |
6536 | ===================== | 6516 | ===================== |