| Message ID | 20220911172608.2542076-5-alex@linutronix.de |
|---|---|
| State | New |
| Headers | show |
| Series | [1/5] ref-manual: correct the location of default configuration template | expand |
> -----Original Message----- > From: docs@lists.yoctoproject.org <docs@lists.yoctoproject.org> On Behalf > Of Alexander Kanavin > Sent: den 11 september 2022 18:26 > To: docs@lists.yoctoproject.org > Cc: Alexander Kanavin <alex@linutronix.de> > Subject: [docs] [PATCH 5/5] 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). I do not agree with this sentiment. If you create and distribute a setup similar to Poky (which we do), why would we not change .templateconf to point at our templates? This has been the documented method and the one at least we use for our distribution. Where have you gotten the notion that this is only to be used by OE-Core & Poky? It does not make sense. //Peter > > Signed-off-by: Alexander Kanavin <alex@linutronix.de> > --- > documentation/dev-manual/common-tasks.rst | 92 +++++++++-------------- > 1 file changed, 36 insertions(+), 56 deletions(-) > > diff --git a/documentation/dev-manual/common-tasks.rst > b/documentation/dev-manual/common-tasks.rst > index 6c2df9aa6..eab5648fd 100644 > --- a/documentation/dev-manual/common-tasks.rst > +++ b/documentation/dev-manual/common-tasks.rst > @@ -6463,71 +6463,51 @@ 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 customize the message shown by the > -setup script or you might want to change the template configuration > -files (i.e. ``local.conf`` and ``bblayers.conf``) that are created in a > -new build directory. > +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 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. > > -The OpenEmbedded build system uses the environment variable > -:term:`TEMPLATECONF` to locate the directory from which it gathers > -configuration information that ultimately ends up in the > -:term:`Build Directory` ``conf`` directory. > -By default, :term:`TEMPLATECONF` is set as follows in the ``poky`` > -repository:: > +This can be done by using ``bitbake-layers save-build-conf``: > > - TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} > - > -This is the > -directory used by the build system to find templates from which to build > -some key configuration files. If you look at this directory, you will > -see the ``bblayers.conf.sample``, ``local.conf.sample``, and > -``conf-notes.txt`` files. The build system uses these files to form the > -respective ``bblayers.conf`` file, ``local.conf`` file, and display the > -list of BitBake targets when running the setup script. > - > -To override these default configuration files with configurations you > -want used within every new Build Directory, simply set the > -:term:`TEMPLATECONF` variable to your directory. The :term:`TEMPLATECONF` > -variable is set in the ``.templateconf`` file, which is in the top-level > -:term:`Source Directory` folder > -(e.g. ``poky``). Edit the ``.templateconf`` so that it can locate your > -directory. > + $ bitbake-layers save-build-conf ../../meta-alex/ test-1 > + NOTE: Starting bitbake server... > + NOTE: Configuration template placed into /srv/work/alex/meta- > alex/conf/templates/test-1 > + 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 > + You can try out the configuration with > + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . > /srv/work/alex/poky/oe-init-build-env build-try-test-1 > > -Best practices dictate that you should keep your template configuration > -directory in your custom distribution layer. For example, suppose you > -have a layer named ``meta-mylayer`` located in your home directory and > -you want your template configuration directory named ``myconf``. > -Changing the ``.templateconf`` as follows causes the OpenEmbedded build > -system to look in your directory and base its configuration files on the > -``*.sample`` configuration files it finds. The final configuration files > -(i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in > -your Build Directory, but they are based on your ``*.sample`` files. > -:: > +The above command takes the config files from the currently active build > directory under ``conf\``, > +replaces site-specific paths in bblayers.conf with ##OECORE##-relative > paths, and copies > +the config files into a specified layer under a specified template name. > > - TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} > +To use those saved templates as a starting point for a build, users > should point > +to one of them with :term:`TEMPLATECONF` environment variable: > > -Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` > -also resides in the default ``meta-poky/conf`` directory. The script > -that sets up the build environment (i.e. > -:ref:`structure-core-script`) uses this file to > -display BitBake targets as part of the script output. Customizing this > -``conf-notes.txt`` file is a good way to make sure your list of custom > -targets appears as part of the script's output. > + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . > /srv/work/alex/poky/oe-init-build-env build-try-test-1 > > -Here is the default list of targets displayed as a result of running > -either of the setup scripts:: > +The OpenEmbedded build system uses the environment variable > +:term:`TEMPLATECONF` to locate the directory from which it gathers > +configuration information that ultimately ends up in the > +:term:`Build Directory` ``conf`` directory. > > - You can now run 'bitbake <target>' > +If :term:`TEMPLATECONF` is not set, the default value is obtained > +from ```.templateconf`` file that is read from the same directory as > +`oe-init-build-env` script. For ``poky`` reference distribution this > +would be:: > > - Common targets are: > - core-image-minimal > - core-image-sato > - meta-toolchain > - meta-ide-support > + TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf/templates/default} > > -Changing the listed common targets is as easy as editing your version of > -``conf-notes.txt`` in your custom template configuration directory and > -making sure you have :term:`TEMPLATECONF` set to your directory. > +If you look at a configuration template directory, you will > +see the ``bblayers.conf.sample``, ``local.conf.sample``, and > +``conf-notes.txt`` files. The build system uses these files to form the > +respective ``bblayers.conf`` file, ``local.conf`` file, and show > +users a note 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 > +available to the users. > > Conserving Disk Space > ===================== > -- > 2.30.2
On Tue, 13 Sept 2022 at 19:38, Peter Kjellerstedt <peter.kjellerstedt@axis.com> wrote: > I do not agree with this sentiment. If you create and distribute a setup > similar to Poky (which we do), why would we not change .templateconf to > point at our templates? This has been the documented method and the one > at least we use for our distribution. Where have you gotten the notion > that this is only to be used by OE-Core & Poky? It does not make sense. First we need to find out, where the documentation section that sets the idea is coming from. It was written by Scott R. in 2014: https://git.yoctoproject.org/yocto-docs/commit/?id=c07fb7082fe08387bbc546b2a23620dedc7127b8 from https://bugzilla.yoctoproject.org/show_bug.cgi?id=5895 I believe Scott misunderstood how the whole thing is supposed to work, and never road tested what he had written. You are free to continue to do the .templateconf rewrite, but I do not want to keep it in the docs. It just isn't actually supported, unless you *also* provide a description and tools for 'creating a distribution setup similar to poky' and for doing the actual rewrite, and find someone else except you who's using it (I believe you do this with custom unpublished scripts?). Besides, the only feature it gets you is not having to specify TEMPLATECONF when you have a default choice for it, which is useful, but should be made possible with the setup everyone *actually* uses, which is cloning poky, then adding layers next to it. Alex
> -----Original Message----- > From: Alexander Kanavin <alex.kanavin@gmail.com> > Sent: den 13 september 2022 19:27 > To: Peter Kjellerstedt <peter.kjellerstedt@axis.com> > Cc: docs@lists.yoctoproject.org; Alexander Kanavin <alex@linutronix.de> > Subject: Re: [docs] [PATCH 5/5] common-tasks.rst: rewrite the section > about configuration templates > > On Tue, 13 Sept 2022 at 19:38, Peter Kjellerstedt > <peter.kjellerstedt@axis.com> wrote: > > I do not agree with this sentiment. If you create and distribute a setup > > similar to Poky (which we do), why would we not change .templateconf to > > point at our templates? This has been the documented method and the one > > at least we use for our distribution. Where have you gotten the notion > > that this is only to be used by OE-Core & Poky? It does not make sense. > > First we need to find out, where the documentation section that sets > the idea is coming from. It was written by Scott R. in 2014: > https://git.yoctoproject.org/yocto-docs/commit/?id=c07fb7082fe08387bbc546b2a23620dedc7127b8 > from > https://bugzilla.yoctoproject.org/show_bug.cgi?id=5895 > > I believe Scott misunderstood how the whole thing is supposed to work, > and never road tested what he had written. And I think he documented it exactly as it was intended to be used. See Paul Eggleton's comment: One way to do it is to set TEMPLATECONF (an environment variable, not a bitbake variable) to point to a directory where the custom conf-notes.txt can be found. In a repository this can be set within a .templateconf file - hopefully we document that somewhere as well." > You are free to continue to > do the .templateconf rewrite, but I do not want to keep it in the > docs. Well, I would prefer to keep it in the docs since it is a documented feature and (at least was) the recommended way to do things. Maybe this has changed over the years, but if it is removed from the docs there is nothing stopping someone from removing it. And just because it does not match how you use Yocto, doesn't mean it isn't useful to others. > It just isn't actually supported, unless you *also* provide a > description and tools for 'creating a distribution setup similar to > poky' and for doing the actual rewrite, and find someone else except > you who's using it (I believe you do this with custom unpublished > scripts?). Nowadays we do, since we gave up on the limitations of static configurations in the layers. Our repo manifests decide which layers are fetched and those are the layers that will be added to the bblayers.conf.sample file. > Besides, the only feature it gets you is not having to > specify TEMPLATECONF when you have a default choice for it, which is > useful, but should be made possible with the setup everyone *actually* > uses, which is cloning poky, then adding layers next to it. Well, that's what we do too using our repo manifests. It's just that repo has the support to copy files into the directories it sets up, which we use to copy in a .templateconf that overrides the one from poky. Anyone can do that if they have a defined set of layers they use. > > Alex //Peter
On Wed, 14 Sept 2022 at 01:59, Peter Kjellerstedt <peter.kjellerstedt@axis.com> wrote: > And I think he documented it exactly as it was intended to be used. See > Paul Eggleton's comment: > > One way to do it is to set TEMPLATECONF (an environment variable, not a > bitbake variable) to point to a directory where the custom conf-notes.txt > can be found. In a repository this can be set within a .templateconf file - > hopefully we document that somewhere as well." Paul didn't think it through either when he wrote this. Specifically, .templateconf must be directly next to oe-init-build-env, which means it cannot simply be 'in a repository'. You can't have it both ways: demand that this is kept in the docs, but without explaining how to actually make it work (using standard tooling). Also, your setup is unnecessarily complicated to begin with: just skip the template assembly altogether, and write directly to build/conf. Eventually you'll be able to do it in a structured, supported way with fragments, which is what we should *actually* be talking about. Alex
Hi Alex, On 9/11/22 19:26, Alexander Kanavin wrote: > 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). > > Signed-off-by: Alexander Kanavin <alex@linutronix.de> > --- > documentation/dev-manual/common-tasks.rst | 92 +++++++++-------------- > 1 file changed, 36 insertions(+), 56 deletions(-) > > diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst > index 6c2df9aa6..eab5648fd 100644 > --- a/documentation/dev-manual/common-tasks.rst > +++ b/documentation/dev-manual/common-tasks.rst > @@ -6463,71 +6463,51 @@ 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 customize the message shown by the > -setup script or you might want to change the template configuration > -files (i.e. ``local.conf`` and ``bblayers.conf``) that are created in a > -new build directory. > +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 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. > > -The OpenEmbedded build system uses the environment variable > -:term:`TEMPLATECONF` to locate the directory from which it gathers > -configuration information that ultimately ends up in the > -:term:`Build Directory` ``conf`` directory. > -By default, :term:`TEMPLATECONF` is set as follows in the ``poky`` > -repository:: > +This can be done by using ``bitbake-layers save-build-conf``: > Double colon to end a sentence to start a code-block missing here. > - TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} > - > -This is the > -directory used by the build system to find templates from which to build > -some key configuration files. If you look at this directory, you will > -see the ``bblayers.conf.sample``, ``local.conf.sample``, and > -``conf-notes.txt`` files. The build system uses these files to form the > -respective ``bblayers.conf`` file, ``local.conf`` file, and display the > -list of BitBake targets when running the setup script. > - > -To override these default configuration files with configurations you > -want used within every new Build Directory, simply set the > -:term:`TEMPLATECONF` variable to your directory. The :term:`TEMPLATECONF` > -variable is set in the ``.templateconf`` file, which is in the top-level > -:term:`Source Directory` folder > -(e.g. ``poky``). Edit the ``.templateconf`` so that it can locate your > -directory. > + $ bitbake-layers save-build-conf ../../meta-alex/ test-1 > + NOTE: Starting bitbake server... > + NOTE: Configuration template placed into /srv/work/alex/meta-alex/conf/templates/test-1 > + 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 > + You can try out the configuration with > + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 > > -Best practices dictate that you should keep your template configuration > -directory in your custom distribution layer. For example, suppose you > -have a layer named ``meta-mylayer`` located in your home directory and > -you want your template configuration directory named ``myconf``. > -Changing the ``.templateconf`` as follows causes the OpenEmbedded build > -system to look in your directory and base its configuration files on the > -``*.sample`` configuration files it finds. The final configuration files > -(i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in > -your Build Directory, but they are based on your ``*.sample`` files. > -:: > +The above command takes the config files from the currently active build directory under ``conf\``, Spurious backslash. > +replaces site-specific paths in bblayers.conf with ##OECORE##-relative paths, and copies Please double-tick quote bblayers.conf and ##OECORE##. > +the config files into a specified layer under a specified template name. > > - TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} > +To use those saved templates as a starting point for a build, users should point > +to one of them with :term:`TEMPLATECONF` environment variable: > Double colon to end a sentence to start a code-block missing here. > -Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` > -also resides in the default ``meta-poky/conf`` directory. The script > -that sets up the build environment (i.e. > -:ref:`structure-core-script`) uses this file to > -display BitBake targets as part of the script output. Customizing this > -``conf-notes.txt`` file is a good way to make sure your list of custom > -targets appears as part of the script's output. > + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 > > -Here is the default list of targets displayed as a result of running > -either of the setup scripts:: > +The OpenEmbedded build system uses the environment variable > +:term:`TEMPLATECONF` to locate the directory from which it gathers > +configuration information that ultimately ends up in the > +:term:`Build Directory` ``conf`` directory. > > - You can now run 'bitbake <target>' > +If :term:`TEMPLATECONF` is not set, the default value is obtained > +from ```.templateconf`` file that is read from the same directory as Spurious tick quote. > +`oe-init-build-env` script. For ``poky`` reference distribution this Double-tick quote oe-init-build-env. Cheers, Quentin
Greetings, On 14.09.22 06:50, Alexander Kanavin wrote: > On Wed, 14 Sept 2022 at 01:59, Peter Kjellerstedt > <peter.kjellerstedt@axis.com> wrote: >> And I think he documented it exactly as it was intended to be used. See >> Paul Eggleton's comment: >> >> One way to do it is to set TEMPLATECONF (an environment variable, not a >> bitbake variable) to point to a directory where the custom conf-notes.txt >> can be found. In a repository this can be set within a .templateconf file - >> hopefully we document that somewhere as well." > Paul didn't think it through either when he wrote this. Specifically, > .templateconf must be directly next to oe-init-build-env, which means > it cannot simply be 'in a repository'. > > You can't have it both ways: demand that this is kept in the docs, but > without explaining how to actually make it work (using standard > tooling). Also, your setup > is unnecessarily complicated to begin with: just skip the template > assembly altogether, and write directly to build/conf. Eventually > you'll be able to do it in a structured, supported > way with fragments, which is what we should *actually* be talking about. It's obvious we don't have a consensus yet here. Can anyone else jump in and contribute to this discussion? The other patches in this series have been merged into master-next. Thanks in advance Michael.
It’s not a need-for-consensus situation. It’s correcting something that should have never been added in the first place. Alex On Tue 20. Sep 2022 at 21.46, Michael Opdenacker < michael.opdenacker@bootlin.com> wrote: > Greetings, > > On 14.09.22 06:50, Alexander Kanavin wrote: > > On Wed, 14 Sept 2022 at 01:59, Peter Kjellerstedt > > <peter.kjellerstedt@axis.com> wrote: > >> And I think he documented it exactly as it was intended to be used. See > >> Paul Eggleton's comment: > >> > >> One way to do it is to set TEMPLATECONF (an environment variable, > not a > >> bitbake variable) to point to a directory where the custom > conf-notes.txt > >> can be found. In a repository this can be set within a .templateconf > file - > >> hopefully we document that somewhere as well." > > Paul didn't think it through either when he wrote this. Specifically, > > .templateconf must be directly next to oe-init-build-env, which means > > it cannot simply be 'in a repository'. > > > > You can't have it both ways: demand that this is kept in the docs, but > > without explaining how to actually make it work (using standard > > tooling). Also, your setup > > is unnecessarily complicated to begin with: just skip the template > > assembly altogether, and write directly to build/conf. Eventually > > you'll be able to do it in a structured, supported > > way with fragments, which is what we should *actually* be talking about. > > > It's obvious we don't have a consensus yet here. > Can anyone else jump in and contribute to this discussion? > > The other patches in this series have been merged into master-next. > > Thanks in advance > Michael. > > -- > Michael Opdenacker, Bootlin > Embedded Linux and Kernel engineering > https://bootlin.com > >
To clarify, the .templateconf stuff can be brought back, but it must come with specific explanation about how to use it if it comes from anything else than poky or oe-core. Which is not possible with current tooling in core. But Peter is welcome to write that section. Alex On Tue, 20 Sept 2022 at 22:54, Alexander Kanavin via lists.yoctoproject.org <alex.kanavin=gmail.com@lists.yoctoproject.org> wrote: > > It’s not a need-for-consensus situation. It’s correcting something that should have never been added in the first place. > > Alex > > On Tue 20. Sep 2022 at 21.46, Michael Opdenacker <michael.opdenacker@bootlin.com> wrote: >> >> Greetings, >> >> On 14.09.22 06:50, Alexander Kanavin wrote: >> > On Wed, 14 Sept 2022 at 01:59, Peter Kjellerstedt >> > <peter.kjellerstedt@axis.com> wrote: >> >> And I think he documented it exactly as it was intended to be used. See >> >> Paul Eggleton's comment: >> >> >> >> One way to do it is to set TEMPLATECONF (an environment variable, not a >> >> bitbake variable) to point to a directory where the custom conf-notes.txt >> >> can be found. In a repository this can be set within a .templateconf file - >> >> hopefully we document that somewhere as well." >> > Paul didn't think it through either when he wrote this. Specifically, >> > .templateconf must be directly next to oe-init-build-env, which means >> > it cannot simply be 'in a repository'. >> > >> > You can't have it both ways: demand that this is kept in the docs, but >> > without explaining how to actually make it work (using standard >> > tooling). Also, your setup >> > is unnecessarily complicated to begin with: just skip the template >> > assembly altogether, and write directly to build/conf. Eventually >> > you'll be able to do it in a structured, supported >> > way with fragments, which is what we should *actually* be talking about. >> >> >> It's obvious we don't have a consensus yet here. >> Can anyone else jump in and contribute to this discussion? >> >> The other patches in this series have been merged into master-next. >> >> Thanks in advance >> Michael. >> >> -- >> Michael Opdenacker, Bootlin >> Embedded Linux and Kernel engineering >> https://bootlin.com >> > > -=-=-=-=-=-=-=-=-=-=-=- > Links: You receive all messages sent to this group. > View/Reply Online (#3191): https://lists.yoctoproject.org/g/docs/message/3191 > Mute This Topic: https://lists.yoctoproject.org/mt/93615912/1686489 > Group Owner: docs+owner@lists.yoctoproject.org > Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [alex.kanavin@gmail.com] > -=-=-=-=-=-=-=-=-=-=-=- >
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 6c2df9aa6..eab5648fd 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst @@ -6463,71 +6463,51 @@ 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 customize the message shown by the -setup script or you might want to change the template configuration -files (i.e. ``local.conf`` and ``bblayers.conf``) that are created in a -new build directory. +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 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. -The OpenEmbedded build system uses the environment variable -:term:`TEMPLATECONF` to locate the directory from which it gathers -configuration information that ultimately ends up in the -:term:`Build Directory` ``conf`` directory. -By default, :term:`TEMPLATECONF` is set as follows in the ``poky`` -repository:: +This can be done by using ``bitbake-layers save-build-conf``: - TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} - -This is the -directory used by the build system to find templates from which to build -some key configuration files. If you look at this directory, you will -see the ``bblayers.conf.sample``, ``local.conf.sample``, and -``conf-notes.txt`` files. The build system uses these files to form the -respective ``bblayers.conf`` file, ``local.conf`` file, and display the -list of BitBake targets when running the setup script. - -To override these default configuration files with configurations you -want used within every new Build Directory, simply set the -:term:`TEMPLATECONF` variable to your directory. The :term:`TEMPLATECONF` -variable is set in the ``.templateconf`` file, which is in the top-level -:term:`Source Directory` folder -(e.g. ``poky``). Edit the ``.templateconf`` so that it can locate your -directory. + $ bitbake-layers save-build-conf ../../meta-alex/ test-1 + NOTE: Starting bitbake server... + NOTE: Configuration template placed into /srv/work/alex/meta-alex/conf/templates/test-1 + 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 + You can try out the configuration with + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 -Best practices dictate that you should keep your template configuration -directory in your custom distribution layer. For example, suppose you -have a layer named ``meta-mylayer`` located in your home directory and -you want your template configuration directory named ``myconf``. -Changing the ``.templateconf`` as follows causes the OpenEmbedded build -system to look in your directory and base its configuration files on the -``*.sample`` configuration files it finds. The final configuration files -(i.e. ``local.conf`` and ``bblayers.conf`` ultimately still end up in -your Build Directory, but they are based on your ``*.sample`` files. -:: +The above command takes the config files from the currently active build directory under ``conf\``, +replaces site-specific paths in bblayers.conf with ##OECORE##-relative paths, and copies +the config files into a specified layer under a specified template name. - TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf} +To use those saved templates as a starting point for a build, users should point +to one of them with :term:`TEMPLATECONF` environment variable: -Aside from the ``*.sample`` configuration files, the ``conf-notes.txt`` -also resides in the default ``meta-poky/conf`` directory. The script -that sets up the build environment (i.e. -:ref:`structure-core-script`) uses this file to -display BitBake targets as part of the script output. Customizing this -``conf-notes.txt`` file is a good way to make sure your list of custom -targets appears as part of the script's output. + TEMPLATECONF=/srv/work/alex/meta-alex/conf/templates/test-1 . /srv/work/alex/poky/oe-init-build-env build-try-test-1 -Here is the default list of targets displayed as a result of running -either of the setup scripts:: +The OpenEmbedded build system uses the environment variable +:term:`TEMPLATECONF` to locate the directory from which it gathers +configuration information that ultimately ends up in the +:term:`Build Directory` ``conf`` directory. - You can now run 'bitbake <target>' +If :term:`TEMPLATECONF` is not set, the default value is obtained +from ```.templateconf`` file that is read from the same directory as +`oe-init-build-env` script. For ``poky`` reference distribution this +would be:: - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-ide-support + TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf/templates/default} -Changing the listed common targets is as easy as editing your version of -``conf-notes.txt`` in your custom template configuration directory and -making sure you have :term:`TEMPLATECONF` set to your directory. +If you look at a configuration template directory, you will +see the ``bblayers.conf.sample``, ``local.conf.sample``, and +``conf-notes.txt`` files. The build system uses these files to form the +respective ``bblayers.conf`` file, ``local.conf`` file, and show +users a note 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 +available to the users. Conserving Disk Space =====================
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). Signed-off-by: Alexander Kanavin <alex@linutronix.de> --- documentation/dev-manual/common-tasks.rst | 92 +++++++++-------------- 1 file changed, 36 insertions(+), 56 deletions(-)