1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Locking and Unlocking Recipes Using ``bblock`` 4********************************************** 5 6By design, the OpenEmbedded build system builds everything from scratch 7unless BitBake determines that specific tasks do not require rebuilding. 8At startup, it computes a signature for all tasks, based on the task's input. 9Then, it compares these signatures with the ones from the sstate cache (if they 10exist). Any changes cause the task to rerun. 11 12During development, changes might trigger BitBake to rebuild certain 13recipes, even when we know they do not require rebuilding at that stage. 14For example, modifying a recipe can lead to rebuilding its native 15counterpart, which might prove unnecessary. Editing the ``python3`` recipe, 16for instance, can prompt BitBake to rebuild ``python3-native`` along with any 17recipes that depend on it. 18 19To prevent this, use ``bblock`` to lock specific tasks or recipes to 20specific signatures, forcing BitBake to use the sstate cache for them. 21 22.. warning:: 23 24 Use ``bblock`` only during the development phase. 25 26 Forcing BitBake to use the sstate cache, regardless of input changes, means 27 the recipe metadata no longer directly reflect the output. Use this feature 28 with caution. If you do not understand why signatures change, see the section 29 on :yocto_wiki:`understanding what changed </TipsAndTricks/Understanding_what_changed_(diffsigs_etc)>`. 30 31 32Locking tasks and recipes 33------------------------- 34 35To lock a recipe, use:: 36 37 $ bblock recipe 38 39You can also use a space-separated list of recipes to lock multiple recipes:: 40 41 $ bblock recipe1 recipe2 42 43Locking a recipe means locking all tasks of the recipe. If you need to 44lock only particular tasks, use the `-t` option with a comma-separated 45list of tasks:: 46 47 $ bblock -t task1,task2 recipe 48 49 50Unlocking tasks and recipes 51--------------------------- 52 53To unlock a recipe, use the ``-r`` option:: 54 55 $ bblock -r recipe 56 57You can also use a space-separated list of recipes to unlock multiple recipes:: 58 59 $ bblock -r recipe1 recipe2 60 61Unlocking a recipe means unlocking all tasks of the recipe. If you need to 62unlock only particular tasks use the ``-t`` option with a comma-separated 63list of tasks:: 64 65 $ bblock -r -t task1,task2 recipe 66 67To unlock all recipes, do not specify any recipe:: 68 69 $ bblock -r 70 71 72Configuration file 73------------------ 74 75``bblock`` will dump the signatures in the ``build/conf/bblock.conf`` file, 76included by default in :oe_git:`meta/conf/bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`. 77 78To dump the file, use the ``-d`` option:: 79 80 $ bblock -d 81 82 83Locking mechanism 84----------------- 85 86``bblock`` computes the signature(s) of the task(s) and sets the 3 following 87variables: :term:`SIGGEN_LOCKEDSIGS`, :term:`SIGGEN_LOCKEDSIGS_TYPES` 88and :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`. 89 90In particular, ``bblock`` sets:: 91 92 SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info" 93 SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" 94 95 SIGGEN_LOCKEDSIGS_<package_arch> += "<recipe>:<task>:<signature>" 96 97This produces architecture specific locks and reminds user that some tasks 98have locked signatures. 99 100Example 101------- 102 103When working on the ``python3`` recipe, we can lock ``python3-native`` with 104the following:: 105 106 $ bblock python3-native 107 $ bblock -d 108 # Generated by bblock 109 SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info" 110 SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" 111 112 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_patch:865859c27e603ba42025b7bb766c3cd4c0f477e4962cfd39128c0619d695fce7" 113 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_sysroot:f8fa5d3194cef638416000252b959e86d0a19f6b7898e1f56b643c588cdd8605" 114 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_prepare_recipe_sysroot:fe295ac505d9d1143313424b201c6f3f2a0a90da40a13a905b86b874705f226a" 115 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_fetch:1b6e4728fee631bc7a8a7006855c5b8182a8224579e32e3d0a2db77c26459f25" 116 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_unpack:2ad74d6f865ef75c35c0e6bbe3f9a90923a6b2c62c18a3ddef514ea31fbc588f" 117 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_deploy_source_date_epoch:15f89b8483c1ad7507480f337619bb98c26e231227785eb3543db163593e7b42" 118 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_configure:7960c13d23270fdb12b3a7c426ce1da0d2f5c7cf5e5d3f5bdce5fa330eb7d482" 119 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_compile:012e1d4a63f1a78fc2143bd90d704dbcf5865c5257d6272aa7540ec1cd3063d9" 120 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_install:d3401cc2afa4c996beb154beaad3e45fa0272b9c56fb86e9db14ec3544c68f9d" 121 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_build:fa88bb7afb9046c0417c24a3fa98a058653805a8b00eda2c2d7fea68fc42f882" 122 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_collect_spdx_deps:cc9c53ba7c495567e9a38ec4801830c425c0d1f895aa2fc66930a2edd510d9b4" 123 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_spdx:766a1d09368438b7b5a1a8e2a8f823b2b731db44b57e67d8b3196de91966f9c5" 124 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_package_spdx:46f80faeab25575e9977ba3bf14c819489c3d489432ae5145255635108c21020" 125 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_recipe_qa:cb960cdb074e7944e894958db58f3dc2a0436ecf87c247feb3e095e214fec0e4" 126 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_lic:15657441621ee83f15c2e650e7edbb036870b56f55e72e046c6142da3c5783fd" 127 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_manifest:24f0abbec221d27bbb2909b6e846288b12cab419f1faf9f5006ed80423d37e28" 128 SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_addto_recipe_sysroot:bcb6a1905f113128de3f88d702b706befd6a786267c045ee82532759a7c214d7" 129 130