From 320b6c0cd8db2acaf09d1259b9efeb653cecf8d8 Mon Sep 17 00:00:00 2001 From: Andreas Schneider Date: Sun, 4 Apr 2010 13:38:36 +0200 Subject: Added an improved version of UseDoxygen.cmake which handles trac doc. --- cmake/Modules/UseDoxygen.cmake | 197 +++++++++++++++++------------------------ 1 file changed, 80 insertions(+), 117 deletions(-) (limited to 'cmake/Modules') diff --git a/cmake/Modules/UseDoxygen.cmake b/cmake/Modules/UseDoxygen.cmake index 541dace..0a190c3 100644 --- a/cmake/Modules/UseDoxygen.cmake +++ b/cmake/Modules/UseDoxygen.cmake @@ -1,134 +1,97 @@ -# -helper macro to add a "doc" target with CMake build system. -# and configure doxy.config.in to doxy.config +# - Run Doxygen # -# target "doc" allows building the documentation with doxygen/dot on WIN32 and Linux -# Creates .chm windows help file if MS HTML help workshop -# (available from http://msdn.microsoft.com/workshop/author/htmlhelp) -# is installed with its DLLs in PATH. +# Adds a doxygen target that runs doxygen to generate the html +# and optionally the LaTeX API documentation. +# The doxygen target is added to the doc target as dependency. +# i.e.: the API documentation is built with: +# make doc # +# USAGE: INCLUDE IN PROJECT # -# Please note, that the tools, e.g.: -# doxygen, dot, latex, dvips, makeindex, gswin32, etc. -# must be in path. +# set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}) +# include(UseDoxygen) +# Add the Doxyfile.in and UseDoxygen.cmake files to the projects source directory. # -# Note about Visual Studio Projects: -# MSVS has its own path environment which may differ from the shell. -# See "Menu Tools/Options/Projects/VC++ Directories" in VS 7.1 # -# author Jan Woetzel 2004-2006 -# www.mip.informatik.uni-kiel.de/~jw +# Variables you may define are: +# DOXYFILE_OUTPUT_DIR - Path where the Doxygen output is stored. Defaults to "doc". +# +# DOXYFILE_LATEX_DIR - Directory where the Doxygen LaTeX output is stored. Defaults to "latex". +# +# DOXYFILE_HTML_DIR - Directory where the Doxygen html output is stored. Defaults to "html". +# + +# +# Copyright (c) 2009-2010 Tobias Rautenkranz +# Copyright (c) 2010 Andreas Schneider +# +# Redistribution and use is allowed according to the terms of the New +# BSD license. +# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# + +macro(usedoxygen_set_default name value) + if(NOT DEFINED "${name}") + set("${name}" "${value}") + endif() +endmacro() + +find_package(Doxygen) +if(DOXYGEN_FOUND) + find_file(DOXYFILE_IN "doxy.config.in" + PATHS "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_ROOT}/Modules/" + NO_DEFAULT_PATH) + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args(DOXYFILE_IN DEFAULT_MSG "DOXYFILE_IN") +endif() -FIND_PACKAGE(Doxygen) +if(DOXYGEN_FOUND AND DOXYFILE_IN_FOUND) + add_custom_target(doxygen ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxy.config) -IF (DOXYGEN_FOUND) + usedoxygen_set_default(DOXYFILE_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc") + usedoxygen_set_default(DOXYFILE_HTML_DIR "html") - # click+jump in Emacs and Visual Studio (for doxy.config) (jw) - IF (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)") - SET(DOXY_WARN_FORMAT "\"$file($line) : $text \"") - ELSE (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)") - SET(DOXY_WARN_FORMAT "\"$file:$line: $text \"") - ENDIF (CMAKE_BUILD_TOOL MATCHES "(msdev|devenv)") + set_property(DIRECTORY APPEND PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES "${DOXYFILE_OUTPUT_DIR}/${DOXYFILE_HTML_DIR}") - #Build the documentation for libssh developpers if asked - IF (WITH_INTERNAL_DOC) - SET(CMAKE_INTERNAL_DOC "Yes") - ELSE (WITH_INTERNAL_DOC) - SET(CMAKE_INTERNAL_DOC "No") - ENDIF (WITH_INTERNAL_DOC) + set(DOXYFILE_LATEX FALSE) + set(DOXYFILE_PDFLATEX FALSE) + set(DOXYFILE_DOT FALSE) - # we need latex for doxygen because of the formulas - FIND_PACKAGE(LATEX) - IF (NOT LATEX_COMPILER) - MESSAGE(STATUS "latex command LATEX_COMPILER not found but usually required. You will probably get warnings and user inetraction on doxy run.") - ENDIF (NOT LATEX_COMPILER) - IF (NOT MAKEINDEX_COMPILER) - MESSAGE(STATUS "makeindex command MAKEINDEX_COMPILER not found but usually required.") - ENDIF (NOT MAKEINDEX_COMPILER) - IF (NOT DVIPS_CONVERTER) - MESSAGE(STATUS "dvips command DVIPS_CONVERTER not found but usually required.") - ENDIF (NOT DVIPS_CONVERTER) - FIND_PROGRAM(DOXYGEN_DOT_EXECUTABLE_PATH NAMES dot) - IF (DOXYGEN_DOT_EXECUTABLE_PATH) - SET(DOXYGEN_DOT_FOUND "YES") - ENDIF (DOXYGEN_DOT_EXECUTABLE_PATH) + find_package(LATEX) + if(LATEX_COMPILER AND MAKEINDEX_COMPILER) + set(DOXYFILE_LATEX TRUE) + usedoxygen_set_default(DOXYFILE_LATEX_DIR "latex") - IF (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config.in") - MESSAGE(STATUS "Generate ${CMAKE_CURRENT_BINARY_DIR}/doxy.config from doxy.config.in") - CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/doxy.config.in - ${CMAKE_CURRENT_BINARY_DIR}/doxy.config - @ONLY ) - # use (configured) doxy.config from (out of place) BUILD tree: - SET(DOXY_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/doxy.config") - ELSE (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config.in") - # use static hand-edited doxy.config from SOURCE tree: - SET(DOXY_CONFIG "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config") - IF (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config") - MESSAGE(STATUS "WARNING: using existing ${CMAKE_CURRENT_SOURCE_DIR}/doxy.config instead of configuring from doxy.config.in file.") - ELSE (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config") - IF (EXISTS "${CMAKE_MODULE_PATH}/doxy.config.in") - # using template doxy.config.in - MESSAGE(STATUS "Generate ${CMAKE_CURRENT_BINARY_DIR}/doxy.config from doxy.config.in") - CONFIGURE_FILE(${CMAKE_MODULE_PATH}/doxy.config.in - ${CMAKE_CURRENT_BINARY_DIR}/doxy.config - @ONLY ) - SET(DOXY_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/doxy.config") - ELSE (EXISTS "${CMAKE_MODULE_PATH}/doxy.config.in") - # failed completely... - MESSAGE(SEND_ERROR "Please create ${CMAKE_CURRENT_SOURCE_DIR}/doxy.config.in (or doxy.config as fallback)") - ENDIF(EXISTS "${CMAKE_MODULE_PATH}/doxy.config.in") + set_property(DIRECTORY APPEND PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES + "${DOXYFILE_OUTPUT_DIR}/${DOXYFILE_LATEX_DIR}") - ENDIF(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config") - ENDIF(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/doxy.config.in") + if(PDFLATEX_COMPILER) + set(DOXYFILE_PDFLATEX TRUE) + endif() + if(DOXYGEN_DOT_EXECUTABLE) + set(DOXYFILE_DOT TRUE) + endif() - ADD_CUSTOM_TARGET(doc ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxy.config) + add_custom_command(TARGET doxygen + POST_BUILD + COMMAND ${CMAKE_MAKE_PROGRAM} + WORKING_DIRECTORY "${DOXYFILE_OUTPUT_DIR}/${DOXYFILE_LATEX_DIR}") + endif() - # create a windows help .chm file using hhc.exe - # HTMLHelp DLL must be in path! - # fallback: use hhw.exe interactively - IF (WIN32) - FIND_PACKAGE(HTMLHelp) - IF (HTML_HELP_COMPILER) - SET (TMP "${CMAKE_CURRENT_BINARY_DIR}\\doc\\html\\index.hhp") - STRING(REGEX REPLACE "[/]" "\\\\" HHP_FILE ${TMP} ) - # MESSAGE(SEND_ERROR "DBG HHP_FILE=${HHP_FILE}") - ADD_CUSTOM_TARGET(winhelp ${HTML_HELP_COMPILER} ${HHP_FILE}) - ADD_DEPENDENCIES (winhelp doc) - - IF (NOT TARGET_DOC_SKIP_INSTALL) - # install windows help? - # determine useful name for output file - # should be project and version unique to allow installing - # multiple projects into one global directory - IF (EXISTS "${PROJECT_BINARY_DIR}/doc/html/index.chm") - IF (PROJECT_NAME) - SET(OUT "${PROJECT_NAME}") - ELSE (PROJECT_NAME) - SET(OUT "Documentation") # default - ENDIF(PROJECT_NAME) - IF (${PROJECT_NAME}_VERSION_MAJOR) - SET(OUT "${OUT}-${${PROJECT_NAME}_VERSION_MAJOR}") - IF (${PROJECT_NAME}_VERSION_MINOR) - SET(OUT "${OUT}.${${PROJECT_NAME}_VERSION_MINOR}") - IF (${PROJECT_NAME}_VERSION_PATCH) - SET(OUT "${OUT}.${${PROJECT_NAME}_VERSION_PATCH}") - ENDIF(${PROJECT_NAME}_VERSION_PATCH) - ENDIF(${PROJECT_NAME}_VERSION_MINOR) - ENDIF(${PROJECT_NAME}_VERSION_MAJOR) - # keep suffix - SET(OUT "${OUT}.chm") - - #MESSAGE("DBG ${PROJECT_BINARY_DIR}/doc/html/index.chm \n${OUT}") - # create target used by install and package commands - INSTALL(FILES "${PROJECT_BINARY_DIR}/doc/html/index.chm" - DESTINATION "doc" - RENAME "${OUT}" - ) - ENDIF(EXISTS "${PROJECT_BINARY_DIR}/doc/html/index.chm") - ENDIF(NOT TARGET_DOC_SKIP_INSTALL) + configure_file(${DOXYFILE_IN} doxy.config ESCAPE_QUOTES IMMEDIATE @ONLY) + if (EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/doxy.trac.in) + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxy.trac.in doxy.trac ESCAPE_QUOTES IMMEDIATE @ONLY) + add_custom_target(doxygen-trac ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxy.trac) + add_dependencies(doxygen doxygen-trac) + endif() - ENDIF(HTML_HELP_COMPILER) - # MESSAGE(SEND_ERROR "HTML_HELP_COMPILER=${HTML_HELP_COMPILER}") - ENDIF (WIN32) -ENDIF(DOXYGEN_FOUND) + get_target_property(DOC_TARGET doc TYPE) + if(NOT DOC_TARGET) + add_custom_target(doc) + endif() + add_dependencies(doc doxygen) +endif() -- cgit v1.2.3