diff mbox series

ref-manual/variables.rst: improve the PKGV documentation

Message ID 20250325-better-pkgv-desc-v1-1-7febf4c713ce@bootlin.com
State Under Review
Headers show
Series ref-manual/variables.rst: improve the PKGV documentation | expand

Commit Message

Antonin Godard March 25, 2025, 11:13 a.m. UTC 
It may be confusing for users that source control information is not
present in the BitBake environment. Document it as a warning block.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)


---
base-commit: ee6b3698da044e290dbc4fbb852f3cc37638e689
change-id: 20250325-better-pkgv-desc-9aedfcf2f5c2

Best regards,
diff mbox series

Patch

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 41bda5d0d..bf1f35d2d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6771,6 +6771,23 @@  system and gives an overview of their function and contents.
       The version of the package(s) built by the recipe. By default,
       :term:`PKGV` is set to :term:`PV`.
 
+      If :term:`PV` contains the ``+`` sign, source control information will be
+      included in :term:`PKGV` later in the packaging phase. For more
+      information, see the :doc:`/dev-manual/external-scm` section of the Yocto
+      Project Development Tasks Manual.
+
+      .. warning::
+
+         Since source control information is included in a late stage by the
+         :ref:`ref-classes-package` class, it cannot be seen from the BitBake
+         environment with ``bitbake -e`` or ``bitbake-getvar``. Instead, after
+         the package is built, the version information can be retrieved with
+         ``oe-pkgdata-util package-info <package name>``. See the
+         :ref:`dev-manual/debugging:Viewing Package Information with
+         \`\`oe-pkgdata-util\`\`` section of the Yocto Project Development Tasks
+         Manual for more information on ``oe-pkgdata-util``.
+
+
    :term:`PN`
       This variable can have two separate functions depending on the
       context: a recipe name or a resulting package name.