mirror of
git://git.yoctoproject.org/poky.git
synced 2025-07-19 21:09:03 +02:00
dev-manual: add bblock documentation
bblock is a helper tool to lock/unlock tasks and recipes to specific signatures. Add a documentation page for it. (From yocto-docs rev: a082aa39840587d3af6c3f4a2c2747564ca37414) Signed-off-by: Julien Stephan <jstephan@baylibre.com> Reviewed-by: Antonin Godard <antonin.godard@bootlin.com> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Julien Stephan
Richard Purdie
parent
c69aaeef11
commit
78f25d9a9c
129
documentation/dev-manual/bblock.rst
Normal file
129
documentation/dev-manual/bblock.rst
Normal file
|
|
@ -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 cache (if they
|
||||
exist). Any changes cause the task to rerun.
|
||||
|
||||
During development, changes might trigger BitBake to rebuild certain
|
||||
recipes, even when we know they do not require rebuilding at that stage.
|
||||
For example, modifying a recipe can lead to rebuilding its native
|
||||
counterpart, which might prove unnecessary. Editing the ``python3`` recipe,
|
||||
for instance, can prompt BitBake to rebuild ``python3-native`` along with any
|
||||
recipes that depend on it.
|
||||
|
||||
To prevent this, use ``bblock`` to lock specific tasks or recipes to
|
||||
specific signatures, forcing BitBake to use the sstate cache for them.
|
||||
|
||||
.. attention::
|
||||
|
||||
Use ``bblock`` only during the development phase.
|
||||
|
||||
Forcing BitBake to use the sstate cache, regardless of input changes, means
|
||||
the recipe metadata no longer directly reflect the output. Use this feature
|
||||
with caution. If you do not understand why signatures change, see the section
|
||||
on :yocto_wiki:`understanding what changed </TipsAndTricks/Understanding_what_changed_(diffsigs_etc)>`.
|
||||
|
||||
|
||||
Locking tasks and recipes
|
||||
-------------------------
|
||||
|
||||
To lock a recipe, use::
|
||||
|
||||
$ bblock recipe
|
||||
|
||||
You can also use a space-separated list of recipes to lock multiple recipes::
|
||||
|
||||
$ bblock recipe1 recipe2
|
||||
|
||||
Locking a recipe means locking all tasks of the recipe. If you need to
|
||||
lock only particular tasks, use the `-t` option with a comma-separated
|
||||
list of tasks::
|
||||
|
||||
$ bblock -t task1,task2 recipe
|
||||
|
||||
|
||||
Unlocking tasks and recipes
|
||||
---------------------------
|
||||
|
||||
To unlock a recipe, use the ``-r`` option::
|
||||
|
||||
$ bblock -r recipe
|
||||
|
||||
You can also use a space-separated list of recipes to unlock multiple recipes::
|
||||
|
||||
$ bblock -r recipe1 recipe2
|
||||
|
||||
Unlocking a recipe means unlocking all tasks of the recipe. If you need to
|
||||
unlock only particular tasks use the ``-t`` option with a comma-separated
|
||||
list of tasks::
|
||||
|
||||
$ bblock -r -t task1,task2 recipe
|
||||
|
||||
To unlock all recipes, do not specify any recipe::
|
||||
|
||||
$ bblock -r
|
||||
|
||||
|
||||
Configuration file
|
||||
------------------
|
||||
|
||||
``bblock`` will dump the signatures in the ``build/conf/bblock.conf`` file,
|
||||
included by default in :oe_git:`meta/conf/bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`.
|
||||
|
||||
To dump the file, use the ``-d`` option::
|
||||
|
||||
$ bblock -d
|
||||
|
||||
|
||||
Locking mechanism
|
||||
-----------------
|
||||
|
||||
``bblock`` computes the signature(s) of the task(s) and sets the 3 following
|
||||
variables: :term:`SIGGEN_LOCKEDSIGS`, :term:`SIGGEN_LOCKEDSIGS_TYPES`
|
||||
and :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`.
|
||||
|
||||
In particular, ``bblock`` sets::
|
||||
|
||||
SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info"
|
||||
SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
|
||||
|
||||
SIGGEN_LOCKEDSIGS_<package_arch> += "<recipe>:<task>:<signature>"
|
||||
|
||||
This produces architecture specific locks and reminds user that some tasks
|
||||
have locked signatures.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
When working on the ``python3`` recipe, we can lock ``python3-native`` with
|
||||
the following::
|
||||
|
||||
$ bblock python3-native
|
||||
$ bblock -d
|
||||
# Generated by bblock
|
||||
SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info"
|
||||
SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
|
||||
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_patch:865859c27e603ba42025b7bb766c3cd4c0f477e4962cfd39128c0619d695fce7"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_sysroot:f8fa5d3194cef638416000252b959e86d0a19f6b7898e1f56b643c588cdd8605"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_prepare_recipe_sysroot:fe295ac505d9d1143313424b201c6f3f2a0a90da40a13a905b86b874705f226a"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_fetch:1b6e4728fee631bc7a8a7006855c5b8182a8224579e32e3d0a2db77c26459f25"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_unpack:2ad74d6f865ef75c35c0e6bbe3f9a90923a6b2c62c18a3ddef514ea31fbc588f"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_deploy_source_date_epoch:15f89b8483c1ad7507480f337619bb98c26e231227785eb3543db163593e7b42"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_configure:7960c13d23270fdb12b3a7c426ce1da0d2f5c7cf5e5d3f5bdce5fa330eb7d482"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_compile:012e1d4a63f1a78fc2143bd90d704dbcf5865c5257d6272aa7540ec1cd3063d9"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_install:d3401cc2afa4c996beb154beaad3e45fa0272b9c56fb86e9db14ec3544c68f9d"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_build:fa88bb7afb9046c0417c24a3fa98a058653805a8b00eda2c2d7fea68fc42f882"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_collect_spdx_deps:cc9c53ba7c495567e9a38ec4801830c425c0d1f895aa2fc66930a2edd510d9b4"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_spdx:766a1d09368438b7b5a1a8e2a8f823b2b731db44b57e67d8b3196de91966f9c5"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_package_spdx:46f80faeab25575e9977ba3bf14c819489c3d489432ae5145255635108c21020"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_recipe_qa:cb960cdb074e7944e894958db58f3dc2a0436ecf87c247feb3e095e214fec0e4"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_lic:15657441621ee83f15c2e650e7edbb036870b56f55e72e046c6142da3c5783fd"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_manifest:24f0abbec221d27bbb2909b6e846288b12cab419f1faf9f5006ed80423d37e28"
|
||||
SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_addto_recipe_sysroot:bcb6a1905f113128de3f88d702b706befd6a786267c045ee82532759a7c214d7"
|
||||
|
||||
|
|
@ -48,5 +48,6 @@ Yocto Project Development Tasks Manual
|
|||
error-reporting-tool
|
||||
wayland
|
||||
qemu
|
||||
bblock
|
||||
|
||||
.. include:: /boilerplate.rst
|
||||
|
|
|
|||
|
|
@ -335,6 +335,15 @@ 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``. By default, it does not exist
|
||||
and will be created upon the first invocation of ``bblock``.
|
||||
|
||||
.. _structure-build-downloads:
|
||||
|
||||
``build/downloads/``
|
||||
|
|
|
|||
|
|
@ -7901,6 +7901,9 @@ system and gives an overview of their function and contents.
|
|||
Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for
|
||||
files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
|
||||
|
||||
Alternatively, you can also use :doc:`bblock </dev-manual/bblock>` to
|
||||
generate this line for you.
|
||||
|
||||
:term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`
|
||||
Specifies the debug level of task signature check. 3 levels are supported:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user