Skip to contentSkip to conversation

docs: make DISTRO_FEATURES examples more explicit

PATCH In review Aatir Manzur 3 participants 3 messages Jun 23, 2022 – Jul 4, 2022

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: make DISTRO_FEATURES examples more explicit

Make DISTRO_FEATURES example more explicit by specifying that DISTRO_FEATURES alone can't select build configurations, and need mechanisms like PACKAGECONFIG setup to take care of selecting build configurations.

Signed-off-by Aatir Manzur <[email protected]>

---
 documentation/ref-manual/features.rst  | 4 +++-
 documentation/ref-manual/variables.rst | 5 ++++-
 2 files changed, 7 insertions(+), 2 deletions(-)
documentation/ref-manual/features.rst +3 -1
index a8d0dac99..6f9edf1a1 100644
@@ -100,7 +100,9 @@ packages, and they can go beyond simply controlling the installation of
 a package or packages. In most cases, the presence or absence of a
 feature translates to the appropriate option supplied to the configure
 script during the :ref:`ref-tasks-configure` task for
-the recipes that optionally support the feature.
+the recipes that optionally support the feature. Appropriate options
+must be supplied, and enabling/disabling :term `PACKAGECONFIG` for the
+concerned packages is one way of supplying such options.
 
 Some distro features are also machine features. These select features
 make sense to be controlled both at the machine and distribution
documentation/ref-manual/variables.rst +4 -1
index 28267101d..48bdf3810 100644
@@ -1873,7 +1873,10 @@ system and gives an overview of their function and contents.
       optionally support the feature. For example, specifying "x11" in
       :term:`DISTRO_FEATURES`, causes every piece of software built for the
       target that can optionally support X11 to have its X11 support
-      enabled.
+      enabled. Note: just enabling :term: `DISTRO_FEATURES` alone doesn't
+      enable feature support for packages, mechanisms such as making
+      :term `PACKAGECONFIG` track :iterm: `DISTRO_FEATURES` are used
+      to enable/disbale package features.
 
       Two more examples are Bluetooth and NFS support. For a more complete
       list of features that ships with the Yocto Project and that you can
Signature · 1 line
2.31.0
#1 lore raw

Hi Aatir,

Many thanks for the patch!
Here are my comments...

Quoted 4 lines · aatir

Make DISTRO_FEATURES example more explicit by specifying that DISTRO_FEATURES alone can't select build configurations, and need mechanisms like PACKAGECONFIG setup to take care of selecting build configurations.

I would talk about "DISTRO_FEATURES example" but instead "DISTRO_FEATURES description" here.

Quoted 12 lines

Signed-off-by Aatir Manzur <[email protected]>

---
  documentation/ref-manual/features.rst  | 4 +++-
  documentation/ref-manual/variables.rst | 5 ++++-
  2 files changed, 7 insertions(+), 2 deletions(-)
documentation/ref-manual/features.rst +0 -0
index a8d0dac99..6f9edf1a1 100644

documentation/ref-manual/features.rst packages, and they can go beyond simply controlling the installation of · line 104

Quoted 6 lines
documentation/ref-manual/features.rst +2 -1
@@ -100,7 +100,9 @@ packages, and they can go beyond simply controlling the installation of
  a package or packages. In most cases, the presence or absence of a
  feature translates to the appropriate option supplied to the configure
  script during the :ref:`ref-tasks-configure` task for
-the recipes that optionally support the feature.
+the recipes that optionally support the feature. Appropriate options
+must be supplied, and enabling/disabling :term `PACKAGECONFIG` for the

Oops, there should be no space between ":term:" and "PACKAGECONFIG", otherwise Sphinx doesn't create a reference. You have multiple instances of this issue.

Quoted 9 lines
documentation/ref-manual/features.rst +1 -0
+concerned packages is one way of supplying such options.
 
  Some distro features are also machine features. These select features
  make sense to be controlled both at the machine and distribution
documentation/ref-manual/variables.rst +0 -0
index 28267101d..48bdf3810 100644

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1877

Quoted 6 lines
documentation/ref-manual/variables.rst +2 -1
@@ -1873,7 +1873,10 @@ system and gives an overview of their function and contents.
        optionally support the feature. For example, specifying "x11" in
        :term:`DISTRO_FEATURES`, causes every piece of software built for the
        target that can optionally support X11 to have its X11 support
-      enabled.
+      enabled. Note: just enabling :term: `DISTRO_FEATURES` alone doesn't
+      enable feature support for packages, mechanisms such as making

Same issue here

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1879

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+      :term `PACKAGECONFIG` track :iterm: `DISTRO_FEATURES` are used
+      to enable/disbale package features.

s/:iterm:/:term:/

Would you mind sending an updated patch, please?
Thanks again
Michael

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#2 lore raw

Hi Aatir,

Quoted 36 lines · Michael Opdenacker via lists.yoctoproject.org

Hi Aatir,

Many thanks for the patch!
Here are my comments...

Quoted 4 lines · aatir

Make DISTRO_FEATURES example more explicit by specifying that DISTRO_FEATURES alone can't select build configurations, and need mechanisms like PACKAGECONFIG setup to take care of selecting build configurations.

I would talk about "DISTRO_FEATURES example" but instead "DISTRO_FEATURES description" here.

Quoted 16 lines

Signed-off-by Aatir Manzur <[email protected]>
---
  documentation/ref-manual/features.rst  | 4 +++- documentation/ref-manual/variables.rst | 5 ++++-

  2 files changed, 7 insertions(+), 2 deletions(-)
documentation/ref-manual/features.rst +0 -0
index a8d0dac99..6f9edf1a1 100644
@@ -100,7 +100,9 @@ packages, and they can go beyond simply 

controlling the installation of
  a package or packages. In most cases, the presence or absence of a feature translates to the appropriate option supplied to the configure script during the :ref:ref-tasks-configure task for

documentation/ref-manual/features.rst packages, and they can go beyond simply controlling the installation of · line 104

Quoted 3 lines
documentation/ref-manual/features.rst +2 -1
-the recipes that optionally support the feature.
+the recipes that optionally support the feature. Appropriate options
+must be supplied, and enabling/disabling :term `PACKAGECONFIG` for the

Oops, there should be no space between ":term:" and "PACKAGECONFIG", otherwise Sphinx doesn't create a reference. You have multiple instances of this issue.

Quoted 17 lines
Quoted 8 lines

+concerned packages is one way of supplying such options. Some distro features are also machine features. These select features make sense to be controlled both at the machine and distribution

documentation/ref-manual/variables.rst +0 -0
index 28267101d..48bdf3810 100644
@@ -1873,7 +1873,10 @@ system and gives an overview of their function 
Quoted 8 lines

and contents.
        optionally support the feature. For example, specifying "x11" in :term:DISTRO_FEATURES, causes every piece of software built for the target that can optionally support X11 to have its X11 support -      enabled.
+      enabled. Note: just enabling :term: DISTRO_FEATURES alone doesn't
+      enable feature support for packages, mechanisms such as making

I would use .. note:: directive here instead of Note:. This way it is properly highlighted by Sphinx and the user won't miss this important piece of information.

Cheers,
Quentin