Commit 9b076afe authored by Marcus D. Hanwell's avatar Marcus D. Hanwell

DOC: Added documentation to CMake API functions

Improve the documentation of the CMake API, making it clearer what
the expected behavior is, and how the macros/functions should be
used. Also made some very minor whitespace changes in one or two
places for consistency with the rest of the file.

Change-Id: I0293dee3bede73dc0fd91149ae3dd6f62ebd995f
parent 94a046be
#-----------------------------------------------------------------------------
# Private helper macros.
# _vtk_module_config_recurse(<namespace> <module>)
#
# Internal macro to recursively load module information into the supplied
# namespace, this is called from vtk_module_config. It should be noted that
# _${ns}_${mod}_USED must be cleared if this macro is to work correctly on
# subsequent invocations. The macro will load the module files using the
# vtk_module_load, making all of its variables available in the local scope.
macro(_vtk_module_config_recurse ns mod)
if(NOT _${ns}_${mod}_USED)
set(_${ns}_${mod}_USED 1)
......@@ -26,7 +31,8 @@ endmacro()
# vtk_module_load(<module>)
#
# Loads variables describing the given module:
# Loads variables describing the given module, these include custom variables
# set by the module along with the standard ones listed below:
# <module>_LOADED = True if the module has been loaded
# <module>_DEPENDS = List of dependencies on other modules
# <module>_LIBRARIES = Libraries to link
......@@ -35,7 +41,7 @@ endmacro()
macro(vtk_module_load mod)
if(NOT ${mod}_LOADED)
include("${VTK_MODULES_DIR}/${mod}.cmake" OPTIONAL RESULT_VARIABLE _found)
if (NOT _found)
if(NOT _found)
# When building applications outside VTK, they can provide extra module
# config files by simply adding the corresponding locations to the
# CMAKE_MODULE_PATH
......@@ -60,9 +66,10 @@ endmacro()
# vtk_module_headers_load(<module>)
#
# Loads variables describing the given module:
# <module>_HEADERS_LOADED = True if the module header info has been loaded
# <module>_HEADERS = List of headers
# Loads variables describing the headers/API of the given module, this is not
# loaded by vtk_module_config, and is mainly useful for wrapping generation:
# <module>_HEADERS_LOADED = True if the module header info has been loaded
# <module>_HEADERS = List of headers
# <module>_HEADER_<header>_EXISTS
# <module>_HEADER_<header>_ABSTRACT
# <module>_HEADER_<header>_WRAP_EXCLUDE
......@@ -71,7 +78,7 @@ macro(vtk_module_headers_load mod)
if(NOT ${mod}_HEADERS_LOADED)
include("${VTK_MODULES_DIR}/${mod}-Headers.cmake"
OPTIONAL RESULT_VARIABLE _found)
if (NOT _found)
if(NOT _found)
# When building applications outside VTK, they can provide extra module
# config files by simply adding the corresponding locations to the
# CMAKE_MODULE_PATH
......@@ -90,6 +97,12 @@ endmacro()
# <namespace>_LIBRARIES = Libraries to link
# <namespace>_INCLUDE_DIRS = Header search path
# <namespace>_LIBRARY_DIRS = Library search path (for outside dependencies)
#
# Calling this macro also recursively calls vtk_module_load for all modules
# explicitly named, and their dependencies, making them available in the local
# scope. This means that module level information can be accessed once this
# macro has been called.
#
# Do not name a module as the namespace.
macro(vtk_module_config ns)
set(_${ns}_MISSING ${ARGN})
......@@ -152,7 +165,9 @@ macro(vtk_module_config ns)
unset(_${ns}_AUTOINIT)
endmacro()
# Call to add a single directory to the module search path
# vtk_add_to_module_search_path(<source> <build>)
#
# Call to add a single module to the module search path.
macro(vtk_add_to_module_search_path src bld)
list(APPEND vtk_module_search_path "${src},${bld}")
endmacro()
......@@ -12,6 +12,30 @@ if(UNIX AND VTK_BUILD_FORWARDING_EXECUTABLES)
include(vtkForwardingExecutable)
endif()
# vtk_module(<name>)
#
# Main function for declaring a VTK module, usually in a module.cmake file in
# the module search path. The module name is the only required argument, all
# others are optional named arguments that will be outlined below. The following
# named options take one (or more) arguments, such as the names of dependent
# modules:
# DEPENDS = Modules that will be publicly linked to this module
# PRIVATE_DEPENDS = Modules that will be privately linked to this module
# COMPILE_DEPENDS = Modules that are needed at compile time by this module
# TEST_DEPENDS = Modules that are needed by this modules testing executables
# DESCRIPTION = Free text description of the module
# TCL_NAME = Alternative name for the TCL wrapping (cannot contain numbers)
# IMPLEMENTS = Modules that this module implements, using the auto init feature
# GROUPS = Module groups this module should be included in
# TEST_LABELS = Add labels to the tests for the module
#
# The following options take no arguments:
# EXCLUDE_FROM_ALL = Exclude this module from the build all modules flag
# EXCLUDE_FROM_WRAPPING = Do not attempt to wrap this module in any language
# EXCLUDE_FROM_WRAP_HIERARCHY = Do not attempt to process with wrap hierarchy
#
# This macro will ensure the module name is compliant, and set the appropriate
# module variables as declared in the module.cmake file.
macro(vtk_module _name)
vtk_module_check_name(${_name})
set(vtk-module ${_name})
......@@ -93,12 +117,17 @@ macro(vtk_module _name)
endif()
endmacro()
# vtk_module_check_name(<name>)
#
# Check if the proposed module name is compliant.
macro(vtk_module_check_name _name)
if( NOT "${_name}" MATCHES "^[a-zA-Z][a-zA-Z0-9]*$")
if(NOT "${_name}" MATCHES "^[a-zA-Z][a-zA-Z0-9]*$")
message(FATAL_ERROR "Invalid module name: ${_name}")
endif()
endmacro()
# vtk_module_impl()
#
# This macro provides module implementation, setting up important variables
# necessary to build a module. It assumes we are in the directory of the module.
macro(vtk_module_impl)
......@@ -144,7 +173,11 @@ macro(vtk_module_impl)
endif()
endmacro()
# Export just the essential data from a module such as name, include directory.
# vtk_module_export_info()
#
# Export just the essential data from a module such as name, include directory,
# libraries provided by the module, and any custom variables that are part of
# the module configuration.
macro(vtk_module_export_info)
vtk_module_impl()
# First gather and configure the high level module information.
......@@ -207,8 +240,12 @@ macro(vtk_module_export_info)
endif()
endmacro()
# vtk_module_export(<sources>)
#
# Export data from a module such as name, include directory and header level
# information useful for wrapping.
# information useful for wrapping. This calls vtk_module_export_info() and then
# exports additional information in a supplemental file useful for wrapping
# generators.
function(vtk_module_export sources)
vtk_module_export_info()
# Now iterate through the headers in the module to get header level information.
......@@ -287,6 +324,8 @@ macro(vtk_target_label _target_name)
set_property(TARGET ${_target_name} PROPERTY LABELS ${_label})
endmacro()
# vtk_target_name(<name>)
#
# This macro does some basic checking for library naming, and also adds a suffix
# to the output name with the VTK version by default. Setting the variable
# VTK_CUSTOM_LIBRARY_SUFFIX will override the suffix.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment