VTK  9.1.0
Functions
Module CMake APIs

Functions

function vtk_module_find_kits (output)
 Find vtk.kit files in a set of directories. More...
 
function vtk_module_find_modules (output)
 Find vtk.module files in a set of directories. More...
 
function vtk_module_scan ()
 Scan modules and kits. More...
 
function vtk_module_set_properties (module)
 Set multiple properties on a module. More...
 
function vtk_module_set_property (module)
 Set a property on a module. More...
 
function vtk_module_get_property (module)
 Get a property from a module. More...
 
function vtk_module_depend (module)
 Add dependencies to a module. More...
 
function vtk_module_include (module)
 Add include directories to a module. More...
 
function vtk_module_definitions (module)
 Add compile definitions to a module. More...
 
function vtk_module_compile_options (module)
 Add compile options to a module. More...
 
function vtk_module_compile_features (module)
 Add compile features to a module. More...
 
function vtk_module_link (module)
 Add link libraries to a module. More...
 
function vtk_module_link_options (module)
 Add link options to a module. More...
 
function vtk_module_build ()
 Build modules and kits. More...
 
function vtk_module_autoinit ()
 Linking to autoinit-using modules. More...
 
function vtk_module_add_module (name)
 Create a module library. More...
 
function vtk_module_install_headers ()
 Install headers. More...
 
function vtk_module_add_executable (name)
 Create a module executable. More...
 
macro vtk_module_find_package ()
 Find a package. More...
 
function vtk_module_export_find_packages ()
 Export find_package calls for dependencies. More...
 
function vtk_module_third_party ()
 Third party module. More...
 
function vtk_module_third_party_external ()
 External third party package. More...
 
function vtk_module_third_party_internal ()
 Internal third party package. More...
 

Detailed Description

Module API

A module is a set of related functionality. These are then compiled together into libraries at the "kit" level. Each module may be enabled or disabled individually and its dependencies will be built as needed.All functions strictly check their arguments. Any unrecognized or invalid values for a function cause errors to be raised.

Module overview

vtk.module file contents

The vtk.module file is parsed and used as arguments to a CMake function which stores information about the module for use when building it. Note that no variable expansion is allowed and it is not CMake code, so no control flow is allowed. Comments are supported and any content after a # on a line is treated as a comment. Due to the breakdown of the content, quotes are not meaningful within the files.

Example:

NAME
VTK::CommonCore
LIBRARY_NAME
vtkCommonCore
DESCRIPTION
The base VTK library.
GROUPS
StandAlone
DEPENDS
VTK::kwiml
PRIVATE_DEPENDS
VTK::vtksys
VTK::utf8

All values are optional unless otherwise noted. The following arguments are supported:

vtk.kit file contents

The vtk.kit file is parsed similarly to vtk.module files. Kits are intended to bring together related modules into a single library in order to reduce the number of objects that linkers need to deal with.

Example:

NAME
VTK::Common
LIBRARY_NAME
vtkCommon
DESCRIPTION
Core utilities for VTK.

All values are optional unless otherwise noted. The following arguments are supported:

Enable status values

Modules and groups are enable and disable preferences are specified using a 5-way flag setting:

If a YES module preference requires a module with a NO preference, an error is raised.

A module with a setting of DEFAULT will look for its first non-DEFAULT group setting and only if all of those are set to DEFAULT is the WANT_BY_DEFAULT setting used.

Module-as-target functions

Due to the nature of VTK modules supporting being built as kits, the module name might not be usable as a target to CMake's target_ family of commands. Instead, there are various wrappers around them which take the module name as an argument. These handle the forwarding of relevant information to the kit library as well where necessary.

Autoinit

When a module contains a factory which may be populated by other modules, these factories need to be populated when the modules are loaded by the dynamic linker (for shared builds) or program load time (for static builds). To provide for this, the module system contains an autoinit "subsystem".

Leveraging the autoinit subsystem

The subsystem provides the following hooks for use by projects:

#ifdef <module>_AUTOINIT_INCLUDE
#include <module>_AUTOINIT_INCLUDE
#endif
#ifdef <module>_AUTOINIT
#include <header>
#endif
#define VTK_MODULE_AUTOINIT
Definition: vtkAutoInit.h:21

