[kirkstone][PATCH 9/9] dev-manual: improve descriptions of 'bitbake -S printdiff'

michael.opdenacker
2024-03-25T13:27:51Z

From: Alexander Kanavin <alex.kanavin@gmail.com>

Try to particularly emphasize that it can be used to find
out why something rebuilds when it shouldn't.

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
documentation/dev-manual/building.rst | 7 +++----
documentation/dev-manual/debugging.rst | 13 ++++++++++---
2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index 7fcac33b75..fe502690dd 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -775,10 +775,9 @@ your tunings to best consider build times and package feed maintenance.
in the script for information on how to use the tool.

- *BitBake's "-S printdiff" Option:* Using this option causes
- BitBake to try to establish the closest signature match it can
- (e.g. in the shared state cache) and then run ``bitbake-diffsigs``
- over the matches to determine the stamps and delta where these two
- stamp trees diverge.
+ BitBake to try to establish the most recent signature match
+ (e.g. in the shared state cache) and then compare matched signatures
+ to determine the stamps and delta where these two stamp trees diverge.

Building Software from an External Source
=========================================
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 71b5807f5a..74f5772554 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -339,7 +339,10 @@ BitBake has determined by doing the following:
:term:`BB_BASEHASH_IGNORE_VARS`
information.

-There is also a ``bitbake-diffsigs`` command for comparing two
+Debugging signature construction and unexpected task executions
+===============================================================
+
+There is a ``bitbake-diffsigs`` command for comparing two
``siginfo`` or ``sigdata`` files. This command can be helpful when
trying to figure out what changed between two versions of a task. If you
call ``bitbake-diffsigs`` with just one file, the command behaves like
@@ -356,8 +359,12 @@ BitBake command-line options::
.. note::

Two common values for `SIGNATURE_HANDLER` are "none" and "printdiff", which
- dump only the signature or compare the dumped signature with the cached one,
- respectively.
+ dump only the signature or compare the dumped signature with the most recent one,
+ respectively. "printdiff" will try to establish the most recent
+ signature match (e.g. in the sstate cache) and then
+ compare the matched signatures to determine the stamps and delta
+ where these two stamp trees diverge. This can be used to determine why
+ tasks need to be re-run in situations where that is not expected.

Using BitBake with either of these options causes BitBake to dump out
``sigdata`` files in the ``stamps`` directory for every task it would
--
2.34.1