[PATCH] documentation: bitbake: add file-checksums to varflags section

[PATCH] documentation: bitbake: add file-checksums to varflags section

[Richard Elberger]

Fixes [YOCTO #11605] by:

- Adding definition of file-checksums to Variable Flags section.
- Describe data to add to list which adds external file dependencies.
- Write example on usage to prepend a value to file-checksums list.

Signed-off-by: Richard Elberger <rich@richelberger.com>
---
 .../bitbake-user-manual-metadata.rst                  | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index deb7afad..c2f0cad2 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1496,6 +1496,17 @@ functionality of the task:
    directory listed is used as the current working directory for the
    task.
 
+- ``[file-checksums]``: Controls the file dependencies for a task. The
+  baseline file list is the set of files associated with
+  :term:`SRC_URI`. May be used to set additional dependencies on
+  files not associated with :term:`SRC_URI`.
+
+  The value set to the list is a pair where the first value is the
+  file name and the second is whether or not it physically exists on
+  the filesystem. ::
+
+    do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True"
+
 -  ``[lockfiles]``: Specifies one or more lockfiles to lock while the
    task executes. Only one task may hold a lockfile, and any task that
    attempts to lock an already locked file will block until the lock is
-- 
2.34.1

Re: [docs] [PATCH] documentation: bitbake: add file-checksums to varflags section

[Richard Purdie]

On Fri, 2023-02-24 at 20:14 +0000, Richard Elberger wrote:
> Fixes [YOCTO #11605] by:
> 
> - Adding definition of file-checksums to Variable Flags section.
> - Describe data to add to list which adds external file dependencies.
> - Write example on usage to prepend a value to file-checksums list.
> 
> Signed-off-by: Richard Elberger <rich@richelberger.com>
> ---
>  .../bitbake-user-manual-metadata.rst                  | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index deb7afad..c2f0cad2 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -1496,6 +1496,17 @@ functionality of the task:
>     directory listed is used as the current working directory for the
>     task.
>  
> +- ``[file-checksums]``: Controls the file dependencies for a task. The
> +  baseline file list is the set of files associated with
> +  :term:`SRC_URI`. May be used to set additional dependencies on
> +  files not associated with :term:`SRC_URI`.
> +
> +  The value set to the list is a pair where the first value is the
> +  file name and the second is whether or not it physically exists on
> +  the filesystem. ::
> +
> +    do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True"
> +

Thanks, this is good to document. We should probably add that:

"""
It is important to record any paths which the task looked at and which
didn't exist. This means that if these do exist at a later time, the
task can be rerun with the new additional files. The "exists" True or
False value after the path allows this to be handled.
"""

Cheers,

Richard

Re: [docs] [PATCH] documentation: bitbake: add file-checksums to varflags section

[Richard Elberger]

Hello Richard, I have added this, amended the commit, and sent through 
another patch.

On 2/24/23 16:33, Richard Purdie wrote:
> It is important to record any paths which the task looked at and which
> didn't exist. This means that if these do exist at a later time, the
> task can be rerun with the new additional files. The "exists" True or
> False value after the path allows this to be handled.

Re: [docs] [PATCH] documentation: bitbake: add file-checksums to varflags section

[Richard Purdie]

On Sat, 2023-02-25 at 16:36 +0000, Richard Elberger wrote:
> Hello Richard, I have added this, amended the commit, and sent through 
> another patch.

Thanks! I've merged it. If there are other tweaks others want to
make/add we can build on this incrementally, it is great to get it
documented.

Cheers,

Richard