[PATCH 0/3] BitBake user manual updates for 2.4

[PATCH 0/3] BitBake user manual updates for 2.4

[Paul Eggleton]

Documentation updates for the 2.4 branch / master (to correspond with
the Yocto Project 4.2 release).

Note: I am electing to add BB_GLOBAL_PYMODULES and BB_HASH_CODEPARSER_VALS
here without pointers from the Yocto reference manual currently, since they
are highly specialized.


The following changes since commit 66131fa6a3e12c28710d09e1dbf3c03f2981280d:

  cooker: do not abort on single ctrl-c (2023-04-20 12:36:18 +0100)

are available in the Git repository at:

  https://git.openembedded.org/bitbake-contrib paule/doc-updates-2.4
  http://cgit.openembedded.org/bitbake-contrib/log/?h=paule/doc-updates-2.4

Paul Eggleton (3):
  bitbake-user-manual: document BB_CACHEDIR
  bitbake-user-manual: add addpylib and BB_GLOBAL_PYMODULES
  bitbake-user-manual: add BB_HASH_CODEPARSER_VALS

 .../bitbake-user-manual-metadata.rst          | 18 ++++++++++++++
 .../bitbake-user-manual-ref-variables.rst     | 24 +++++++++++++++++++
 2 files changed, 42 insertions(+)

-- 
2.34.1

[PATCH 1/3] bitbake-user-manual: document BB_CACHEDIR

[Paul Eggleton]

New variable for 2.4.

Signed-off-by: Paul Eggleton <bluelightning@bluelightning.org>
---
 .../bitbake-user-manual-ref-variables.rst                    | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
index 25620fdda1..1cf37d5fcd 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -99,6 +99,11 @@ overview of their function and contents.
       the path of the build. BitBake's output should not (and usually does
       not) depend on the directory in which it was built.
 
+   :term:`BB_CACHEDIR`
+      Specifies the code parser cache directory (distinct from :term:`CACHE`
+      and :term:`PERSISTENT_DIR` although they can be set to the same value
+      if desired). The default value is "${TOPDIR}/cache".
+
    :term:`BB_CHECK_SSL_CERTS`
       Specifies if SSL certificates should be checked when fetching. The default
       value is ``1`` and certificates are not checked if the value is set to ``0``.
-- 
2.34.1

[PATCH 2/3] bitbake-user-manual: add addpylib and BB_GLOBAL_PYMODULES

[Paul Eggleton]

New directive and variable for 2.4.

Signed-off-by: Paul Eggleton <bluelightning@bluelightning.org>
---
 .../bitbake-user-manual-metadata.rst           | 18 ++++++++++++++++++
 .../bitbake-user-manual-ref-variables.rst      |  8 ++++++++
 2 files changed, 26 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index ba8129afab..b35c332c82 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1972,6 +1972,24 @@ looking at the source code of the ``bb`` module, which is in
 the commonly used functions ``bb.utils.contains()`` and
 ``bb.utils.mkdirhier()``, which come with docstrings.
 
+Extending Python Library Code
+-----------------------------
+
+If you wish to add your own Python library code (e.g. to provide
+functions/classes you can use from Python functions in the metadata)
+you can do so from any layer using the ``addpylib`` directive.
+This directive is typically added to your layer configuration (
+``conf/layer.conf``) although it will be handled in any ``.conf`` file.
+
+Usage is of the form::
+
+   addpylib <directory> <namespace>
+
+Where <directory> specifies the directory to add to the library path.
+The specified <namespace> is imported automatically, and if the imported
+module specifies an attribute named ``BBIMPORTS``, that list of
+sub-modules is iterated and imported too.
+
 Testing and Debugging BitBake Python code
 -----------------------------------------
 
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
index 1cf37d5fcd..fc7cb88238 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -348,6 +348,14 @@ overview of their function and contents.
 
       For example usage, see :term:`BB_GIT_SHALLOW`.
 
+   :term:`BB_GLOBAL_PYMODULES`
+      Specifies the list of Python modules to place in the global namespace.
+      It is intended that only the core layer should set this and it is meant
+      to be a very small list, typically just ``os`` and ``sys``.
+      :term:`BB_GLOBAL_PYMODULES` is expected to be set before the first
+      ``addpylib`` directive.
+      See also ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:extending python library code`".
+
    :term:`BB_HASHCHECK_FUNCTION`
       Specifies the name of the function to call during the "setscene" part
       of the task's execution in order to validate the list of task hashes.
-- 
2.34.1

[PATCH 3/3] bitbake-user-manual: add BB_HASH_CODEPARSER_VALS

[Paul Eggleton]

New variable for 2.4.

Signed-off-by: Paul Eggleton <bluelightning@bluelightning.org>
---
 .../bitbake-user-manual-ref-variables.rst             | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
index fc7cb88238..6ccf58b212 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -108,6 +108,17 @@ overview of their function and contents.
       Specifies if SSL certificates should be checked when fetching. The default
       value is ``1`` and certificates are not checked if the value is set to ``0``.
 
+   :term:`BB_HASH_CODEPARSER_VALS`
+      Specifies values for variables to use when populating the codeparser cache.
+      This can be used selectively to set dummy values for variables to avoid
+      the codeparser cache growing on every parse. Variables that would typically
+      be included are those where the value is not significant for where the
+      codeparser cache is used (i.e. when calculating variable dependencies for
+      code fragments.) The value is space-separated without quoting values, for
+      example::
+
+         BB_HASH_CODEPARSER_VALS = "T=/ WORKDIR=/ DATE=1234 TIME=1234"
+
    :term:`BB_CONSOLELOG`
       Specifies the path to a log file into which BitBake's user interface
       writes output during the build.
-- 
2.34.1

Re: [bitbake-devel] [PATCH 0/3] BitBake user manual updates for 2.4

[Richard Purdie]

On Sat, 2023-04-22 at 15:05 +1200, Paul Eggleton wrote:
> Documentation updates for the 2.4 branch / master (to correspond with
> the Yocto Project 4.2 release).

Thanks for catching these. I wish we could do a better job as we go
along but it is hard with the resources we have. Sadly I'm probably
guilty of not adding some of these.

> Note: I am electing to add BB_GLOBAL_PYMODULES and BB_HASH_CODEPARSER_VALS
> here without pointers from the Yocto reference manual currently, since they
> are highly specialized.

I agree that makes sense as those are only really meant to be used by
the core.

Cheers,

Richard