The vtk_module_autoinit function will generate an include file and provide its path via the <module>_AUTOINIT_INCLUDE define. once it has been included, if the <module>_AUTOINIT symbol is defined, a header is included which is intended to provide the VTK_MODULE_AUTOINIT macro. This macro is given the module name and should use <module>_AUTOINIT to fill in the factories in the module with those from the IMPLEMENTS modules listed in that symbol.

The <module>_AUTOINIT symbol's value is:

<count>(<module1>,<module2>,<module3>)

where <count> is the number of modules in the parentheses and each module listed need to register something to <module>.

If not provided via the AUTOINIT_INCLUDE argument to the vtk_module_add_module function, the header to use is fetched from the _vtk_module_autoinit_include global property. This only needs to be managed in modules that IMPLEMENTS or are IMPLEMENTABLE. This should be provided by projects using the module system at its lowest level. Projects not implementing the VTK_MODULE_AUTOINIT macro should have its value provided by find_package dependencies in some way.

Third party support

The module system acknowledges that third party support is a pain and offers APIs to help wrangle them. Sometimes third party code needs a shim introduced to make it behave better, so an INTERFACE library to add that in is very useful. Other times, third party code is hard to ensure that it exists everywhere, so it is bundled. When that happens, the ability to select between the bundled copy and an external copy is useful. All three (and more) of these are possible.

The following functions are used to handle third party modules:

Function Documentation

◆ vtk_module_find_kits()

function vtk_module_find_kits ( output  )

Find vtk.kit files in a set of directories.

vtk_module_find_kits(<output> [<directory>...])
function vtk_module_find_kits(output)
Find vtk.kit files in a set of directories.
Definition: vtkModule.cmake:84

This scans the given directories recursively for vtk.kit files and put the paths into the output variable.

Definition at line 84 of file vtkModule.cmake.

◆ vtk_module_find_modules()

function vtk_module_find_modules ( output  )

Find vtk.module files in a set of directories.

vtk_module_find_modules(<output> [<directory>...])
function vtk_module_find_modules(output)
Find vtk.module files in a set of directories.

This scans the given directories recursively for vtk.module files and put the paths into the output variable. Note that module files are assumed to live next to the CMakeLists.txt file which will build the module.

Definition at line 107 of file vtkModule.cmake.

◆ vtk_module_scan()

function vtk_module_scan ( )

Scan modules and kits.

Once all of the modules and kits files have been found, they are "scanned" to determine what modules are enabled or required.

MODULE_FILES <file>...
[KIT_FILES <file>...]
PROVIDES_MODULES <variable>
[PROVIDES_KITS <variable>]
[REQUIRES_MODULES <variable>]
[REQUEST_MODULES <module>...]
[REJECT_MODULES <module>...]
[UNRECOGNIZED_MODULES <variable>]
[WANT_BY_DEFAULT <ON|OFF>]
[HIDE_MODULES_FROM_CACHE <ON|OFF>]
[ENABLE_TESTS <ON|OFF|WANT|DEFAULT>])
function vtk_module_scan()
Scan modules and kits.

The MODULE_FILES and PROVIDES_MODULES arguments are required. Modules which refer to kits must be scanned at the same time as their kits. This is so that modules may not add themselves to kits declared prior. The arguments are as follows:

  • MODULE_FILES: (Required) The list of module files to scan.
  • KIT_FILES: The list of kit files to scan.
  • PROVIDES_MODULES: (Required) This variable will contain the list of modules which are enabled due to this scan.
  • PROVIDES_KITS: (Required if KIT_FILES are provided) This variable will contain the list of kits which are enabled due to this scan.
  • REQUIRES_MODULES: This variable will contain the list of modules required by the enabled modules that were not scanned.
  • REQUEST_MODULES: The list of modules required by previous scans.
  • REJECT_MODULES: The list of modules to exclude from the scan. If any of these modules are required, an error will be raised.
  • UNRECOGNIZED_MODULES: This variable will contain the list of requested modules that were not scanned.
  • WANT_BY_DEFAULT: (Defaults to OFF) Whether modules should default to being built or not.
  • HIDE_MODULES_FROM_CACHE: (Defaults to OFF) Whether or not to hide the control variables from the cache or not. If enabled, modules will not be built unless they are required elsewhere.
  • ENABLE_TESTS: (Defaults to DEFAULT) Whether or not modules required by the tests for the scanned modules should be enabled or not.
    • ON: Modules listed as TEST_DEPENDS will be required.
    • OFF: Test modules will not be considered.
    • WANT: Test dependencies will enable modules if possible. Note that this has known issues where modules required only via testing may not have their dependencies enabled.
    • DEFAULT: Test modules will be enabled if their required dependencies are satisfied and skipped otherwise.

