Re: [docs] [PATCH v2 1/5] ref-manual/terms.rst: refresh the Build Directory definition

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 1/20/26 4:17 PM, Antonin Godard via lists.yoctoproject.org wrote:
> After the Poky repository obsolescence, refresh the build directory
> definition. Fix the formatting and indenting issues while at it.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/ref-manual/terms.rst | 46 +++++++++++++++++++++-----------------
>   1 file changed, 25 insertions(+), 21 deletions(-)
> 
> diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
> index 6a9f88061..93a2febc7 100644
> --- a/documentation/ref-manual/terms.rst
> +++ b/documentation/ref-manual/terms.rst
> @@ -63,36 +63,39 @@ universal, the list includes them just in case:
>         This term refers to the area used by the OpenEmbedded build system for
>         builds. The area is created when you ``source`` the setup environment
>         script that is found in the Source Directory
> -      (i.e. :ref:`ref-manual/structure:``oe-init-build-env```). The
> +      (i.e. :ref:`ref-manual/structure:``oe-init-build-env```, or
> +      ``init-build-env`` when using :doc:`bitbake-setup
> +      <bitbake:bitbake-user-manual/bitbake-user-manual-environment-setup>`). The
>         :term:`TOPDIR` variable points to the :term:`Build Directory`.
>   
> -      You have a lot of flexibility when creating the :term:`Build Directory`.
> +      When setting up the build manually (see :doc:`/dev-manual/poky-manual-setup`),
> +      you have a lot of flexibility when creating the :term:`Build Directory`.
>         Here are some examples that show how to create the directory.  The
> -      examples assume your :term:`Source Directory` is named ``poky``:
> +      examples assume your :term:`Source Directory` is named ``project``:
>   
> -         -  Create the :term:`Build Directory` inside your Source Directory and let
> -            the name of the :term:`Build Directory` default to ``build``:
> +      -  Create the :term:`Build Directory` inside your Source Directory and let
> +         the name of the :term:`Build Directory` default to ``build``:
>   
> -            .. code-block:: shell
> +         .. code-block:: console
>   
> -               $ cd poky
> -               $ source oe-init-build-env
> +            $ cd project
> +            $ source layers/openembedded-core/oe-init-build-env
>   
> -         -  Create the :term:`Build Directory` inside your home directory and
> -            specifically name it ``test-builds``:
> +      -  Or create the :term:`Build Directory` inside your current working
> +         directory and specifically name it ``test-builds``:
>   

suggestion: to make more digestable:

Or create the :term:`Build Directory` named ``test-builds`` inside the 
current working directory

> -            .. code-block:: shell
> +         .. code-block:: console
>   
> -               $ source poky/oe-init-build-env test-builds
> +            $ source project/layers/openembedded-core/oe-init-build-env test-builds
>   
> -         -  Provide a directory path and specifically name the
> -            :term:`Build Directory`. Any intermediate folders in the pathname
> -            must exist.  This next example creates a :term:`Build Directory`
> -            named ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
> +      -  Or provide a directory path and specifically name the

suggestion:

Or provide a path relative to the current working directory as 
:term:`Build Directory`.

> +         :term:`Build Directory`. Any intermediate folders in the pathname

suggestion:

Any parent folder of :term:`Build Directory` must exist.

> +         must exist.  This next example creates a :term:`Build Directory`

s/  / /

> +         named ``YP-&DISTRO;`` within the existing directory ``mybuilds``:
>   
> -            .. code-block:: shell
> +         .. code-block:: shell
>   
> -               $ source poky/oe-init-build-env mybuilds/YP-&DISTRO;
> +            $ source project/layers/openembedded-core/oe-init-build-env mybuilds/YP-&DISTRO;

question: do we support absolute paths?

Seems like something we could add a word for here? I think we do but 
I've never tried.

Cheers,
Quentin