Skip building Doxygen when no documentation inputs have changed #6245
Draft
brtnfld wants to merge 9 commits intoHDFGroup:developfrom
Draft
Skip building Doxygen when no documentation inputs have changed #6245brtnfld wants to merge 9 commits intoHDFGroup:developfrom
brtnfld wants to merge 9 commits intoHDFGroup:developfrom
Conversation
Replace unconditional add_custom_target(... ALL COMMAND ...) with the stamp-file pattern (add_custom_command + DEPENDS) so that CMake can perform timestamp-based up-to-date checks. Doxygen is now only re-invoked when a tracked input file is newer than the stamp.
Add CONFIGURE_DEPENDS to file(GLOB_RECURSE) so that CMake automatically re-configures when files matching the patterns are added or removed. Quote all glob expressions to prevent issues with paths containing semicolons (CMake list separators).
Documentation targets (hdf5lib_doc, hdf5hllib_doc) no longer participate
in the default build. Docs are built on demand via the umbrella target:
cmake --build . --target doxygen
HDF5_BUILD_DOC already gates whether the doc infrastructure is configured,
so ALL was adding implicit cost to every build for users who simply wanted
docs available.
When HDF5_BUILD_DOC=ON, docs should build automatically on the first build and again whenever inputs change (handled by the stamp file). The umbrella "doxygen" target remains available for building docs independently of compilation.
The dependency lists now mirror the full set of FILE_PATTERNS and INPUT entries from Doxyfile.in. Previously missing inputs: - Fortran sources (fortran/src/*.F90, hl/fortran/src/*.F90) - C++ headers and sources (c++/src/*.h, c++/src/*.cpp) - Java sources (H5*.java, HDF*.java, exception classes) - Tool headers (h5copy.h, h5dump.h, h5diff_main.h, etc.) - HL tool header (h5watch.h) - Doxygen menu .md files (examples/menus/*.md)
Move the documentation block (find_package(Doxygen) and related setup) before add_subdirectory(src) so that DOXYGEN_FOUND is set when src/CMakeLists.txt processes. Previously, hdf5lib_doc was never created because add_subdirectory(src) ran before find_package(Doxygen). Also extract the shared doxygen content/configuration file patterns (*.dox, *.html, *.css, *.xml, *.js, menus/*.md) into a single HDF5_DOXYGEN_CONTENT_INPUTS list in the top-level CMakeLists.txt, eliminating the duplication between src/ and hl/src/.
Replace filesystem globs with the explicit header/source variables that
HDF5 already maintains where possible:
- src/: Use H5_PUBLIC_HEADERS and H5_GENERATED_HEADERS instead of
globbing H5*public.h, H5*module.h, H5*develop.h, H5FD*.h, etc.
- hl/src/: Use HL_HEADERS instead of globbing H5*public.h, H5*module.h.
Bindings in sibling subdirectory scopes (C++, Fortran, Java) still use
narrow, directory-scoped globs because their source lists are not
visible here — but without CONFIGURE_DEPENDS, so they do not penalize
null-build performance.
Drop CONFIGURE_DEPENDS from the top-level HDF5_DOXYGEN_CONTENT_INPUTS
glob as well: doxygen content/configuration files (*.dox, *.html, *.css)
change rarely in structure, and edits to existing files still trigger
the stamp-file rebuild correctly.
Replace 14 explicit tool header paths with a single-level wildcard
"${HDF5_TOOLS_SRC_DIR}/*/*.h" in the narrow directory glob. This
is cheap (one directory level, not recursive) and self-maintaining.
Also restructure the dependency gathering into three clearly numbered
steps: explicit core headers, narrow globs for encapsulated scopes,
and the shared doxygen content merge.
brtnfld
requested review from
bmribler,
derobins,
fortnern,
glennsong09,
jhendersonHDF,
lrknox,
mattjala,
qkoziol and
vchoi-hdfgroup
as code owners
Each language/tool subdirectory now appends its explicit source list to HDF5_DOXYGEN_LIB_INPUTS or HDF5_DOXYGEN_HL_INPUTS via set_property(GLOBAL APPEND PROPERTY ...). The hdf5lib_doc and hdf5hllib_doc targets are defined at the end of the top-level CMakeLists.txt, after all add_subdirectory() calls, where get_property() sees the fully-populated lists. Contributors: src/ H5_PUBLIC_HEADERS, H5_GENERATED_HEADERS, H5build_settings.c c++/src/ CPP_SOURCES, CPP_HDRS fortran/src/ f90_F_BASE_SOURCES tools/src/ explicit list of all tool *.h files hl/src/ HL_HEADERS, h5watch.h hl/fortran/src/ HDF5_HL_F90_F_BASE_SOURCES Java files are enumerated explicitly in the top-level end block via DOXYGEN_JAVA_DIR, matching the correct tree (JNI vs pure-Java). HDF5_DOXYGEN_CONTENT_INPUTS now uses CONFIGURE_DEPENDS so Ninja/Make automatically re-runs CMake when a .dox/.html/.css/.xml/.js/.md file is added or removed from the doxygen/ directory. This eliminates the need for file(GLOB) on source code entirely: adding a new language source to its explicit compile list automatically becomes a Doxygen dependency with no manual CMake re-run required.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Important
Optimize Doxygen build process by skipping rebuilds when input files are unchanged, using timestamp checks in CMake configuration.
CMakeLists.txt,hl/src/CMakeLists.txt, andsrc/CMakeLists.txt.hdf5lib_doc.stamp,hdf5hllib_doc.stamp) to track changes.add_custom_commandandadd_custom_targetused to manage Doxygen builds.CMakeLists.txtfor reuse.add_subdirectory(src)inCMakeLists.txtfor visibility of Doxygen variables.This description was created by
for 640cd81. You can customize this summary. It will automatically update as commits are pushed.