To make error messages clearer, modules passed to REQUIRES_MODULES and REJECT_MODULES may have a _vtk_module_reason_<MODULE> variable set to the reason for the module appearing in either argument. For example, if the Package::Frobnitz module is required due to a ENABLE_FROBNITZ cache variable:

set("_vtk_module_reason_Package::Frobnitz"
"via the `ENABLE_FROBNITZ` setting")

Additionally, the reason for the WANT_BY_DEFAULT value may be provided via the _vtk_module_reason_WANT_BY_DEFAULT variable.

Scanning multiple groups of modules

When scanning complicated projects, multiple scans may be required to get defaults set properly. The REQUIRES_MODULES, REQUEST_MODULES, and UNRECOGNIZED_MODULES arguments are meant to deal with this case. As an example, imagine a project with its source code, third party dependencies, as well as some utility modules which should only be built as necessary. Here, the project would perform three scans, one for each "grouping" of modules:

# Scan our modules first because we need to know what of the other groups we
# need.
vtk_module_find_modules(our_modules "${CMAKE_CURRENT_SOURCE_DIR}/src")
MODULE_FILES ${our_modules}
PROVIDES_MODULES our_enabled_modules
REQUIRES_MODULES required_modules)
# Scan the third party modules, requesting only those that are necessary, but
# allowing them to be toggled during the build.
vtk_module_find_modules(third_party_modules "${CMAKE_CURRENT_SOURCE_DIR}/third-party")
MODULE_FILES ${third_party_modules}
PROVIDES_MODULES third_party_enabled_modules
# These modules were requested by an earlier scan.
REQUEST_MODULES ${required_modules}
REQUIRES_MODULES required_modules
UNRECOGNIZED_MODULES unrecognized_modules)
# These modules are internal and should only be built if necessary. There is no
# need to support them being enabled independently, so hide them from the
# cache.
vtk_module_find_modules(utility_modules "${CMAKE_CURRENT_SOURCE_DIR}/utilities")
MODULE_FILES ${utility_modules}
PROVIDES_MODULES utility_enabled_modules
# These modules were either requested or unrecognized by an earlier scan.
REQUEST_MODULES ${required_modules}
${unrecognized_modules}
REQUIRES_MODULES required_modules
UNRECOGNIZED_MODULES unrecognized_modules
HIDE_MODULES_FROM_CACHE ON)
if (required_modules OR unrecognized_modules)
# Not all of the modules we required were found. This should probably error out.
endif ()
@ enabled
Definition: vtkX3D.h:265

Definition at line 541 of file vtkModule.cmake.

◆ vtk_module_set_properties()

function vtk_module_set_properties ( module  )

Set multiple properties on a module.

A wrapper around set_target_properties that works for modules.

[<property> <value>]...)
function vtk_module_set_properties(module)
Set multiple properties on a module.
@ value
Definition: vtkX3D.h:226

Definition at line 1278 of file vtkModule.cmake.

◆ vtk_module_set_property()

function vtk_module_set_property ( module  )

Set a property on a module.

A wrapper around set_property(TARGET) that works for modules.

[APPEND] [APPEND_STRING]
PROPERTY <property>
VALUE <value>...)
function vtk_module_set_property(module)
Set a property on a module.

Definition at line 1299 of file vtkModule.cmake.

◆ vtk_module_get_property()

function vtk_module_get_property ( module  )

Get a property from a module.

A wrapper around get_property(TARGET) that works for modules.

