Skip to contentSkip to conversation

Do proper dependency tracking for doxygen

PATCH Applied Bruce Richardson 3 participants 6 messages Jan 17, 2020 – Feb 15, 2020 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

cover Do proper dependency tracking for doxygen

When building doxygen docs as part of the build, there was no tracking being done of the files processed, so that doxygen can be re-run if needed. This patchset adds that tracking support, by generating a gcc-style ".d" file for the custom targets used in the doc/api build.

In doing so, we remove the doc directory as a custom target input path directly, which removes a warning from meson.

Bruce Richardson (2):
doc/api: generate dependency file for examples doc doc/api: track header files to rebuild docs on change

 doc/api/generate_doxygen.sh  | 5 ++++-
 doc/api/generate_examples.sh | 4 ++++
 doc/api/meson.build          | 8 ++++----
 3 files changed, 12 insertions(+), 5 deletions(-)
Signature · 1 line
2.20.1
#1 lore raw

PATCH 1/2 doc/api: generate dependency file for examples doc

For the doxygen API for the examples folder, we can generate a build dependency file when we generate the examples.dox file. This allows correct rebuilds if the files in examples change.

---
 doc/api/generate_examples.sh | 4 ++++
 doc/api/meson.build          | 5 ++---
 2 files changed, 6 insertions(+), 3 deletions(-)
doc/api/generate_examples.sh +4 -0
index 6fcfe513b..dae7ee0be 100755
@@ -5,6 +5,10 @@
 EXAMPLES_DIR=$1
 API_EXAMPLES=$2
 
+# generate a .d file including both C files and also build files, so we can
+# detect both file changes and file additions/deletions
+echo "$API_EXAMPLES: $(find ${EXAMPLES_DIR} -type f \( -name '*.c' -o -name 'meson.build' \) -printf '%p ' )" > ${API_EXAMPLES}.d
+
 exec > "${API_EXAMPLES}"
 printf '/**\n'
 printf '@page examples DPDK Example Programs\n\n'
doc/api/meson.build +2 -3
index c72b880e1..899e930fa 100644
@@ -15,7 +15,6 @@ generate_doxygen = find_program('generate_doxygen.sh')
 generate_examples = find_program('generate_examples.sh')
 generate_css = find_program('doxy-html-custom.sh')
 
-inputdir = join_paths(meson.source_root(), 'examples')
 htmldir = join_paths('share', 'doc', 'dpdk')
 
 # due to the following bug: https://github.com/mesonbuild/meson/issues/4107
@@ -24,9 +23,9 @@ htmldir = join_paths('share', 'doc', 'dpdk')
 # false it would be impossible to install the docs.
 # So use a configure option for now.
 example = custom_target('examples.dox',
-	input: inputdir,
 	output: 'examples.dox',
-	command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+	command: [generate_examples, join_paths(meson.source_root(), 'examples'), '@OUTPUT@'],
+	depfile: 'examples.dox.d',
 	install: get_option('enable_docs'),
 	install_dir: htmldir,
 	build_by_default: get_option('enable_docs'))
Signature · 1 line
2.20.1
Acked-by on v1 1/2
#2 lore raw

Re: [dpdk-dev] [PATCH 1/2] doc/api: generate dependency file for examples doc

Quoted 11 lines · Bruce Richardson

For the doxygen API for the examples folder, we can generate a build dependency file when we generate the examples.dox file. This allows correct rebuilds if the files in examples change.

Signed-off-by: Bruce Richardson <
[email protected]

Quoted 1 line
---
 doc/api/generate_examples.sh | 4 ++++
 doc/api/meson.build          | 5 ++---
 2 files changed, 6 insertions(+), 3 deletions(-)
Signature · 2 lines
Kind regards,
Luca Boccassi
#3 lore raw

PATCH 2/2 doc/api: track header files to rebuild docs on change

In reply to Bruce Richardson

Generate a dependency file for the header files used in the API guide so that the docs can be rebuilt if a header changes.

---
 doc/api/generate_doxygen.sh | 5 ++++-
 doc/api/meson.build         | 3 ++-
 2 files changed, 6 insertions(+), 2 deletions(-)
doc/api/generate_doxygen.sh +4 -1
index ab5766095..ee509e896 100755
@@ -6,5 +6,8 @@ DOXYCONF=$1
 OUTDIR=$2
 SCRIPTCSS=$3
 
-doxygen "${DOXYCONF}"
+# run doxygen, capturing all the header files it processed
+doxygen "${DOXYCONF}" | tee doxygen.out
+echo "$OUTDIR: $(awk '/Preprocessing/ {printf("%s ", substr($2, 1, length($2) - 3))}' doxygen.out)" > $OUTDIR.d
+
 "${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
doc/api/meson.build +2 -1
index 899e930fa..49d5b9a15 100644
@@ -15,7 +15,7 @@ generate_doxygen = find_program('generate_doxygen.sh')
 generate_examples = find_program('generate_examples.sh')
 generate_css = find_program('doxy-html-custom.sh')
 
-htmldir = join_paths('share', 'doc', 'dpdk')
+htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
 
 # due to the following bug: https://github.com/mesonbuild/meson/issues/4107
 # if install is set to true it will override build_by_default and it will
@@ -46,6 +46,7 @@ doxy_build = custom_target('doxygen',
 	depends: example,
 	input: doxy_conf,
 	output: 'api',
+	depfile: 'api.d',
 	command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
 	install: get_option('enable_docs'),
 	install_dir: htmldir,
Signature · 1 line
2.20.1
Acked-by on v1 2/2
#4 lore raw

Re: [dpdk-dev] [PATCH 2/2] doc/api: track header files to rebuild docs on change

Quoted 10 lines · Bruce Richardson

Generate a dependency file for the header files used in the API guide so that the docs can be rebuilt if a header changes.

Signed-off-by: Bruce Richardson <
[email protected]

Quoted 1 line
---
 doc/api/generate_doxygen.sh | 5 ++++-
 doc/api/meson.build         | 3 ++-
 2 files changed, 6 insertions(+), 2 deletions(-)
Signature · 2 lines
Kind regards,
Luca Boccassi
#5 lore raw
In reply to Bruce Richardson

17/01/2020 12:22, Bruce Richardson:

Quoted 11 lines

When building doxygen docs as part of the build, there was no tracking being done of the files processed, so that doxygen can be re-run if needed. This patchset adds that tracking support, by generating a gcc-style ".d" file for the custom targets used in the doc/api build.

In doing so, we remove the doc directory as a custom target input path directly, which removes a warning from meson.

Bruce Richardson (2):
doc/api: generate dependency file for examples doc doc/api: track header files to rebuild docs on change

Applied, thanks