.. 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.

.. warning::

   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"