Skip to content
Snippets Groups Projects
Commit 06f656c0 authored by Dominic Kempf's avatar Dominic Kempf
Browse files

Initial implementation of the sphinx-based CMake API documentation

This includes the following workflow:

* The cmake module path is globbed for any modules matching *.cmake
* The opening comment is parsed for the following rst directives:
  cmake_function, cmake_module, cmake_variables
* From those, a browsable documentation is generated.

To run properly, a python interpreter and sphinx are needed.
parent 9ce8c207
No related branches found
No related tags found
No related merge requests found
Showing
with 605 additions and 194 deletions
......@@ -5,6 +5,7 @@
*.o
*.trs
*~
*.pyc
.deps/
.libs/
Makefile
......
# add_dune_gmp_flags(target1 target2 ...)
# Function that adds GMP flags to the specified targets
# Defines the functions to use GMP
#
# .. cmake_function:: add_dune_gmp_flags
#
# .. cmake_param:: targets
# :positional:
# :single:
# :required:
#
# A list of targets to use GMP with.
#
function(add_dune_gmp_flags _targets)
if(GMP_FOUND)
foreach(_target ${_targets})
......
# Module providing convenience functions for using METIS
# Defines the functions to use METIS
#
# Provides the following functions:
# .. cmake_function:: add_dune_metis_flags
#
# add_dune_metis_flags(target1 target2 ...)
# .. cmake_param:: targets
# :positional:
# :single:
# :required:
#
# Adds the necessary flags to compile and link the targets with ParMETIS support.
# A list of targets to use METIS with.
#
function(add_dune_metis_flags _targets)
if(METIS_FOUND)
foreach(_target ${_targets})
......
# Module providing convenience functions for using PT-Scotch
# Defines the functions to use PTScotch
#
# Provides the following functions:
# .. cmake_function:: add_dune_ptscotch_flags
#
# add_dune_ptscotch_flags(target1 target2 ...)
# .. cmake_param:: targets
# :positional:
# :single:
# :required:
#
# Adds the necessary flags to compile and link the targets with PT-Scotch support.
# A list of targets to use PTScotch with.
#
function(add_dune_ptscotch_flags _targets)
if(PTSCOTCH_FOUND)
foreach(_target ${_targets})
......
# Module providing convenience functions for using ParMETIS
# Defines the functions to use ParMETIS
#
# Provides the following functions:
# .. cmake_function:: add_dune_parmetis_flags
#
# add_dune_parmetis_flags(target1 target2 ...)
# .. cmake_param:: targets
# :positional:
# :single:
# :required:
#
# Adds the necessary flags to compile and link the targets with ParMETIS support.
# A list of targets to use ParMETIS with.
#
function(add_dune_parmetis_flags _targets)
if(PARMETIS_FOUND)
foreach(_target ${_targets})
......
# module providing convenience mehtods for compiling bianries with UMFPack support
# Defines the functions to use UMFPack
#
# Provides the following functions:
# .. cmake_function:: add_dune_umfpack_flags
#
# add_dune_umfpack_flags(target1 target2...)
# .. cmake_param:: targets
# :positional:
# :single:
# :required:
#
# adds UMFPack flags to the targets for compilation and linking
# A list of targets to use UMFPack with.
#
function(add_dune_umfpack_flags _targets)
if(UMFPACK_FOUND)
foreach(_target ${_targets})
......@@ -15,4 +21,4 @@ function(add_dune_umfpack_flags _targets)
"${_props} ${UMFPACK_DUNE_COMPILE_FLAGS} -DENABLE_UMFPACK")
endforeach(_target ${_targets})
endif(UMFPACK_FOUND)
endfunction(add_dune_umfpack_flags)
\ No newline at end of file
endfunction(add_dune_umfpack_flags)
......@@ -15,6 +15,7 @@ set(modules
DuneMacros.cmake
DuneMPI.cmake
DunePkgConfig.cmake
DuneSphinxCMakeDoc.cmake
DuneStreams.cmake
DuneSymlinkOrCopy.cmake
DuneTestMacros.cmake
......@@ -26,6 +27,7 @@ set(modules
FindMProtect.cmake
FindParMETIS.cmake
FindPTScotch.cmake
FindSphinx.cmake
FindThreadsCMake31.cmake
FindUMFPack.cmake
Headercheck.cmake
......
# .. cmake_module::
#
# Module that checks for supported C++14, C++11 and non-standard features.
# Module that checks for supported C++14, C++11 and non-standard features.
#
# Sets the follwing variables:
# The behaviour of this module can be modified by the following variable:
#
# HAVE_NULLPTR True if nullptr is available
# HAS_ATTRIBUTE_UNUSED True if attribute unused is supported
# HAS_ATTRIBUTE_DEPRECATED True if attribute deprecated is supported
# HAS_ATTRIBUTE_DEPRECATED_MSG True if attribute deprecated("msg") is supported
# HAVE_CONSTEXPR True if constexpr is supported
# HAVE_KEYWORD_FINAL True if final is supported.
# HAVE_RANGE_BASED_FOR True if range-based for is supported and working.
# HAVE_NOEXCEPT_SPECIFIER True if nonexcept specifier is supported.
# :ref:`DISABLE_CXX_VERSION_CHECK`
# Disable checking for std=c++11 (c++14, c++1y)
#
# Input variables:
# This module internally sets the following variables, which are then
# exported into the config.h of the current dune module.
#
# DISABLE_CXX_VERSION_CHECK Disable checking for std=c++11 (c++14, c++1y)
# :code:`HAVE_NULLPTR`
# True if nullptr is available
#
# :code:`HAS_ATTRIBUTE_UNUSED`
# True if attribute unused is supported
#
# :code:`HAS_ATTRIBUTE_DEPRECATED`
# True if attribute deprecated is supported
#
# :code:`HAS_ATTRIBUTE_DEPRECATED_MSG`
# True if attribute deprecated("msg") is supported
#
# :code:`HAVE_CONSTEXPR1`
# True if constexpr is supported
#
# :code:`HAVE_KEYWORD_FINAL`
# True if final is supported.
#
# :code:`HAVE_RANGE_BASED_FOR`
# True if range-based for is supported and working.
#
# :code:`HAVE_NOEXCEPT_SPECIFIER`
# True if nonexcept specifier is supported.
#
# .. cmake_variable:: DISABLE_CXX_VERSION_CHECK
#
# You may set this variable to TRUE to disable checking for
# std=c++11 (c++14, c++1y). For more details, check :ref:`CheckCXXFeatures`.
#
include(CMakePushCheckState)
cmake_push_check_state()
......
# .. cmake_module::
#
# .. note::
# This module should be removed soon, as it provides fallbacks for pre 2.8.8
#
# A poor mans version of CMakePackageConfigHelpers.cmake for as a substitute
# for old Cmake versions.
......
# This cmake file holds tests and directives that are executed
# for the module dune-common and have to be executed by
# all dependent modules
# .. cmake_module::
#
# Specifically it configure the DUNE debug streams and
# tests whether LAPACK and BLAS are available.
# This modules content is executed whenever a module required or suggests dune-common!
#
include(DuneStreams)
dune_set_minimal_debug_level()
......
# Module that checks whether the compiler supports the
# This Module checks whether the compiler supports the
# abi::__cxa_demangle function required to
# make the type names returned by typeid() human-readable
#
# Sets the following variable:
# HAVE_CXA_DEMANGLE
# It sets the a variable :code:`HAVE_CXA_DEMANGLE` with the result.
#
# perform tests
include(CheckCXXSourceCompiles)
CHECK_CXX_SOURCE_COMPILES("#include <typeinfo>
......
......@@ -15,7 +15,30 @@
# If DEPENDENCY is specified, this is a dependency for
# the installation. Otherwise FILENAME becomes the dependency
#
# dune_add_latex_document()
# .. cmake_function:: dune_add_latex_document
#
# .. cmake_brief::
#
# build a pdf document through the dune buildsystem.
#
# .. cmake_param:: texfile
# :single:
# :required:
# :positional:
#
# The texfile to compile into a pdf.
#
# .. note::
#
# This function will be rewritten for Dune 3.0 as it currently
# shadows all options provided by the base implementation
# :code:`add_latex_document`.
#
# .. cmake_function:: create_doc_install
#
# .. todo::
#
# Evaluate use cases for this function.
FIND_PACKAGE(LATEX)
FIND_PROGRAM(IMAGEMAGICK_CONVERT convert
......@@ -47,6 +70,9 @@ endif(LATEX_USABLE)
add_custom_target(doc)
# add the Sphinx-generated build system documentation
include(DuneSphinxCMakeDoc)
MACRO(create_doc_install filename targetdir)
dune_common_script_dir(SCRIPT_DIR)
......
# Module for building documentation using doxygen.
#
# provides the following macros:
# .. cmake_function:: add_doxygen_target
#
# add_doxgen_target
# .. cmake_param:: TARGET
# :single:
#
# This macro creates a target for building (doxygen_${ProjectName}) and installing
# (doxygen_install_${ProjectName}) the generated doxygen documentation.
# The documentation is built during the top-level make doc call. We have added a dependency
# that makes sure it is built before running make install.
# The suffix to add to the target name, default to the module name.
#
# .. cmake_param:: DEPENDS
# :multi:
#
# A list of further dependencies of the doxygen documentation.
# Might include :code:`mainpage.txt`.
#
# .. cmake_param:: OUTPUT
# :single:
#
# Name of the output target, necessary if you don't generate html.
#
# This macro creates a target for building (:code:`doxygen_${ProjectName}`) and installing
# (:code:`doxygen_install_${ProjectName}`) the generated doxygen documentation.
# The documentation is built during the top-level :code:`make doc` call. We have added a dependency
# that makes sure it is built before running :code:`make install`.
#
FIND_PACKAGE(Doxygen)
include (CMakeParseArguments)
......@@ -37,19 +51,6 @@ MACRO (prepare_doxyfile)
add_custom_target(Doxyfile DEPENDS Doxyfile.in Doxyfile)
ENDMACRO (prepare_doxyfile)
#
# add_doxgen_target
#
# This macro creates a target for building (doxygen_${ProjectName}) and installing
# (doxygen_install_${ProjectName}) the generated doxygen documentation.
# The documentation is built during the top-level make doc call. We have added a dependency
# that make sure it is built before running make install.
#
# the macro takes the following optional parameters:
# TARGET [name] : overwrite the target appendix, default is the module name
# DEPENDS [list] : add a list of further dependencies for doxygen.
# This list might include mainpage.txt
# OUTPUT [name] : change the name of the output target; necessary if you don't generate html.
MACRO (add_doxygen_target)
set(options )
set(oneValueArgs TARGET OUTPUT)
......
# This module provides the functions necessary for a simplified CMake build system
#
# The DUNE build system relies on the user to choose and add the compile and link flags
# necessary to build an executable. While this offers full control to the user, it
# is an error-prone procedure.
#
# Alternatively, users may use the functions in this module to simply add the compile flags for all
# found external modules to all executables in a DUNE module. Likewise, all found libraries are
# linked to all targets.
#
# This module provides the following functions:
#
# dune_enable_all_packages(INCLUDE_DIRS [include_dirs]
# COMPILE_DEFINITIONS [compile_definitions]
# COMPILE_OPTIONS [compile_options]
# MODULE_LIBRARIES [libraries]
# [VERBOSE] [APPEND]
# )
#
# Adds all flags and all libraries to all executables that are subsequently added in the directory
# from where this function is called and from all its subdirectories (recursively).
# If used, this function MUST be called in the top level CMakeLists.txt BEFORE adding any subdirectories!
# You can optionally add additional include dirs and compile definitions that will also be applied to
# all targets in the module.
# Finally, if your module contains libraries as well as programs and if the programs should automatically
# link to those libraries, you MUST list these libraries in MODULE_LIBRARIES. Those libraries will be
# automatically created by dune_enable_all_packages (which internally calls dune_add_library()) and placed
# in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
# be listed after its dependency. This special handling of the libraries is due to the way newer CMake
# versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
# anywhere in the source tree by calling dune_library_add_sources().
#
# Warning: dune_enable_all_packages() requires CMake 2.8.12+. If you call this function with an older version
# of CMake, the build will fail with a fatal error. DO NOT enable this feature if your module needs
# to compile on machines with an older version of CMake.
# Warning: The library feature requires CMake 3.1+. If you use the feature with older versions, CMake
# will emit a fatal error. Moreover, it will issue a warning if the cmake_minimum_required()
# Implementation of a simplified CMake build system.
#
# .. cmake_function:: dune_enable_all_packages
#
# .. cmake_brief::
#
# Previously, the DUNE build system relied on the user to choose and add the compile and link flags
# necessary to build an executable. While this offers full control to the user, it
# is an error-prone procedure.
#
# Alternatively, users may use this function to simply add the compile flags for all
# found external modules to all executables in a DUNE module. Likewise, all found libraries are
# linked to all targets.
#
# .. cmake_param:: INCLUDE_DIRS
# :multi:
#
# A list of include directories, that should be added to all targets.
# In a standard Dune module, it is not necessary to specify anything.
#
# .. cmake_param:: COMPILE_DEFINITIONS
# :multi:
#
# A list of compile definitions, that should be added to all targets.
# In a standard Dune module, it is not necessary to specify anything.
#
# .. cmake_param:: COMPILE_OPTIONS
# :multi:
#
# A list of non-definition compile options, that should be added to all targets.
# In a standard Dune module, it is not necessary to specify anything.
#
# .. cmake_param:: MODULE_LIBRARIES
# :multi:
#
# If your module contains libraries as well as programs and if the programs should automatically
# link to those libraries, you *MUST* list these libraries in :code:`MODULE_LIBRARIES`. Those libraries will be
# automatically created by :ref:`dune_enable_all_packages` (which internally calls :ref:`dune_add_library()`) and placed
# in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
# be listed after its dependency. This special handling of the libraries is due to the way newer CMake
# versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
# anywhere in the source tree by calling :ref:`dune_library_add_sources()`.
#
# .. warning::
# The library feature requires CMake 3.1+. If you use the feature with older versions, CMake
# will emit a fatal error. Moreover, it will issue a warning if the :code:`cmake_minimum_required`
# version is older than 3.1.
# Note: If you want to use dune_enable_all_packages() with an older version of CMake and your DUNE mdule
# creates its own library, you have to manually create the library in the top-level CMakeLists.txt
# file using dune_add_library() (with all sources listed within that call), use
# dune_target_enable_all_packages() to add all packages to the library and finally list that library
# under LIBRARIES in the call to dune_register_package_flags(). See dune-pdelab for an example of
# how to do this correctly.
#
# For a description of the APPEND option, see the documentation of dune_register_package_flags().
# With the VERBOSE option set, the list of flags is printed during configure.
# .. cmake_param:: VERBOSE
# :option:
#
# If this option is set, the set of compile flags, linked libraries and include directories
# that is in use for all targets in the module is printed upon configuration.
#
# .. cmake_param:: APPEND
# :option:
#
# If this option is set, the definitions, flags and directories specified in this function are
# appended to the global collection of flags instead of being prepended. Only use it, if you know
# what you are doing.
#
# Adds all flags and all libraries to all executables that are subsequently added in the directory
# from where this function is called and from all its subdirectories (recursively).
# If used, this function *MUST* be called in the top level CMakeLists.txt BEFORE adding any subdirectories!
# You can optionally add additional include dirs and compile definitions that will also be applied to
# all targets in the module.
#
# .. warning::
# :ref:`dune_enable_all_packages` requires CMake 2.8.12+. If you call this function with an older version
# of CMake, the build will fail with a fatal error. DO NOT enable this feature if your module needs
# to compile on machines with an older version of CMake.
#
# .. note::
# If you want to use :code:`dune_enable_all_packages` with an older version of CMake and your DUNE module
# creates its own library, you have to manually create the library in the top-level CMakeLists.txt
# file using :ref:`dune_add_library` (with all sources listed within that call), use
# :ref:`dune_target_enable_all_packages` to add all packages to the library and finally list that library
# under :code:`LIBRARIES` in the call to :ref:`dune_register_package_flags`. See dune-pdelab for an example of
# how to do this correctly.
#
# While :ref:`dune_enable_all_packages` defines the user interface for this feature, developers might
# also be interested in the following related functions:
#
# * :ref:`dune_target_enable_all_packages`
# * :ref:`dune_register_package_flags`
# * :ref:`dune_library_add_sources`
#
# .. cmake_function:: dune_target_enable_all_packages
#
# .. cmake_param:: TARGETS
# :multi:
#
# A list of targets to add all flags etc. too.
#
# Adds all currently registered package flags (see :ref:`dune_register_package_flags`) to the given targets.
# This function is mainly intended to help write DUNE modules that want to use :ref:`dune_enable_all_packages` and
# define their own libraries, but need to be compatible with CMake < 3.1
#
# .. note::
# Just like :ref:`dune_enable_all_packages`, this function requires CMake 2.8.12+.
#
# .. cmake_function:: dune_register_package_flags
#
# .. cmake_param:: INCLUDE_DIRS
# :multi:
#
# The list of include directories needed by the external package.
#
# .. cmake_param:: COMPILE_DEFINITIONS
# :multi:
#
# The list of compile definitions needed by the external package.
#
# .. cmake_param:: COMPILE_OPTIONS
# :multi:
#
# The list of compile options needed by the external package.
#
# .. cmake_param:: LIBRARIES
# :multi:
#
# The list of libraries that the external package should link to.
# The order of the input is preserved in the output.
#
# dune_target_enable_all_packages(TARGETS [target] ...)
# .. cmake_param:: APPEND
# :option:
#
# Adds all currently registered package flags (see dune_register_package_flags()) to the given targets.
# This function is mainly intended to help write DUNE modules that want to use dune_enable_all_packages() and
# define their own libraries, but need to be compatible with CMake < 3.1.
# If this option is set, the definitions, flags and directories specified in this function are
# appended to the global collection of flags instead of being prepended. Only use it, if you know
# what you are doing.
#
# Note: Just like dune_enable_all_packages(), this function requires CMake 2.8.12+.
# To correctly implement the automatic handling of external libraries, the compile flags, include paths and link
# flags of all found packages must be registered with this function. This function is only necessary for people that
# want to write their own :code:`FindFooBar` CMake modules to link against additional libraries which are not supported by
# the DUNE core modules. Call this function at the end of every find module. If you are using an external FindFoo
# module which you cannot alter, call it after the call to :code:`find_package(foo)`.
#
# .. cmake_function:: dune_library_add_sources
#
# dune_register_package_flags(COMPILE_DEFINITIONS [flags]
# COMPILE_OPTIONS [options]
# INCLUDE_DIRS {includes]
# LIBRARIES [libs]
# [APPEND]
# )
# .. cmake_param:: module_library
# :single:
# :positional:
#
# To correctly implement the automatic handling of external libraries, the compile flags, include paths and link
# flags of all found packages must be registered with this function. This function is only necessary for people that
# want to write their own FindFooBar CMake modules to link against additional libraries which are not supported by
# the DUNE core modules. Call this function at the end of every find module. If you are using an external FindFoo
# module which you cannot alter, call it after the call to find_package(foo).
# The APPEND parameter appends the given flags to the global list instead of prepending. Only use it, if you know
# what you are doing.
# The name of the module library target.
#
# .. cmake_param: SOURCES
# :multi:
# :required:
#
# dune_library_add_sources(module_library
# SOURCES [sources]
# )
# The source files to add to the DUNE module library :code:`module_library`.
# That library must have been created by an earlier call to :ref:`dune_enable_all_packages`
# in the current DUNE module.
#
# Adds the source files listed in [sources] to the DUNE module library module_library created by an earlier
# call to dune_enable_all_packages() in the current DUNE module.
# Register sources for module exported library.
#
function(dune_register_package_flags)
......
......@@ -10,13 +10,17 @@
# compiler with MPI flags usually used for C. CXX bindings
# are deactivated to prevent ABI problems.
#
# The following function is defined:
# .. cmake_function:: add_dune_mpi_flags
#
# add_dune_mpi_flags(targets)
# .. cmake_param:: targets
# :single:
# :required:
# :positional:
#
# Adds the above flags and libraries to the specified targets.
# The target list to add the MPI flags to.
#
find_package(MPI)
find_package(Threads)
......
# Core DUNE module for CMake.
#
# Provides the following macros:
# Documentation of the public API defined in this module:
#
# .. cmake_function:: dune_project
#
# Initialize a Dune module. This function needs to be run from every
# top-level CMakeLists.txt file. It sets up the module, defines basic
# variables and manages depedencies. Don't forget to call
# :ref:`finalize_dune_project` afterwards.
#
# .. cmake_function:: finalize_dune_project
#
# Finalize a Dune module. This function needs to be run at the end of
# every top-level CMakeLists.txt file.
#
# .. cmake_function:: dune_add_library
#
# .. cmake_brief::
#
# Add a library to a Dune module!
#
# .. cmake_param:: basename
# :single:
# :required:
# :positional:
#
# The basename for the library. On Unix this created :code:`lib<basename>.so`
# and :code:`lib<basename>.a`
#
# .. cmake_param:: NO_EXPORT
# :option:
#
# If omitted the library is exported for usage in other modules.
#
# .. cmake_param:: ADD_LIBS
# :multi:
#
# A list of libraries that should be incorporated into this library.
#
# .. cmake_param:: OBJECT
# :option:
#
# .. note::
# This feature will very likely vanish in Dune 3.0
#
# .. cmake_param:: SOURCES
# :multi:
# :required:
#
# The source files from which to build the library.
#
# .. cmake_param:: COMPILE_FLAGS
# :multi:
#
# Any additional compile flags fpr building the library.
#
# .. cmake_function:: dune_target_link_libraries
#
# .. cmake_param:: BASENAME
#
# .. cmake_param:: LIBRARIES
#
# Link libraries to the static and shared version of
# library BASENAME
#
#
# Documentation of internal macros in this module:
#
# dune_module_to_uppercase(upper_name module_name)
#
......@@ -13,15 +78,6 @@
# Parse ${MODULE_DIR}/dune.module and provide that information.
# If the second argument is QUIET no status message is printed.
#
#
# dune_project()
#
# macro that should be called near the begin of the top level CMakeLists.txt.
# Namely it sets up the module, defines basic variables and manages
# depedencies.
# Don't forget to call finalize_dune_project afterwards.
#
#
# dune_create_dependency_tree()
#
# Creates the dependency tree of the module.
......@@ -35,7 +91,6 @@
# _macro_name: variable where the name will be stored.
# _dune_module: the name of the dune module.
#
#
# dune_regenerate_config_cmake()
#
# Creates a new config_collected.h.cmake file in ${CMAKE_CURRENT_BINARY_DIR) that
......@@ -44,37 +99,6 @@
# of all dependent modules.
# Finally config.h is created from config_collected.h.cmake.
#
#
# dune_add_library(<basename> [NO_EXPORT] [ADD_LIBS <lib1> [<lib2> ...]]
# [OBJECT] SOURCES <source1> [<source2> ...] [COMPILE_FLAGS <flags>])
#
# Creates shared and static libraries with the same basename.
# <basename> is the basename of the library.
# On Unix this creates lib<basename>.so and lib<BASENAME>.a.
# Libraries that should be incorporate into this library can
# be specified with the ADD_LIBS option.
# The libraries will be built in ${PROJECT_BINARY_DIR}/lib.
# If the option NO_EXPORT is omitted the library is exported
# for usage in other modules.
#
# Object libraries can now be created with dune_add_library(<target>
# OBJECT <sources>). It will create a GLOBAL property
# _DUNE_TARGET_OBJECTS:<target>_ that records the full path to the
# source files. Theses can later be referenced by providing
# _DUNE_TARGET_OBJECTS:<target>_ as one of the sources to dune_add_library
#
# finalize_dune_project()
#
# macro that should be called at the end of the top level CMakeLists.txt.
# Namely it creates config.h and the cmake-config files,
# some install directives and exports the module.
#
#
# dune_target_link_libraries(BASENAME, LIBRARIES)
#
# Link libraries to the static and shared version of
# library BASENAME
#
# Make CMake use rpath on OS X
if(POLICY CMP0042)
......
# Module to generate CMake API documentation with Sphinx
#
# .. cmake_function:: dune_cmake_sphinx_doc
#
# .. cmake_brief::
#
# Generate the documentation that you are just browsing!!!
#
# .. cmake_param:: PATHS
# :multi:
#
# The set of paths to look for CMake modules. Defaults
# to the cmake/modules subdirectory of the current module.
# Note, that all modules must be rst-documented following
# the criteria defined in :ref:`DuneSphinxCMakeDoc` in order
# to successfully generate documentation.
#
# .. cmake_param:: BUILDTYPE
# :multi:
#
# Set the type of build that is requested. By default, "html" is chosen.
# The list of available build types:
#
# * `html`
#
# .. cmake_param:: EXCLUDE
# :multi:
#
# Exclude the given macros from the documentation.
#
# .. cmake_param:: NO_DEFAULT_PATHS
# :option:
#
# If set, the cmake/modules subdirectory will not be searched
# for CMake macros to generate documentation.
#
# Generate a documentation for the CMake API. A set of cmake
# modules defined by the parameters and all functions and macros
# there in are automatically generated. The top level directory
# of the documentation is the current build directory (aka the
# directory that this function is called from)
#
# There are some assumptions on how the documentation in
# the CMake modules is written:
#
# * At the beginning of each CMake module there is a comment block that is written in restructured text.
# The first two characters of each line (the comment character
# and a blank) are ignored. Any resulting content of lines most form valid rst.
# * TODO document more
#
find_package(Sphinx)
find_package(PythonInterp)
function(dune_cmake_sphinx_doc)
# Only proceed if Sphinx was found on the system
if(NOT SPHINX_FOUND)
message("-- Skipping building CMake API documentation (Sphinx was not found!)")
return()
endif()
# Only proceed if the python interpreter was found by cmake
if(NOT PYTHONINTERP_FOUND)
message("-- Skipping building CMake API documentation (Python interpreter was not found!)")
return()
endif()
# Parse Arguments
set(OPTION NO_DEFAULT_PATHS)
set(SINGLE)
set(MULTI PATHS EXCLUDE BUILDTYPE)
include(CMakeParseArguments)
cmake_parse_arguments(SPHINX_CMAKE "${OPTION}" "${SINGLE}" "${MULTI}" ${ARGN})
if(SPHINX_CMAKE_UNPARSED_ARGUMENTS)
message(WARNING "Unparsed arguments in dune_cmake_sphinx_doc: This often indicates typos!")
endif()
# Apply defaults
if(NOT SPHINX_CMAKE_BUILDTYPE)
set(SPHINX_CMAKE_BUILDTYPE html)
endif()
# Add default paths to the path variable
if(NOT SPHINX_CMAKE_NO_DEFAULT_PATHS)
set(SPHINX_CMAKE_PATHS ${SPHINX_CMAKE_PATHS} ${CMAKE_SOURCE_DIR}/cmake/modules)
endif()
# Write the conf.py, which sets up Sphinx into the build
set(DUNE_SPHINX_EXT_PATH)
dune_common_script_dir(DUNE_SPHINX_EXT_PATH)
configure_file(${DUNE_SPHINX_EXT_PATH}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
# Generate the list of modules by looking through the given paths
# for files matching *.cmake
set(SPHINX_DOC_MODULE_LIST)
foreach(path ${SPHINX_CMAKE_PATHS})
file(GLOB modules "${path}/*.cmake")
set(SPHINX_DOC_MODULE_LIST ${SPHINX_DOC_MODULE_LIST} ${modules})
endforeach()
# Initialize a variable that collects all dependencies of the documentation
set(DOC_DEPENDENCIES)
# Generate the rst files for all cmake modules
foreach(module ${SPHINX_DOC_MODULE_LIST})
get_filename_component(modname ${module} NAME)
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/modules/${modname}
COMMAND ${PYTHON_EXECUTABLE} ${DUNE_SPHINX_EXT_PATH}/extract_cmake_data.py
--module=${module}
--builddir=${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${module})
set(DOC_DEPENDENCIES ${DOC_DEPENDENCIES} ${CMAKE_CURRENT_BINARY_DIR}/modules/${modname})
endforeach()
# copy the rst files that are fixed to the build directory during configure
file(GLOB rstfiles "${CMAKE_CURRENT_SOURCE_DIR}/*.rst")
foreach(rst ${rstfiles})
get_filename_component(rstname ${rst} NAME)
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${rstname}
COMMAND ${CMAKE_COMMAND} -E copy ${rst} ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${rst})
set(DOC_DEPENDENCIES ${DOC_DEPENDENCIES} ${CMAKE_CURRENT_BINARY_DIR}/${rstname})
endforeach()
# Call Sphinx once for each requested build type
foreach(type ${SPHINX_CMAKE_BUILDTYPE})
# Call the sphinx executable
add_custom_target(sphinx_${type}
COMMAND ${SPHINX_EXECUTABLE}
-b ${type}
-w ${CMAKE_BINARY_DIR}/SphinxError.log
-c ${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_CURRENT_BINARY_DIR}/${type}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${DOC_DEPENDENCIES}
)
add_dependencies(doc sphinx_${type})
endforeach()
endfunction()
# Module configures the DUNE debug streams.
# A default debug level can be specified with
# MINIMAL_DEBUG_LEVEL
# This Module configures the DUNE debug streams.
#
# .. cmake_variable:: MINIMAL_DEBUG_LEVEL
#
# This variable configures the Dune debug streams.
# Standard debug streams with level below :code:`MINIMAL_DEBUG_LEVEL` will
# collapse to doing nothing if output is requested. Possible values are
# :code:`vverb`, :code:`verb`, :code:`info`, :code:`warn` and :code:`grave`.
# Deafults to :code:`warn`.
#
macro(dune_set_minimal_debug_level)
set(MINIMAL_DEBUG_LEVEL ON CACHE STRING "set the MINIMAL_DEBUG_LEVEL. Standard debug streams with level below MINIMAL_DEBUG_LEVEL will collapse to doing nothing if output is requested. (default=warn)")
set_property(CACHE MINIMAL_DEBUG_LEVEL PROPERTY STRINGS
......
......@@ -27,21 +27,82 @@
# in the source tree. This file will be copied
# to the build tree.
#
# dune_symlink_to_source_tree([NAME name])
#
# add a symlink called NAME to all directories in the build tree (defaults to src_dir).
# That symlink points to the corresponding directory in the source tree.
# Call the macro from the toplevel CMakeLists.txt file of your project.
# You can also call it from some other directory, creating only symlinks
# in that directory and all directories below. A warning is issued on
# Windows systems.
# .. cmake_function:: dune_add_copy_command
#
# dune_symlink_to_source_files(FILES files)
# .. cmake_param:: filename
# :positional:
# :single:
# :required:
#
# .. todo::
# DOC ME!
#
# .. cmake_function:: dune_add_copy_target
#
# .. cmake_param:: target_name
# :positional:
# :single:
# :required:
#
# .. cmake_param:: filename
# :positional:
# :single:
# :required:
#
# .. todo::
# DOC ME!
#
# .. cmake_function:: dune_add_copy_dependency
#
# .. cmake_param:: target
# :positional:
# :single:
# :required:
#
# .. cmake_param:: filename
# :positional:
# :single:
# :required:
#
# .. todo::
# DOC ME!
#
# .. cmake_function:: dune_symlink_to_source_tree
#
# .. cmake_param:: NAME
# :single:
#
# The name of the symlink, defaults to :code:`src_dir`.
#
# This function will place a symlink into every subdirectory
# of the build tree, that allows to jump to the corresponding
# source directory. Call this from your top-level :code:`CMakeLists.txt`
# to enable it for a given module. To enable it for all modules,
# set the variable :ref:`DUNE_SYMLINK_TO_SOURCE_TREE` instead.
# If used on Windows systems, a warning is issued.
#
# .. cmake_variable:: DUNE_SYMLINK_TO_SOURCE_TREE
#
# If this variable is set to TRUE, the functionality of
# :ref:`dune_symlink_to_source_tree` is enabled in all modules.
# This will place symlinks to the corresponding source directory
# in every subdirectory of the build directory.
#
# .. cmake_function:: dune_symlink_to_source_files
#
# .. cmake_param:: FILES
# :multi:
# :required:
#
# The list of files to symlink.
#
# Create symlinks in the current build directory, which
# point to files in the source directory. This is usually
# used for grid and ini files and the like. On Windows systems,
# a warning is issued and copying is used as a fallback to
# symlinking.
#
# add symlinks to the build tree, which point to files in the source tree.
# Foreach file given in "files", a symlink of that name is created in the
# corresponding build directory. Use for ini files, grid files etc. A warning
# is issued on Windows systems.
macro(dune_add_copy_command file_name)
add_custom_command(
......
# Module that checks for the GNU MP Bignum (GMP) library, include
# dirs and
# .. cmake_module::
#
# Variables used by this module which you may want to set:
# GMP_ROOT Path list to search for GMP
# Find the GNU MP Bignum (GMP) library
#
# Sets the following variables:
# GMP_FOUND True if the GMP library was found.
# You may set the following variables to modify the
# behaviour of this module:
#
# :ref:`GMP_ROOT`
# Path list to search for GMP
#
# Sets the following variables:
#
# :code:`GMP_FOUND`
# True if the GMP library was found.
#
# .. cmake_variable:: GMP_ROOT
#
# You may set this variable to have :ref:`FindGMP` look
# for the gmp package in the given path before inspecting
# system paths.
#
# search for location of header gmpxx.h", only at positions given by the user
find_path(GMP_INCLUDE_DIR
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment