[v2] dev-manual: Add info on build env initialization

From: Jasper Orschulko <jasper@fancydomain.eu>

Going through the docs we a new trainee, we noticed that the build
initialization is only mentioned in the quick build
(https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html) but not
in the in-depth getting started documentation.

While this is repeatedly mentioned later on, e.g. in the "building" section,
you might easily end up somewhere where this has not been mentioned yet.

E.g. in our case this was:

https://docs.yoctoproject.org/dev-manual/layers.html# (which comes right
after the "setup" chapter)
->
https://docs.yoctoproject.org/dev-manual/layers.html#creating-a-general-layer-using-the-bitbake-layers-script
(which is linked right at the top)

To avoid any confusion I think it best to mention this required step
directly in the "start" document.

Signed-off-by: Jasper Orschulko <jasper@fancydomain.eu>
---
 documentation/dev-manual/start.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

Hi Jasper,

On 6/6/24 5:04 PM, jasper@fancydomain.eu wrote:
> [You don't often get email from jasper@fancydomain.eu. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> From: Jasper Orschulko <jasper@fancydomain.eu>
> 
> Going through the docs we a new trainee, we noticed that the build
> initialization is only mentioned in the quick build
> (https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html) but not
> in the in-depth getting started documentation.
> 
> While this is repeatedly mentioned later on, e.g. in the "building" section,
> you might easily end up somewhere where this has not been mentioned yet.
> 
> E.g. in our case this was:
> 
> https://docs.yoctoproject.org/dev-manual/layers.html# (which comes right
> after the "setup" chapter)
> ->
> https://docs.yoctoproject.org/dev-manual/layers.html#creating-a-general-layer-using-the-bitbake-layers-script
> (which is linked right at the top)
> 
> To avoid any confusion I think it best to mention this required step
> directly in the "start" document.
> 
> Signed-off-by: Jasper Orschulko <jasper@fancydomain.eu>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Hi Jasper

On 6/6/24 17:04, Jasper Orschulko via lists.yoctoproject.org wrote:
> From: Jasper Orschulko <jasper@fancydomain.eu>
>
> Going through the docs we a new trainee, we noticed that the build
> initialization is only mentioned in the quick build
> (https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html) but not
> in the in-depth getting started documentation.
>
> While this is repeatedly mentioned later on, e.g. in the "building" section,
> you might easily end up somewhere where this has not been mentioned yet.
>
> E.g. in our case this was:
>
> https://docs.yoctoproject.org/dev-manual/layers.html# (which comes right
> after the "setup" chapter)
> ->
> https://docs.yoctoproject.org/dev-manual/layers.html#creating-a-general-layer-using-the-bitbake-layers-script
> (which is linked right at the top)
>
> To avoid any confusion I think it best to mention this required step
> directly in the "start" document.
>
> Signed-off-by: Jasper Orschulko <jasper@fancydomain.eu>
> ---
>   documentation/dev-manual/start.rst | 11 +++++++++++
>   1 file changed, 11 insertions(+)
>
> diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> index 386e5f5d2..66e70cf21 100644
> --- a/documentation/dev-manual/start.rst
> +++ b/documentation/dev-manual/start.rst
> @@ -853,3 +853,14 @@ similar to checking out by branch name except you use tag names.
>      ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;"
>      development branch at the point where Yocto Project &DISTRO; was
>      released.
> +
> +Initializing the Build Environment
> +==================================
> +
> +Before you can use Yocto you need to setup the build environment.
> +From within the `poky` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment

One last nitpick...
If poky is a directory name, you should use ``poky``. If you refer to 
the project name, it should be `Poky`.

I think the first solution is what you want here.
Cheers
Michael.

I think we should actually rewrite every mention of oe-init-build-env
to suggest oe-setup-build instead and effectively deprecate using
oe-init-build-env directly. I'm okay with this patch though, as such a
rewrite is a bigger effort.

Alex

On Thu, 6 Jun 2024 at 17:45, Michael Opdenacker via
lists.yoctoproject.org <michael=opdenacker.org@lists.yoctoproject.org>
wrote:
>
> Hi Jasper
>
> On 6/6/24 17:04, Jasper Orschulko via lists.yoctoproject.org wrote:
> > From: Jasper Orschulko <jasper@fancydomain.eu>
> >
> > Going through the docs we a new trainee, we noticed that the build
> > initialization is only mentioned in the quick build
> > (https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html) but not
> > in the in-depth getting started documentation.
> >
> > While this is repeatedly mentioned later on, e.g. in the "building" section,
> > you might easily end up somewhere where this has not been mentioned yet.
> >
> > E.g. in our case this was:
> >
> > https://docs.yoctoproject.org/dev-manual/layers.html# (which comes right
> > after the "setup" chapter)
> > ->
> > https://docs.yoctoproject.org/dev-manual/layers.html#creating-a-general-layer-using-the-bitbake-layers-script
> > (which is linked right at the top)
> >
> > To avoid any confusion I think it best to mention this required step
> > directly in the "start" document.
> >
> > Signed-off-by: Jasper Orschulko <jasper@fancydomain.eu>
> > ---
> >   documentation/dev-manual/start.rst | 11 +++++++++++
> >   1 file changed, 11 insertions(+)
> >
> > diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> > index 386e5f5d2..66e70cf21 100644
> > --- a/documentation/dev-manual/start.rst
> > +++ b/documentation/dev-manual/start.rst
> > @@ -853,3 +853,14 @@ similar to checking out by branch name except you use tag names.
> >      ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;"
> >      development branch at the point where Yocto Project &DISTRO; was
> >      released.
> > +
> > +Initializing the Build Environment
> > +==================================
> > +
> > +Before you can use Yocto you need to setup the build environment.
> > +From within the `poky` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
>
> One last nitpick...
> If poky is a directory name, you should use ``poky``. If you refer to
> the project name, it should be `Poky`.
>
> I think the first solution is what you want here.
> Cheers
> Michael.
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#5280): https://lists.yoctoproject.org/g/docs/message/5280
> Mute This Topic: https://lists.yoctoproject.org/mt/106524927/1686489
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>

Hi Alex,

On 6/6/24 18:07, Alexander Kanavin wrote:
> I think we should actually rewrite every mention of oe-init-build-env
> to suggest oe-setup-build instead and effectively deprecate using
> oe-init-build-env directly. I'm okay with this patch though, as such a
> rewrite is a bigger effort.

I agree. Let's keep this patch, which would be useful too as a backport 
for Scarthgap and Kirkstone, as I'm not sure Kirkstone will have 
oe-setup-build.
Thanks in advance for your patch :)
Cheers
Michael.