Re: [docs] [PATCH v3 3/3] dev-manual: add bblock documentation

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Julien,

Thanks for this v3.
Here are my suggestions:

On Tue Nov 5, 2024 at 9:17 AM CET, Julien Stephan wrote:
> bblock is a helper tool to lock/unlock tasks and recipes to specific
> signatures. Add a documentation page for it.
>
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
> ---
>  documentation/dev-manual/bblock.rst    | 129 +++++++++++++++++++++++++++++++++
>  documentation/dev-manual/index.rst     |   1 +
>  documentation/ref-manual/structure.rst |   8 ++
>  documentation/ref-manual/variables.rst |   3 +
>  4 files changed, 141 insertions(+)
>
> diff --git a/documentation/dev-manual/bblock.rst b/documentation/dev-manual/bblock.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..cb45abcc6963e0dc2196cc02fad72010fbdb8df1
> --- /dev/null
> +++ b/documentation/dev-manual/bblock.rst
> @@ -0,0 +1,129 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +Locking and Unlocking Recipes Using ``bblock``
> +**********************************************
> +
> +By design, the OpenEmbedded build system builds everything from scratch
> +unless BitBake determines that specific tasks do not require rebuilding.
> +At startup, it computes a signature for all tasks, based on the task's input.
> +Then, it compares these signatures with the ones from the sstate (if they

s/the sstate/the sstate cache/

[...]
> diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
> index bbeda78c791d430faa55356a3209f5eeb1402837..339ee2fbd77b1264e62b9b70381ff970b816d728 100644
> --- a/documentation/ref-manual/structure.rst
> +++ b/documentation/ref-manual/structure.rst
> @@ -335,6 +335,14 @@ Once the build process gets the sample file, it uses ``sed`` to substitute final
>     version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/templates/default``
>     directory.
>  
> +.. _structure-build-conf-bblock.conf:
> +
> +``build/conf/bblock.conf``
> +--------------------------
> +
> +This configuration file is generated by :doc:`bblock </dev-manual/bblock>` and
> +contains the signatures locked by ``bblock``.
> +

Thank you for adding this. Could you mention that this file does not exist by
default? This is so that users reading this page don't wonder why it doesn't
exist on their setup.

>  .. _structure-build-downloads:
>  
>  ``build/downloads/``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index b24286813eafaa562f4ebd070190f1e97e0cf23c..3d2d3f95695c98e583377ef5392fdfe7fa0ab28e 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -7901,6 +7901,9 @@ system and gives an overview of their function and contents.
>       Then you can look at files in ``build/stamps/<arch>/bc`` and search for the
>       file: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
>  
> +     Alternatively, you can also use :doc:`bblock </dev-manual/bblock>` to
> +     generate this line for you.
> +

Good idea adding this here!


>     :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`
>       Specifies the debug level of task signature check. 3 levels are supported:
>  

Cheers,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com