| Message ID | 20230506111025.18669-2-laurent.pinchart@ideasonboard.com |
|---|---|
| State | Accepted |
| Headers | show |
| Series |
|
| Related | show |
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@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@ideasonboard.com> > doxyfile = configure_file(input : 'Doxyfile.in', > output : 'Doxyfile', > configuration : cdata) > -- > Regards, > > Laurent Pinchart >
Hi Kieran, On Tue, May 09, 2023 at 01:29:18AM +0100, Kieran Bingham wrote: > 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@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 like this :-) > 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 ? I noticed this when developing patch 2/2, doxygen didn't warn me about missing documentation for the new IPAManager::pubKey() function. For the public API I fully agree with you, it should make no difference. For the internal API, it's not so clear cut. The documentation we publish on the website should cover all the internal API, but I understand it could be confusing for the developers if some features are not available in the version of libcamera they run. > But maybe it helps to have them defined to match the build for > consistency somewhere. > > Either way, > > Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > > doxyfile = configure_file(input : 'Doxyfile.in', > > output : 'Doxyfile', > > configuration : cdata)
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)) + doxyfile = configure_file(input : 'Doxyfile.in', output : 'Doxyfile', configuration : cdata)
libcamera creates a config.h file with predefine macros, and instructs 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@ideasonboard.com> --- Documentation/Doxyfile.in | 3 ++- Documentation/meson.build | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-)