[libcamera-devel] [PATCH v1 1/2] Documentation: Add predefined macros from config.h to Doxyfile

[Kieran Bingham]

Quoting Laurent Pinchart via libcamera-devel (2023-05-06 12:10:24)
> libcamera creates a config.h file with predefine macros, and instructs

/predefine/predefined/

> the compiler to include it implicitly with the -include argument.
> Doxygen has no support for implicit inclusion of headers, but has a
> PREDEFINED configuration option for its preprocessor that lists
> predefined macros. Populate it with the values from the config_h
> configuration data object that is used for generate the config.h file,
> to ensure that documentation matches the configuration options libcamera
> has been built with.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> ---
>  Documentation/Doxyfile.in | 3 ++-
>  Documentation/meson.build | 7 +++++++
>  2 files changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index 1447abdb7d8c..697a14d1dfe2 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -80,6 +80,7 @@ INCLUDE_FILE_PATTERNS  = *.h
>  
>  PREDEFINED             = __DOXYGEN__ \
>                           __cplusplus \
> -                         __attribute__(x)=
> +                         __attribute__(x)= \
> +                        @PREDEFINED@
>  
>  HAVE_DOT               = YES
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 186461561f8d..ed581163345e 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -16,6 +16,13 @@ if doxygen.found() and dot.found()
>      cdata.set('TOP_BUILDDIR', meson.project_build_root())
>      cdata.set('OUTPUT_DIR', meson.current_build_dir())
>  
> +    doxygen_predefined = []
> +    foreach key : config_h.keys()
> +        doxygen_predefined += '@0@=@1@'.format(key, config_h.get(key))
> +    endforeach
> +
> +    cdata.set('PREDEFINED', ' '.join(doxygen_predefined))
> +

Going for a quick test, this generates:

PREDEFINED             = __DOXYGEN__ \
                         __cplusplus \
                         __attribute__(x)= \
                         HAVE_BACKTRACE=1 HAVE_DW=1 HAVE_GNUTLS=1 HAVE_IPA_PUBKEY=1 HAVE_LIBUDEV=1 HAVE_LOCALE_T=1 HAVE_SECURE_GETENV=1 HAVE_TRACING=1 HAVE_UNWIND=1 IPA_CONFIG_DIR="/etc/libcamera/ipa:/usr/share/libcamera/ipa" IPA_MODULE_DIR="/usr/lib/x86_64-linux-gnu/libcamera" IPA_PROXY_DIR="/usr/libexec/libcamera" LIBCAMERA_DATA_DIR="/usr/share/libcamera" LIBCAMERA_SYSCONF_DIR="/etc/libcamera"

Which looks reasonable to me.

You could go one step further and match the style of the rest of the
file though which makes it easier to parse. Though it's unlikely for
someone to be reading this specifically! (Unless they're checking the
Doxyfile for parsing issues which maybe more readability would help!?)


-    cdata.set('PREDEFINED', ' '.join(doxygen_predefined))
+    cdata.set('PREDEFINED', ' \\\n\t\t\t '.join(doxygen_predefined))


Makes a cleaner:

PREDEFINED             = __DOXYGEN__ \
                         __cplusplus \
                         __attribute__(x)= \
                         HAVE_BACKTRACE=1 \
                         HAVE_DW=1 \
                         HAVE_GNUTLS=1 \
                         HAVE_IPA_PUBKEY=1 \
                         HAVE_LIBUDEV=1 \
                         HAVE_LOCALE_T=1 \
                         HAVE_SECURE_GETENV=1 \
                         HAVE_TRACING=1 \
                         HAVE_UNWIND=1 \
                         IPA_CONFIG_DIR="/etc/libcamera/ipa:/usr/share/libcamera/ipa" \
                         IPA_MODULE_DIR="/usr/lib/x86_64-linux-gnu/libcamera" \
                         IPA_PROXY_DIR="/usr/libexec/libcamera" \
                         LIBCAMERA_DATA_DIR="/usr/share/libcamera" \
                         LIBCAMERA_SYSCONF_DIR="/etc/libcamera"

I'm a bit bemused about how any of those would be relevant for the
documentation yet though. How we build the documentation shouldn't be
based upon any of those keys ?

But maybe it helps to have them defined to match the build for
consistency somewhere.

Either way,

Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>



>      doxyfile = configure_file(input : 'Doxyfile.in',
>                                output : 'Doxyfile',
>                                configuration : cdata)
> -- 
> Regards,
> 
> Laurent Pinchart
>