PROPERTY <property>
VARIABLE <variable>)
function vtk_module_get_property(module)
Get a property from a module.

The variable name passed to the VARIABLE argument will be unset if the property is not set (rather than the empty string).

Definition at line 1359 of file vtkModule.cmake.

◆ vtk_module_depend()

function vtk_module_depend ( module  )

Add dependencies to a module.

A wrapper around add_dependencies that works for modules.

vtk_module_depend(<module> <depend>...)
function vtk_module_depend(module)
Add dependencies to a module.

Definition at line 1432 of file vtkModule.cmake.

◆ vtk_module_include()

function vtk_module_include ( module  )

Add include directories to a module.

A wrapper around add_dependencies that works for modules.

[SYSTEM]
[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_include(module)
Add include directories to a module.

Definition at line 1453 of file vtkModule.cmake.

◆ vtk_module_definitions()

function vtk_module_definitions ( module  )

Add compile definitions to a module.

A wrapper around target_compile_definitions that works for modules.

[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_definitions(module)
Add compile definitions to a module.

Definition at line 1493 of file vtkModule.cmake.

◆ vtk_module_compile_options()

function vtk_module_compile_options ( module  )

Add compile options to a module.

A wrapper around target_compile_options that works for modules.

[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_compile_options(module)
Add compile options to a module.

Definition at line 1527 of file vtkModule.cmake.

◆ vtk_module_compile_features()

function vtk_module_compile_features ( module  )

Add compile features to a module.

A wrapper around target_compile_features that works for modules.

[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_compile_features(module)
Add compile features to a module.

Definition at line 1561 of file vtkModule.cmake.

◆ vtk_module_link()

function vtk_module_link ( module  )

Add link libraries to a module.

A wrapper around target_link_libraries that works for modules. Note that this function does extra work in kit builds, so circumventing it may break in kit builds.

[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_link(module)
Add link libraries to a module.

Definition at line 1668 of file vtkModule.cmake.

◆ vtk_module_link_options()

function vtk_module_link_options ( module  )

Add link options to a module.

A wrapper around target_link_options that works for modules.

[PUBLIC <directory>...]
[PRIVATE <directory>...]
[INTERFACE <directory>...])
function vtk_module_link_options(module)
Add link options to a module.

Definition at line 1717 of file vtkModule.cmake.

◆ vtk_module_build()

function vtk_module_build ( )

Build modules and kits.

Once all of the modules have been scanned, they need to be built. Generally, there will be just one build necessary for a set of scans, though they may be built distinctly as well. If there are multiple calls to this function, they should generally in reverse order of their scans.

MODULES <module>...
[KITS <kit>...]
[LIBRARY_NAME_SUFFIX <suffix>]
[VERSION <version>]
[SOVERSION <soversion>]
[PACKAGE <package>]
[BUILD_WITH_KITS <ON|OFF>]
[ENABLE_WRAPPING <ON|OFF>]
[USE_EXTERNAL <ON|OFF>]
[INSTALL_HEADERS <ON|OFF>]
[HEADERS_COMPONENT <component>]
[TARGETS_COMPONENT <component>]
[INSTALL_EXPORT <export>]
[TARGET_SPECIFIC_COMPONENTS <ON|OFF>]
[UTILITY_TARGET <target>]
[TEST_DIRECTORY_NAME <name>]
[TEST_DATA_TARGET <target>]
[TEST_INPUT_DATA_DIRECTORY <directory>]
[TEST_OUTPUT_DATA_DIRECTORY <directory>]
[TEST_OUTPUT_DIRECTORY <directory>]
[ARCHIVE_DESTINATION <destination>]
[HEADERS_DESTINATION <destination>]
[LIBRARY_DESTINATION <destination>]
[RUNTIME_DESTINATION <destination>]
[CMAKE_DESTINATION <destination>]
[LICENSE_DESTINATION <destination>]
[HIERARCHY_DESTINATION <destination>])
function vtk_module_build()
Build modules and kits.

The only requirement of the function is the list of modules to build, the rest have reasonable defaults if not specified.

  • MODULES: (Required) The list of modules to build.
  • KITS: (Required if BUILD_WITH_KITS is ON) The list of kits to build.
  • LIBRARY_NAME_SUFFIX: (Defaults to "") A suffix to add to library names. If it is not empty, it is prefixed with - to separate it from the kit name.
  • VERSION: If specified, the VERSION property on built libraries will be set to this value.
  • SOVERSION: If specified, the SOVERSION property on built libraries will be set to this value.
  • PACKAGE: (Defaults to ${CMAKE_PROJECT_NAME}) The name the build is meant to be found as when using find_package. Note that separate builds will require distinct PACKAGE values.
  • BUILD_WITH_KITS: (Defaults to OFF) If enabled, kit libraries will be built.
  • ENABLE_WRAPPING: (Default depends on the existence of VTK::WrapHierarchy or VTKCompileTools::WrapHierarchy targets) If enabled, wrapping will be available to the modules built in this call.
  • USE_EXTERNAL: (Defaults to OFF) Whether third party modules should find external copies rather than building their own copy.
  • INSTALL_HEADERS: (Defaults to ON) Whether or not to install public headers.
  • HEADERS_COMPONENT: (Defaults to development) The install component to use for header installation. Note that other SDK-related bits use the same component (e.g., CMake module files).
  • TARGETS_COMPONENT: Defaults toruntime`) The install component to use for the libraries built.
  • TARGET_SPECIFIC_COMPONENTS: (Defaults to OFF) If ON, place artifacts into target-specific install components (<TARGET>-<COMPONENT>).
  • UTILITY_TARGET: If specified, all libraries and executables made by the VTK Module API will privately link to this target. This may be used to provide things such as project-wide compilation flags or similar.
  • TARGET_NAMESPACE: Defaults to<AUTO>) The namespace for installed targets. All targets must have the same namespace. If set to<AUTO>`, the namespace will be detected automatically.
  • INSTALL_EXPORT: (Defaults to "") If non-empty, targets will be added to the given export. The export will also be installed as part of this build command.
  • TEST_DIRECTORY_NAME: (Defaults to Testing) The name of the testing directory to look for in each module. Set to NONE to disable automatic test management.
  • TEST_DATA_TARGET: (Defaults to <PACKAGE>-data) The target to add testing data download commands to.
  • TEST_INPUT_DATA_DIRECTORY: (Defaults to ${CMAKE_CURRENT_SOURCE_DIR}/Data) The directory which will contain data for use by tests.
  • TEST_OUTPUT_DATA_DIRECTORY: (Defaults to ${CMAKE_CURRENT_BINARY_DIR}/Data) The directory which will contain data for use by tests.
  • TEST_OUTPUT_DIRECTORY: (Defaults to ${CMAKE_BINARY_DIR}/<TEST_DIRECTORY_NAME>/Temporary) The directory which tests may write any output files to.

The remaining arguments control where to install files related to the build. See CMake documentation for the difference between ARCHIVE, LIBRARY, and RUNTIME.

  • ARCHIVE_DESTINATION: (Defaults to ${CMAKE_INSTALL_LIBDIR}) The install destination for archive files.
  • HEADERS_DESTINATION: (Defaults to ${CMAKE_INSTALL_INCLUDEDIR}) The install destination for header files.
  • LIBRARY_DESTINATION: (Defaults to ${CMAKE_INSTALL_LIBDIR}) The install destination for library files.
  • RUNTIME_DESTINATION: (Defaults to ${CMAKE_INSTALL_BINDIR}) The install destination for runtime files.
  • CMAKE_DESTINATION: (Defaults to <LIBRARY_DESTINATION>/cmake/<PACKAGE>) The install destination for CMake files.
  • LICENSE_DESTINATION: (Defaults to ${CMAKE_INSTALL_DATAROOTDIR}/licenses/${CMAKE_PROJECT_NAME}) The install destination for license files (relevant for third party packages).
  • HIERARCHY_DESTINATION: (Defaults to <LIBRARY_DESTINATION>/vtk/hierarchy/<PACKAGE>) The install destination for hierarchy files (used for language wrapping).

Definition at line 2289 of file vtkModule.cmake.

◆ vtk_module_autoinit()

function vtk_module_autoinit ( )

Linking to autoinit-using modules.

When linking to modules, in order for the autoinit system to work, modules need to declare their registration. In order to do this, defines may need to be provided to targets in order to trigger registration. These defines may be added to targets by using this function.

TARGETS <target>...
MODULES <module>...)
function vtk_module_autoinit()
Linking to autoinit-using modules.

After this call, the targets given to the TARGETS argument will gain the preprocessor definitions to trigger registrations properly.

Definition at line 2988 of file vtkModule.cmake.

◆ vtk_module_add_module()

function vtk_module_add_module ( name  )

Create a module library.

[FORCE_STATIC] [HEADER_ONLY] [HEADER_DIRECTORIES]
[EXPORT_MACRO_PREFIX <prefix>]
[HEADERS_SUBDIR <subdir>]
[LIBRARY_NAME_SUFFIX <suffix>]
[CLASSES <class>...]
[TEMPLATE_CLASSES <template class>...]
[NOWRAP_CLASSES <nowrap class>...]
[SOURCES <source>...]
[HEADERS <header>...]
[NOWRAP_HEADERS <header>...]
[TEMPLATES <template>...]
[PRIVATE_CLASSES <class>...]
[PRIVATE_TEMPLATE_CLASSES <template class>...]
[PRIVATE_HEADERS <header>...]
[PRIVATE_TEMPLATES <template>...])
function vtk_module_add_module(name)
Create a module library.
@ name
Definition: vtkX3D.h:225

The PRIVATE_ arguments are analogous to their non-PRIVATE_ arguments, but the associated files are not installed or available for wrapping (SOURCES are always private, so there is no PRIVATE_ variant for that argument).

  • FORCE_STATIC: For a static library to be created. If not provided, BUILD_SHARED_LIBS will control the library type.
  • HEADER_ONLY: The module only contains headers (or templates) and contains no compilation steps. Mutually exclusive with FORCE_STATIC.
  • HEADER_DIRECTORIES: The headers for this module are in a directory structure which should be preserved in the install tree.
  • EXPORT_MACRO_PREFIX: The prefix for the export macro definitions. Defaults to the library name of the module in all uppercase.
  • HEADERS_SUBDIR: The subdirectory to install headers into in the install tree.
  • LIBRARY_NAME_SUFFIX: The suffix to the module's library name if additional information is required.
  • CLASSES: A list of classes in the module. This is a shortcut for adding <class>.cxx to SOURCES and <class>.h to HEADERS.
  • TEMPLATE_CLASSES: A list of template classes in the module. This is a shortcut for adding <class>.txx to TEMPLATES and <class>.h to HEADERS.
  • SOURCES: A list of source files which require compilation.
  • HEADERS: A list of header files which will be available for wrapping and installed.
  • NOWRAP_CLASSES: A list of classes which will not be available for wrapping but installed. This is a shortcut for adding <class>.cxx to SOURCES and <class>.h to NOWRAP_HEADERS.
  • NOWRAP_HEADERS: A list of header files which will not be available for wrapping but installed.
  • TEMPLATES: A list of template files which will be installed.

Definition at line 3355 of file vtkModule.cmake.

◆ vtk_module_install_headers()

function vtk_module_install_headers ( )

Install headers.

Installing headers is done for normal modules by the vtk_module_add_module function already. However, sometimes header structures are more complicated and need to be installed manually. This is common for third party modules or projects which use more than a single directory of headers for a module.

To facilitate the installation of headers in various ways, the this function is available. This function honors the INSTALL_HEADERS, HEADERS_DESTINATION, and HEADERS_COMPONENT arguments to vtk_module_build.

[USE_RELATIVE_PATHS]
[DIRECTORIES <directory>...]
[FILES <file>...]
[SUBDIR <subdir>])
function vtk_module_install_headers()
Install headers.

