diff options
Diffstat (limited to 'documentation/dev-manual/custom-template-configuration-directory.rst')
-rw-r--r-- | documentation/dev-manual/custom-template-configuration-directory.rst | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/documentation/dev-manual/custom-template-configuration-directory.rst b/documentation/dev-manual/custom-template-configuration-directory.rst new file mode 100644 index 0000000000..06fcada822 --- /dev/null +++ b/documentation/dev-manual/custom-template-configuration-directory.rst | |||
@@ -0,0 +1,52 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Creating a Custom Template Configuration Directory | ||
4 | ************************************************** | ||
5 | |||
6 | If you are producing your own customized version of the build system for | ||
7 | use by other users, you might want to provide a custom build configuration | ||
8 | that includes all the necessary settings and layers (i.e. ``local.conf`` and | ||
9 | ``bblayers.conf`` that are created in a new :term:`Build Directory`) and a custom | ||
10 | message that is shown when setting up the build. This can be done by | ||
11 | creating one or more template configuration directories in your | ||
12 | custom distribution layer. | ||
13 | |||
14 | This can be done by using ``bitbake-layers save-build-conf``:: | ||
15 | |||
16 | $ bitbake-layers save-build-conf ../../meta-alex/ test-1 | ||
17 | NOTE: Starting bitbake server... | ||
18 | NOTE: Configuration template placed into /srv/work/alex/meta-alex/conf/templates/test-1 | ||
19 | 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 | ||
20 | You can try out the configuration with | ||
21 | TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 | ||
22 | |||
23 | The above command takes the config files from the currently active :term:`Build Directory` under ``conf``, | ||
24 | replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies | ||
25 | the config files into a specified layer under a specified template name. | ||
26 | |||
27 | To use those saved templates as a starting point for a build, users should point | ||
28 | to one of them with :term:`TEMPLATECONF` environment variable:: | ||
29 | |||
30 | TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 | ||
31 | |||
32 | The OpenEmbedded build system uses the environment variable | ||
33 | :term:`TEMPLATECONF` to locate the directory from which it gathers | ||
34 | configuration information that ultimately ends up in the | ||
35 | :term:`Build Directory` ``conf`` directory. | ||
36 | |||
37 | If :term:`TEMPLATECONF` is not set, the default value is obtained | ||
38 | from ``.templateconf`` file that is read from the same directory as | ||
39 | ``oe-init-build-env`` script. For the Poky reference distribution this | ||
40 | would be:: | ||
41 | |||
42 | TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf/templates/default} | ||
43 | |||
44 | If you look at a configuration template directory, you will | ||
45 | see the ``bblayers.conf.sample``, ``local.conf.sample``, ``conf-summary.txt`` and | ||
46 | ``conf-notes.txt`` files. The build system uses these files to form the | ||
47 | respective ``bblayers.conf`` file, ``local.conf`` file, and show | ||
48 | users usage information about the build they're setting up | ||
49 | when running the ``oe-init-build-env`` setup script. These can be | ||
50 | edited further if needed to improve or change the build configurations | ||
51 | available to the users, and provide useful summaries and detailed usage notes. | ||
52 | |||