[4/5] common-tasks.rst: describe the layer setup tooling

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
 documentation/dev-manual/common-tasks.rst | 54 +++++++++++++++++++++++
 1 file changed, 54 insertions(+)

Hi Alex,

On 9/11/22 19:26, Alexander Kanavin wrote:
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>   documentation/dev-manual/common-tasks.rst | 54 +++++++++++++++++++++++
>   1 file changed, 54 insertions(+)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 4d19bd921..6c2df9aa6 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -858,6 +858,60 @@ enables the build system to locate the layer during the build.
>      During a build, the OpenEmbedded build system looks in the layers
>      from the top of the list down to the bottom in that order.
>   
> +Saving and restoring the layers setup
> +-------------------------------------
> +
> +Once you have a working build with the correct set of layers, it is beneficial
> +to capture the layer setup - what they are, which repositories they come from
> +and which SCM revisions they're at - into a configuration file, so that this
> +setup can be easily replicated later, perhaps on a different machine. Here's
> +how to do this:
> +
> +   $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/
> +   NOTE: Starting bitbake server...
> +   NOTE: Created /srv/work/alex/meta-alex/setup-layers.json
> +   NOTE: Created /srv/work/alex/meta-alex/setup-layers
> +
> +The tool needs a single argument which tells where to place the output, consisting
> +of a json formatted layer configuration, and a 'setup-layers' script that can use that configuration
> +to restore the layers in a different location, or on a different host machine. The argument
> +can point to a custom layer (which is then deemed a 'bootstrap' layer that needs to be
> +checked out first), or into a completely independent location.
> +
> +The replication of the layers is performed by running the setup-layer script provided
> +above:
> +
> +1. Clone the bootstrap layer or some other repository to obtain
> +the json config and the setup script that can use it.
> +
> +2. Run the script directly with no options:
> +(note: this will work to update an existing checkout as well)
> +

This breaks the expected sphinx syntax.

Please move the note after the code block and add re-indent the "code" 
blocks with three more spaces (otherwise it thinks it's part of the 
bullet point text instead of a code block instead the bullet point text).

Also, add a second colon after "options:" above to start the code block.

> +   alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers
> +   Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override.
> +
> +   Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master
> +   Running 'git init -q /srv/work/alex/my-build/meta-intel'
> +   Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/meta-intel' in /srv/work/alex/my-build/meta-intel
> +   Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel
> +   Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel
> +
> +   Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers
> +   Running 'git init -q /srv/work/alex/my-build/poky'
> +   Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/poky' in /srv/work/alex/my-build/poky
> +   Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky
> +   Running 'git remote remove poky-contrib > /dev/null 2>&1; git remote add poky-contrib ssh://git@push.yoctoproject.org/poky-contrib' in /srv/work/alex/my-build/poky
> +   Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky
> +   Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky
> +

Add your note for existing checkout here.

> +.. note::
> +   The script is self-suffucient and requires only python3

s/self-suffucient/self-sufficient/

> +   and git on the host machne where it will run.
> +

s/machne/machine/

Replace "host machne where it will run" with "build machine"?

> +.. note::
> +   Both the 'create-layers-setup' and the 'setup-layers' provided several additional options
> +   that customize their behavior - you are welcome to study them via '--help' command line parameter.
> +

Replace single quotes by double-tick quotes to highlight.

Cheers,
Quentin

On 9/11/22 19:26, Alexander Kanavin wrote:
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>   documentation/dev-manual/common-tasks.rst | 54 +++++++++++++++++++++++
>   1 file changed, 54 insertions(+)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 4d19bd921..6c2df9aa6 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -858,6 +858,60 @@ enables the build system to locate the layer during the build.
>      During a build, the OpenEmbedded build system looks in the layers
>      from the top of the list down to the bottom in that order.
>   
> +Saving and restoring the layers setup
> +-------------------------------------
> +
> +Once you have a working build with the correct set of layers, it is beneficial
> +to capture the layer setup - what they are, which repositories they come from
> +and which SCM revisions they're at - into a configuration file, so that this
> +setup can be easily replicated later, perhaps on a different machine. Here's
> +how to do this:
> +

Double colon here to start a code-block.

> +   $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/
> +   NOTE: Starting bitbake server...
> +   NOTE: Created /srv/work/alex/meta-alex/setup-layers.json
> +   NOTE: Created /srv/work/alex/meta-alex/setup-layers
> +
> +The tool needs a single argument which tells where to place the output, consisting
> +of a json formatted layer configuration, and a 'setup-layers' script that can use that configuration

Replace single quotes with double-tick quotes to highlight.

> +to restore the layers in a different location, or on a different host machine. The argument
> +can point to a custom layer (which is then deemed a 'bootstrap' layer that needs to be

s/'bootstrap'/"bootstrap"/ ?

> +checked out first), or into a completely independent location.
> +
> +The replication of the layers is performed by running the setup-layer script provided
> +above:
> +

``setup-layer`` script

Sorry for the second mail, missed a few things.

Cheers,
Quentin