Installation of header directories follows CMake's install function semantics with respect to trailing slashes.

If USE_RELATIVE_PATHS is given, the directory part of any listed files will be added to the destination. Absolute paths will be computed relative to ${CMAKE_CURRENT_BINARY_DIR}.

Definition at line 3921 of file vtkModule.cmake.

◆ vtk_module_add_executable()

function vtk_module_add_executable ( name  )

Create a module executable.

Some modules may have associated executables with them. By using this function, the target will be installed following the options given to the associated vtk_module_build command. Its name will also be changed according to the LIBRARY_NAME_SUFFIX option.

[NO_INSTALL]
[DEVELOPMENT]
[BASENAME <basename>]
<source>...)
function vtk_module_add_executable(name)
Create a module executable.
boost::graph_traits< vtkGraph * >::vertex_descriptor source(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)

If NO_INSTALL is specified, the executable will not be installed. If BASENAME is given, it will be used as the name of the executable rather than the target name.

If DEVELOPMENT is given, it marks the executable as a development tool and will not be installed if INSTALL_HEADERS is not set for the associated vtk_module_build command.

If the executable being built is the module, its module properties are used rather than BASENAME. In addition, the dependencies of the module will be linked.

Definition at line 4166 of file vtkModule.cmake.

◆ vtk_module_find_package()

