From 1d1c19091f13b7e19015698a23f454aa85f17ac3 Mon Sep 17 00:00:00 2001 From: yuangongji <82787816@qq.com> Date: Fri, 23 Aug 2019 21:48:05 +0800 Subject: [PATCH] cmake: attach doxygen target into all target v2: Disable non-html generator for doxygen by default v3: convert cmake option to doxygen config --- .gitignore | 7 ++- CMakeLists.txt | 12 ++--- Documentation/Building.md | 3 ++ Makefile.am | 1 + cmake/UseDoxygen.cmake | 111 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 126 insertions(+), 8 deletions(-) create mode 100644 cmake/UseDoxygen.cmake diff --git a/.gitignore b/.gitignore index 2d70fa6b..d7f5e5f7 100644 --- a/.gitignore +++ b/.gitignore @@ -64,7 +64,6 @@ cscope* /m4/ltversion.m4 /m4/lt~obsolete.m4 -/doxygen /aclocal.m4 compile config.cache @@ -84,6 +83,12 @@ missing stamp-h1 stamp-h2 +# files generated by doxygen +doxygen +CMakeDoxyfile.in +CMakeDoxygenDefaults.cmake +Doxyfile.doxygen + # sample binaries dns-example event-read-fifo diff --git a/CMakeLists.txt b/CMakeLists.txt index 458dcdce..b562c6b0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1493,13 +1493,11 @@ install(PROGRAMS COMPONENT runtime) # Create documents with doxygen. -find_program(DOXYGEN doxygen) -if (DOXYGEN) - add_custom_target(doxygen - COMMAND ${DOXYGEN} Doxyfile - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) -else() - message(WARNING "The doxygen target will not support since doxygen command was not found!") +option(EVENT__DOXYGEN + "Enables doxygen documentation" OFF) +if (EVENT__DOXYGEN) + include(UseDoxygen) + UseDoxygen() endif() diff --git a/Documentation/Building.md b/Documentation/Building.md index 22dd4e2f..9ee71e09 100644 --- a/Documentation/Building.md +++ b/Documentation/Building.md @@ -119,6 +119,9 @@ EVENT__ENABLE_VERBOSE_DEBUG:BOOL=OFF # on the the cross compilation target to verify that it works. See CMake # documentation for try_run for more details EVENT__FORCE_KQUEUE_CHECK:BOOL=OFF + +# Build documentation with doxygen +EVENT__DOXYGEN:BOOL=OFF ``` __More variables can be found by running `cmake -LAH `__ diff --git a/Makefile.am b/Makefile.am index 1be4d27a..d34726f3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -128,6 +128,7 @@ CMAKE_FILES = \ cmake/LibeventConfigVersion.cmake.in \ cmake/VersionViaGit.cmake \ cmake/Uninstall.cmake.in \ + cmake/UseDoxygen.cmake \ event-config.h.cmake \ evconfig-private.h.cmake \ CMakeLists.txt diff --git a/cmake/UseDoxygen.cmake b/cmake/UseDoxygen.cmake new file mode 100644 index 00000000..3b60d5a0 --- /dev/null +++ b/cmake/UseDoxygen.cmake @@ -0,0 +1,111 @@ +# Use FindDoxygen.cmake to generate documentation. + +option(DOXYGEN_GENERATE_HTML "Generate HTML" ON) +option(DOXYGEN_GENERATE_MAN "Generate man pages" OFF) +option(DOXYGEN_MAN_LINKS "Generate man links" ON) +option(DOXYGEN_GENERATE_LATEX "Generate LaTeX" OFF) + +# If the case-insensitive value of the cmake option is one of +# "off, no, false" or 0, it is equal to false, otherwise true. +# And the values of the doxygen config does not exactly match it. +# So we need to convert the cmake option to a doxygen config. +macro(_convert_to_dx_cfg CMK_OPTION) + if (${CMK_OPTION}) + set(${CMK_OPTION} YES) + else() + set(${CMK_OPTION} NO) + endif() +endmacro() + +macro(UseDoxygen) + if (${CMAKE_VERSION} VERSION_LESS "3.9") + # Old versions of cmake have poor support for Doxygen generation. + message(FATAL_ERROR "Doxygen generation only enabled for cmake 3.9 and higher") + else() + find_package(Doxygen) + if (DOXYGEN_FOUND) + set(DOXYGEN_PROJECT_NAME ${PROJECT_NAME}) + set(DOXYGEN_PROJECT_NUMBER ${EVENT_PACKAGE_VERSION}) + set(DOXYGEN_PROJECT_BRIEF "Event notification library") + set(DOXYGEN_OUTPUT_DIRECTORY doxygen) + set(DOXYGEN_STRIP_FROM_PATH include) + set(DOXYGEN_JAVADOC_AUTOBRIEF YES) + set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set(DOXYGEN_SORT_BRIEF_DOCS YES) + set(DOXYGEN_RECURSIVE NO) + + _convert_to_dx_cfg(DOXYGEN_GENERATE_HTML) + _convert_to_dx_cfg(DOXYGEN_GENERATE_MAN) + _convert_to_dx_cfg(DOXYGEN_MAN_LINKS) + _convert_to_dx_cfg(DOXYGEN_GENERATE_LATEX) + + set(DOXYGEN_LATEX_CMD_NAME latex) + set(DOXYGEN_PAPER_TYPE a4wide) + set(DOXYGEN_PDF_HYPERLINKS NO) + + set(DOXYGEN_GENERATE_RTF NO) + set(DOXYGEN_GENERATE_XML NO) + set(DOXYGEN_GENERATE_CHI NO) + + set(DOXYGEN_PREDEFINED TAILQ_ENTRY + RB_ENTRY + EVENT_DEFINED_TQENTRY_ + EVENT_IN_DOXYGEN_ + ) + + set(DOX_INPUT include/event2/buffer.h + include/event2/buffer_compat.h + include/event2/bufferevent.h + include/event2/bufferevent_compat.h + include/event2/bufferevent_ssl.h + include/event2/dns.h + include/event2/dns_compat.h + include/event2/event.h + include/event2/event_compat.h + include/event2/http.h + include/event2/http_compat.h + include/event2/listener.h + include/event2/rpc.h + include/event2/rpc_compat.h + include/event2/tag.h + include/event2/tag_compat.h + include/event2/thread.h + include/event2/util.h + ) + # Add 'doxygen' target + doxygen_add_docs(doxygen + ${DOX_INPUT} + ALL + WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} + COMMENT "Generating doxygen documentation for ${PROJECT_NAME}..." + ) + + # Use 'make clean' to remove the generated directory + set_property(DIRECTORY + PROPERTY ADDITIONAL_MAKE_CLEAN_FILES + "${PROJECT_BINARY_DIR}/${DOXYGEN_OUTPUT_DIRECTORY}" + ) + + # Install html into /share/doc/ + if ("${DOXYGEN_GENERATE_HTML}" STREQUAL "YES") + install(DIRECTORY + ${PROJECT_BINARY_DIR}/${DOXYGEN_OUTPUT_DIRECTORY}/html + DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/${PROJECT_NAME} + COMPONENT doc + ) + endif() + + # Install manual into /share/man/man3 + if ("${DOXYGEN_GENERATE_MAN}" STREQUAL "YES") + install(DIRECTORY + ${PROJECT_BINARY_DIR}/${DOXYGEN_OUTPUT_DIRECTORY}/man/man3 + DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man + COMPONENT doc + ) + endif() + + else(DOXYGEN_FOUND) + message(FATAL_ERROR "Doxygen command not found, set EVENT__DOXYGEN to disable") + endif (DOXYGEN_FOUND) + endif() +endmacro()