ref-manual: Fix PACKAGECONFIG term and add an example

PACKAGECONFIG's first and second flag value will be added to PACKAGECONFIG_CONFARGS
and then it will be added to the appropriate variable (EXTRA_OECMAKE, or ...)
So we need to only mention PACKAGECONFIG_CONFARGS and it will lead to other variables.

I added a custom example that can help understanding very well PACKAGECONFIG.

Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
---
 documentation/ref-manual/variables.rst | 40 ++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 6 deletions(-)

Hi Talel

On 16.10.23 at 19:11, BELHADJ SALEM Talel wrote:
> PACKAGECONFIG's first and second flag value will be added to PACKAGECONFIG_CONFARGS
> and then it will be added to the appropriate variable (EXTRA_OECMAKE, or ...)
> So we need to only mention PACKAGECONFIG_CONFARGS and it will lead to other variables.
>
> I added a custom example that can help understanding very well PACKAGECONFIG.
>
> Signed-off-by: Talel BELHAJSALEM <bhstalel@gmail.com>
> ---
>   documentation/ref-manual/variables.rst | 40 ++++++++++++++++++++++----
>   1 file changed, 34 insertions(+), 6 deletions(-)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 11523bb9e..2f286d26c 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -6059,13 +6059,11 @@ system and gives an overview of their function and contents.
>         omit any argument you like but must retain the separating commas. The
>         order is important and specifies the following:
>   
> -      #. Extra arguments that should be added to the configure script
> -         argument list (:term:`EXTRA_OECONF` or
> -         :term:`PACKAGECONFIG_CONFARGS`) if
> -         the feature is enabled.
> +      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
> +         if the feature is enabled.
>   
> -      #. Extra arguments that should be added to :term:`EXTRA_OECONF` or
> -         :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled.
> +      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
> +         if the feature is disabled.
>   
>         #. Additional build dependencies (:term:`DEPENDS`)
>            that should be added if the feature is enabled.
> @@ -6123,6 +6121,36 @@ system and gives an overview of their function and contents.
>   
>               PACKAGECONFIG:append:pn-recipename = " f4"
>   
> +      Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service
> +      in which :term:`PACKAGECONFIG` is used to transform the systemd service
> +      into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`::
> +
> +         example.c
> +         example.service
> +         CMakeLists.txt
> +
> +      The ``CMakeLists.txt`` file contains::
> +
> +         if(WITH_SYSTEMD)
> +            install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
> +         endif(WITH_SYSTEMD)
> +
> +      In order to enable the installation of ``example.service`` we need to ensure
> +      that `-DWITH_SYSTEMD=ON` is passed to the ``cmake`` command execution.
> +      Recipes that have ``CMakeLists.txt`` generally inherit :ref:`ref-classes-cmake`, that runs ``cmake``
> +      with :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be appended to.
> +      Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is automatically filled with either
> +      the first or second element of :term:`PACKAGECONFIG` flag value, the recipe would be like::
> +
> +         inherit cmake
> +         PACKAGECONFIG = "systemd"
> +         PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
> +
> +      A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
> +      or not::
> +
> +         PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
> +
>      :term:`PACKAGECONFIG_CONFARGS`
>         A space-separated list of configuration options generated from the
>         :term:`PACKAGECONFIG` setting.

Thanks for the update!
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
... and merged into master-next.

Cheers
Michael.