macro vtk_module_find_package ( )

Find a package.

A wrapper around find_package that records information for use so that the same targets may be found when finding this package.

Modules may need to find external dependencies. CMake often provides modules to find these dependencies, but when imported targets are involved, these.need to also be found from dependencies of the current project. Since the benefits of imported targets greatly outweighs not using them, it is preferred to use them.

The module system provides the vtk_module_find_package function in order to extend find_package support to include finding the dependencies from an install of the project.

[PRIVATE] [CONFIG_MODE]
PACKAGE <package>
[VERSION <version>]
[COMPONENTS <component>...]
[OPTIONAL_COMPONENTS <component>...]
[FORWARD_VERSION_REQ <MAJOR|MINOR|PATCH|EXACT>]
[VERSION_VAR <variable>])
macro vtk_module_find_package()
Find a package.
  • PACKAGE: The name of the package to find.
  • VERSION: The minimum version of the package that is required.
  • COMPONENTS: Components of the package which are required.
  • OPTIONAL_COMPONENTS: Components of the package which may be missing.
  • FORWARD_VERSION_REQ: If provided, the found version will be promoted to the minimum version required matching the given version scheme.
  • VERSION_VAR: The variable to use as the provided version (defaults to <PACKAGE>_VERSION). It may contain @ in which case it will be configured. This is useful for modules which only provide components of the actual version number.
  • CONFIG_MODE: If present, pass CONFIG to the underlying find_package call.
  • PRIVATE: The dependency should not be exported to the install.

