diff mbox series

[3/4] doc: bitbake-user-manual-ref-variables: clarify BBMASK matching patterns

Message ID 20260211-bbmask-slashes-v1-3-b72161c647ef@cherry.de
State New
Headers show
Series doc: bitbake-user-manual-ref-variables: clarify BBMASK examples | expand

Commit Message

Quentin Schulz Feb. 11, 2026, 6:06 p.m. UTC 
From: Quentin Schulz <quentin.schulz@cherry.de>

The documentation doesn't explain the side-effect of putting a leading
slash, only the trailing slash.

The leading slash is not for making the regular expression match an
absolute path, but to force the match on the directory or file that
exactly starts (and ends if there is a trailing slash) with the
specified string.

Finally, this also explains that this still doesn't prevent more than
the intended path to be caught up, specifically because it is NOT a
regular expression matching an absolute path. For that though, the user
can use BBFILE_PATTERN set for the layer they want to mask the recipe or
append files to BitBake. This is typically a regex starting with
^${LAYERDIR}, making it an absolute path matching.

Let's document those limitations.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-ref-variables.rst          | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
diff mbox series

Patch

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 f20a9012c..6612dcc03 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1071,6 +1071,28 @@  overview of their function and contents.
          When specifying a directory name, use the trailing slash character
          to ensure you match just that directory name.
 
+      .. note::
+
+         The leading slash in a regular expression in :term:`BBMASK` does not
+         mean the path is absolute. It simply forces the directory to be named
+         exactly that. Take::
+
+            BBMASK = "meta-ti/recipes-bsp/"
+
+        If you happen to have a directory ``my-meta-ti/recipes-bsp``, it will
+        be matched.
+
+        Leading with a slash::
+
+           BBMASK = "/meta-ti/recipes-bsp/"
+
+        makes sure that doesn't happen. However, this doesn't prevent matching a
+        directory ``meta-foo/meta-ti/recipes-bsp``. For that, use the
+        appropriate :term:`BBFILE_PATTERN` to only match a directory from one
+        specific layer::
+
+           BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
+
    :term:`BBMULTICONFIG`
       Enables BitBake to perform multiple configuration builds and lists
       each separate configuration (multiconfig). You can use this variable