The PACKAGE argument is the only required argument. The rest are optional.

Note that PRIVATE is only applicable for private dependencies on interface targets (basically, header libraries) because some platforms require private shared libraries dependencies to be present when linking dependent libraries and executables as well. Such usages should additionally be used only via a $<BUILD_INTERFACE> generator expression to avoid putting the target name into the install tree at all.

Definition at line 4338 of file vtkModule.cmake.

◆ vtk_module_export_find_packages()

function vtk_module_export_find_packages ( )

Export find_package calls for dependencies.

When installing a project that is meant to be found via find_package from CMake, using imported targets in the build means that imported targets need to be created during the find_package as well. This function writes a file suitable for inclusion from a <package>-config.cmake file to satisfy dependencies. It assumes that the exported targets are named ${CMAKE_FIND_PACKAGE_NAME}::${component}. Dependent packages will only be found if a requested component requires the package to be found either directly or transitively.

CMAKE_DESTINATION <directory>
FILE_NAME <filename>
[COMPONENT <component>]
MODULES <module>...)
function vtk_module_export_find_packages()
Export find_package calls for dependencies.

The file will be named according to the FILE_NAME argument will be installed into CMAKE_DESTINATION in the build and install trees with the given filename. If not provided, the development component will be used.

The vtk_module_find_package calls made by the modules listed in MODULES will be exported to this file.

Definition at line 4527 of file vtkModule.cmake.

◆ vtk_module_third_party()

function vtk_module_third_party ( )

Third party module.

When a project has modules which represent third party packages, there are some convenience functions to help deal with them. First, there is the meta-wrapper:

[INTERNAL <internal arguments>...]
[EXTERNAL <external arguments>...])
function vtk_module_third_party()
Third party module.

This offers a cache variable named VTK_MODULE_USE_EXTERNAL_<module name> that may be set to trigger between the internal copy and an externally provided copy. This is available as a local variable named VTK_MODULE_USE_EXTERNAL_<library name>. See the vtk_module_third_party_external and vtk_module_third_party_internal functions for the arguments supported by the EXTERNAL and INTERNAL arguments, respectively.

Definition at line 4844 of file vtkModule.cmake.

◆ vtk_module_third_party_external()

function vtk_module_third_party_external ( )

External third party package.

A third party dependency may be expressed as a module using this function. Third party packages are found using CMake's find_package function. It is highly recommended that imported targets are used to make usage easier. The module itself will be created as an INTERFACE library which exposes the package.

PACKAGE <package>
[VERSION <version>]
[COMPONENTS <component>...]
[OPTIONAL_COMPONENTS <component>...]
[TARGETS <target>...]
[INCLUDE_DIRS <path-or-variable>...]
[LIBRARIES <target-or-variable>...]
[DEFINITIONS <variable>...]
[FORWARD_VERSION_REQ <MAJOR|MINOR|PATCH|EXACT>]
[VERSION_VAR <version-spec>]
[USE_VARIABLES <variable>...]
[CONFIG_MODE]
[STANDARD_INCLUDE_DIRS])
function vtk_module_third_party_external()
External third party package.

Only the PACKAGE argument is required. The arguments are as follows:

  • PACKAGE: (Required) The name of the package to find.
  • VERSION: If specified, the minimum version of the dependency that must be found.
  • COMPONENTS: The list of components to request from the package.
  • OPTIONAL_COMPONENTS: The list of optional components to request from the package.
  • TARGETS: The list of targets to search for when using this package. Targets which do not exist will be ignored to support different versions of a package using different target names.
  • STANDARD_INCLUDE_DIRS: If present, standard include directories will be added to the module target. This is usually only required if both internal and external are supported for a given dependency.
  • INCLUDE_DIRS: If specified, this is added as a SYSTEM INTERFACE include directory for the target. If a variable name is given, it will be dereferenced.
  • LIBRARIES: The libraries to link from the package. If a variable name is given, it will be dereferenced, however a warning that imported targets are not being used will be emitted.
  • DEFINITIONS: If specified, the given variables will be added to the target compile definitions interface.
  • CONFIG_MODE: Force CONFIG mode.
  • FORWARD_VERSION_REQ and VERSION_VAR: See documentation for vtk_module_find_package.
  • USE_VARIABLES: List of variables from the find_package to make available to the caller.

Definition at line 4955 of file vtkModule.cmake.

◆ vtk_module_third_party_internal()

function vtk_module_third_party_internal ( )

Internal third party package.

Third party modules may also be bundled with the project itself. In this case, it is an internal third party dependency. The dependency is assumed to be in a subdirectory that will be used via add_subdirectory. Unless it is marked as HEADERS_ONLY, it is assumed that it will create a target with the name of the module.

[SUBDIRECTORY <path>]
[HEADERS_SUBDIR <subdir>]
[LICENSE_FILES <file>...]
[VERSION <version>]
[HEADER_ONLY]
[INTERFACE]
[STANDARD_INCLUDE_DIRS])
function vtk_module_third_party_internal()
Internal third party package.

All arguments are optional, however warnings are emitted if LICENSE_FILES or VERSION is not specified. They are as follows:

  • SUBDIRECTORY: (Defaults to the library name of the module) The subdirectory containing the CMakeLists.txt for the dependency.
  • HEADERS_SUBDIR: If non-empty, the subdirectory to use for installing headers.
  • LICENSE_FILES: A list of license files to install for the dependency. If not given, a warning will be emitted.
  • VERSION: The version of the library that is included.
  • HEADER_ONLY: The dependency is header only and will not create a target.
  • INTERFACE: The dependency is an INTERFACE library.
  • STANDARD_INCLUDE_DIRS: If present, module-standard include directories will be added to the module target.

Definition at line 5207 of file vtkModule.cmake.