vtkModule#

_vtk_module_debug#

Conditionally output debug statements module-internal

The _vtk_module_debug() function is provided to assist in debugging. It is controlled by the _vtk_module_log variable which contains a list of “domains” to debug.

_vtk_module_debug(<domain> <format>)

If the domain is enabled for debugging, the format argument is configured and printed. It should contain @ variable expansions to replace rather than it being done outside. This helps to avoid the cost of generating large strings when debugging is disabled.

vtk_module_find_kits#

Find vtk.kit files in a set of directories module

vtk_module_find_kits(<output> [<directory>...])

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

vtk_module_find_modules#

Find vtk.module files in a set of directories module

vtk_module_find_modules(<output> [<directory>...])

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.

_vtk_module_split_module_name#

Split a module name into a namespace and target component module-internal

Module names may include a namespace. This function splits the name into a namespace and target name part.

_vtk_module_split_module_name(<name> <prefix>)

The <prefix>_NAMESPACE and <prefix>_TARGET_NAME variables will be set in the calling scope.

_vtk_module_optional_dependency_exists#

Detect whether an optional dependency exists or not. module-internal

Optional dependencies need to be detected namespace and target name part.

_vtk_module_optional_dependency_exists(<dependency>
  SATISFIED_VAR <var>)

The result will be returned in the variable specified by SATISFIED_VAR.

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.
LICENSE_FILES
  Copyright.txt
SPDX_COPYRIGHT_TEXT
  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
SPDX_LICENSE_IDENTIFIER
  BSD-3-Clause
GROUPS
  StandAlone
DEPENDS
  VTK::kwiml
PRIVATE_DEPENDS
  VTK::vtksys
  VTK::utf8

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

  • NAME: (Required) The name of the module.

  • LIBRARY_NAME: The base name of the library file. It defaults to the module name, but any namespaces are removed. For example, a NS::Foo module will have a default LIBRARY_NAME of Foo.

  • DESCRIPTION: (Recommended) Short text describing what the module is for.

  • KIT: The name of the kit the module belongs to (see Kits files for more information).

  • IMPLEMENTABLE: If present, the module contains logic which supports the autoinit functionality.

  • GROUPS: Modules may belong to “groups” which is exposed as a build option. This allows for enabling a set of modules with a single build option.

  • CONDITION: Arguments to CMake’s if command which may be used to hide the module for certain platforms or other reasons. If the expression is false, the module is completely ignored.

  • DEPENDS: A list of modules which are required by this module and modules using this module.

  • PRIVATE_DEPENDS: A list of modules which are required by this module, but not by those using this module.

  • OPTIONAL_DEPENDS: A list of modules which are used by this module if enabled; these are treated as PRIVATE_DEPENDS if they exist.

  • ORDER_DEPENDS: Dependencies which only matter for ordering. This does not mean that the module will be enabled, just guaranteed to build before this module.

  • IMPLEMENTS: A list of modules for which this module needs to register with.

  • TEST_DEPENDS: Modules required by the test suite for this module.

  • TEST_OPTIONAL_DEPENDS: Modules used by the test suite for this module if available.

  • TEST_LABELS: Labels to apply to the tests of this module. By default, the module name is applied as a label.

  • EXCLUDE_WRAP: If present, this module should not be wrapped in any language.

  • INCLUDE_MARSHAL: If present, this module opts into automatic code generation of (de)serializers. This option requires that the module is not excluded from wrapping with EXCLUDE_WRAP.

  • THIRD_PARTY: If present, this module is a third party module.

  • LICENSE_FILES: A list of license files to install for the module.

  • SPDX_LICENSE_IDENTIFIER: A license identifier for SPDX file generation.

  • SPDX_DOWNLOAD_LOCATION: A download location for the SPDX file generation.

  • SPDX_COPYRIGHT_TEXT: A copyright text for the SPDX file generation.

  • SPDX_CUSTOM_LICENSE_FILE: A relative path to a single custom license file to include in generated SPDX file.

  • SPDX_CUSTOM_LICENSE_NAME: The name of the single custom license, without the LicenseRef-

_vtk_module_parse_module_args#

Parse vtk.module file contents

module-impl

This macro places all vtk.module keyword “arguments” into the caller’s scope prefixed with the value of name_output which is set to the NAME of the module.

_vtk_module_parse_module_args(name_output <vtk.module args...>)

For example, this vtk.module file:

NAME
  Namespace::Target
LIBRARY_NAME
  nsTarget

called with _vtk_module_parse_module_args(name ...) will set the following variables in the calling scope:

  • name: Namespace::Target

  • Namespace::Target_LIBRARY_NAME: nsTarget

With namespace support for module names, the variable should instead be referenced via ${${name}_LIBRARY_NAME} instead.

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:

  • NAME: (Required) The name of the kit.

  • LIBRARY_NAME: The base name of the library file. It defaults to the module name, but any namespaces are removed. For example, a NS::Foo module will have a default LIBRARY_NAME of Foo.

  • DESCRIPTION: (Recommended) Short text describing what the kit contains.

_vtk_module_parse_kit_args#

Parse vtk.kit file contents module-impl

Just like _vtk_module_parse_module_args(), but for kits.

Enable status values#

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

  • YES: The module or group must be built.

  • NO: The module or group must not be built.

  • WANT: The module or group should be built if possible.

  • DONT_WANT: The module or group should only be built if required (e.g., via a dependency).

  • DEFAULT: Acts as either WANT or DONT_WANT based on the group settings for the module or WANT_BY_DEFAULT option to vtk_module_scan() if no other preference is specified. This is usually handled via another setting in the main project.

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.

_vtk_module_verify_enable_value#

Verify enable values module-impl

Verifies that the variable named as the first parameter is a valid enable status value.

_vtk_module_verify_enable_value(var)
vtk_module_scan#

Scan modules and kits module

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

vtk_module_scan(
  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>])

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")
vtk_module_scan(
  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")
vtk_module_scan(
  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")
vtk_module_scan(
  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 ()

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.

Module target internals#

When manipulating modules as targets, there are a few functions provided for use in wrapping code to more easily access them.

_vtk_module_real_target_kit#

The real target for a kit module-internal

_vtk_module_real_target_kit(<var> <kit>)

Sometimes the actual, core target for a module is required (e.g., setting CMake-level target properties or install rules). This function returns the real target for a kit.

vtk_module_set_properties#

Set multiple properties on a module module

A wrapper around set_target_properties that works for modules.

vtk_module_set_properties(<module>
  [<property> <value>]...)
vtk_module_set_property#

Set a property on a module. module

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

vtk_module_set_property(<module>
  [APPEND] [APPEND_STRING]
  PROPERTY  <property>
  VALUE     <value>...)
vtk_module_get_property#

Get a property from a module module

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

vtk_module_get_property(<module>
  PROPERTY  <property>
  VARIABLE  <variable>)

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

_vtk_module_target_function#

Generate arguments for target function wrappers module-impl

Create the INTERFACE, PUBLIC, and PRIVATE arguments for a function wrapping CMake’s target_ functions to call the wrapped function.

This is necessary because not all of the functions support empty lists given a keyword.

vtk_module_depend#

Add dependencies to a module module

A wrapper around add_dependencies that works for modules.

vtk_module_depend(<module> <depend>...)
vtk_module_sources#

Add source files to a module. module

A wrapper around target_sources that works for modules.

vtk_module_sources(<module>
  [PUBLIC     <source>...]
  [PRIVATE    <source>...]
  [INTERFACE  <source>...])
vtk_module_include#

Add include directories to a module module

A wrapper around target_include_directories that works for modules.

vtk_module_include(<module>
  [SYSTEM]
  [PUBLIC     <directory>...]
  [PRIVATE    <directory>...]
  [INTERFACE  <directory>...])
vtk_module_definitions#

Add compile definitions to a module. module

A wrapper around target_compile_definitions that works for modules.

vtk_module_definitions(<module>
  [PUBLIC     <define>...]
  [PRIVATE    <define>...]
  [INTERFACE  <define>...])
vtk_module_compile_options#

Add compile options to a module. module

A wrapper around target_compile_options that works for modules.

vtk_module_compile_options(<module>
  [PUBLIC     <option>...]
  [PRIVATE    <option>...]
  [INTERFACE  <option>...])
vtk_module_compile_features#

Add compile features to a module. module

A wrapper around target_compile_features that works for modules.

vtk_module_compile_features(<module>
  [PUBLIC     <feature>...]
  [PRIVATE    <feature>...]
  [INTERFACE  <feature>...])

Manage the private link target for a module. module-impl

This function manages the private link target for a module.

_vtk_private_kit_link_target(<module>
  [CREATE_IF_NEEDED]
  [SETUP_TARGET_NAME <var>]
  [USAGE_TARGET_NAME <var>])

Add link libraries to a module. 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.

The NO_KIT_EXPORT_IF_SHARED argument may be passed to additionally prevent leaking PRIVATE link targets from kit builds. Intended to be used for targets coming from a vtk_module_find_package(PRIVATE_IF_SHARED) call. Applies to all PRIVATE arguments; if different treatment is needed for subsets of these arguments, use a separate call to vtk_module_link.

vtk_module_link(<module>
  [NO_KIT_EXPORT_IF_SHARED]
  [PUBLIC     <link item>...]
  [PRIVATE    <link item>...]
  [INTERFACE  <link item>...])

Add link options to a module. module

A wrapper around target_link_options that works for modules.

vtk_module_link_options(<module>
  [PUBLIC     <option>...]
  [PRIVATE    <option>...]
  [INTERFACE  <option>...])

Module properties#

module-internal

The VTK module system leverages CMake’s target propagation and storage. As such, there are a number of properties added to the targets representing modules. These properties are intended for use by the module system and associated functionality. In particular, more properties may be available by language wrappers.

Naming properties#

When creating properties for use with the module system, they should be prefixed with INTERFACE_vtk_module_. The INTERFACE_ portion is required in order to work with interface libraries. The vtk_module_ portion is to avoid colliding with any other properties. This function assumes this naming scheme for some of its convenience features as well.

Properties should be the same in the local build as well as when imported to ease use.

VTK module system properties#

There are a number of properties that are used and expected by the core of the module system. These are generally module metadata (module dependencies, whether to wrap or not, etc.). The properties all have the INTERFACE_vtk_module_ prefix mentioned in the previous section.

  • third_party: If set, the module represents a third party dependency and should be treated specially. Third party modules are very restricted and generally do not have any other properties set on them.

  • exclude_wrap: If set, the module should not be wrapped by an external language.

  • depends: The list of dependent modules. Language wrappers will generally require this to satisfy references to parent classes of the classes in the module.

  • private_depends: The list of privately dependent modules. Language wrappers may require this to satisfy references to parent classes of the classes in the module.

  • optional_depends: The list of optionally dependent modules. Language wrappers may require this to satisfy references to parent classes of the classes in the module.

  • kit: The kit the module is a member of. Only set if the module is actually a member of the kit (i.e., the module was built with BUILD_WITH_KITS ON).

  • implements: The list of modules for which this module registers to. This is used by the autoinit subsystem and generally is not required.

  • implementable: If set, this module provides registries which may be populated by dependent modules. It is used to check the implements property to help minimize unnecessary work from the autoinit subsystem.

  • needs_autoinit: If set, linking to this module requires the autoinit subsystem to ensure that registries in modules are fully populated.

  • headers: Paths to the public headers from the module. These are the headers which should be handled by language wrappers.

  • hierarchy: The path to the hierarchy file describing inheritance of the classes for use in language wrappers.

  • forward_link: Usage requirements that must be forwarded even though the

    module is linked to privately.

  • include_marshal: If set, the whole module opts into automatic code generation of (de)serializers. Note that only classes annotated with VTK_MARSHALAUTO are considered for code generation.

Kits have the following properties available (but only if kits are enabled):

  • kit_modules: Modules which are compiled into the kit.

_vtk_module_set_module_property#

Set a module property. module-internal

This function sets a module property on a module. The required prefix will automatically be added to the passed name.

_vtk_module_set_module_property(<module>
  [APPEND] [APPEND_STRING]
  PROPERTY  <property>
  VALUE     <value>...)
_vtk_module_get_module_property#

Get a module property. module-internal

Get a module property from a module.

_vtk_module_get_module_property(<module>
  PROPERTY  <property>
  VARIABLE  <variable>)

As with vtk_module_get_property(), the output variable will be unset if the property is not set. The property name is automatically prepended with the required prefix.

_vtk_module_check_destinations#

Check that destinations are valid. module-internal

All installation destinations are expected to be relative so that CMAKE_INSTALL_PREFIX can be relied upon in all code paths. This function may be used to verify that destinations are relative.

_vtk_module_check_destinations(<prefix> [<suffix>...])

For each suffix, prefix is prefixed to it and the resulting variable name is checked for validity as an install prefix. Raises an error if any is invalid.

_vtk_module_write_import_prefix#

Write an import prefix statement. module-internal

CMake files, once installed, may need to construct paths to other locations within the install prefix. This function writes a prefix computation for file given its install destination.

_vtk_module_write_import_prefix(<file> <destination>)

The passed file is cleared so that it occurs at the top of the file. The prefix is available in the file as the _vtk_module_import_prefix variable. It is recommended to unset the variable at the end of the file.

_vtk_module_export_properties#

Export properties on modules and targets. module-internal

This function is intended for use in support functions which leverage the module system, not by general system users. This function supports exporting properties from the build into dependencies via target properties which are loaded from a project’s config file which is loaded via CMake’s find_package function.

_vtk_module_export_properties(
  [MODULE       <module>]
  [KIT          <kit>]
  BUILD_FILE    <path>
  INSTALL_FILE  <path>
  [PROPERTIES               <property>...]
  [FROM_GLOBAL_PROPERTIES   <property fragment>...]
  [SPLIT_INSTALL_PROPERTIES <property fragment>...])

The BUILD_FILE and INSTALL_FILE arguments are required. Exactly one of MODULE and KIT is also required. The MODULE or KIT argument holds the name of the module or kit that will have properties exported. The BUILD_FILE and INSTALL_FILE paths are appended to. As such, when setting up these files, it should be preceded with:

file(WRITE "${build_file}")
file(WRITE "${install_file}")

To avoid accidental usage of the install file from the build tree, it is recommended to store it under a CMakeFiles/ directory in the build tree with an additional .install suffix and use install(RENAME) to rename it at install time.

The set of properties exported is computed as follows:

  • PROPERTIES queries the module target for the given property and exports its value as-is to both the build and install files. In addition, these properties are set on the target directly as the same name.

  • FROM_GLOBAL_PROPERTIES queries the global _vtk_module_<MODULE>_<fragment> property and exports it to both the build and install files as INTERFACE_vtk_module_<fragment>.

  • SPLIT_INSTALL_PROPERTIES queries the target for INTERFACE_vtk_module_<fragment> and exports its value to the build file and INTERFACE_vtk_module_<fragment>_install to the install file as the non-install property name. This is generally useful for properties which change between the build and installation.

vtk_module_build#

Build modules and kits. module

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.

vtk_module_build(
  MODULES       <module>...
  [KITS          <kit>...]

  [LIBRARY_NAME_SUFFIX  <suffix>]
  [VERSION              <version>]
  [SOVERSION            <soversion>]

  [PACKAGE              <package>]

  [BUILD_WITH_KITS  <ON|OFF>]

  [ENABLE_WRAPPING <ON|OFF>]
  [ENABLE_SERIALIZATION <ON|OFF>]

  [USE_EXTERNAL <ON|OFF>]

  [INSTALL_HEADERS             <ON|OFF>]
  [HEADERS_COMPONENT           <component>]
  [HEADERS_EXCLUDE_FROM_ALL    <ON|OFF>]
  [USE_FILE_SETS               <ON|OFF>]

  [TARGETS_COMPONENT  <component>]
  [INSTALL_EXPORT     <export>]

  [TARGET_SPECIFIC_COMPONENTS <ON|OFF>]

  [LICENSE_COMPONENT  <component>]

  [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>]

  [GENERATE_SPDX            <ON|OFF>]
  [SPDX_COMPONENT           <component>]
  [SPDX_DOCUMENT_NAMESPACE  <uri>]
  [SPDX_DOWNLOAD_LOCATION   <url>]

  [ARCHIVE_DESTINATION    <destination>]
  [HEADERS_DESTINATION    <destination>]
  [LIBRARY_DESTINATION    <destination>]
  [RUNTIME_DESTINATION    <destination>]
  [CMAKE_DESTINATION      <destination>]
  [LICENSE_DESTINATION    <destination>]
  [HIERARCHY_DESTINATION  <destination>])

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.

  • ENABLE_SERIALIZATION: (Defaults to OFF) If enabled, (de)serialization code will be autogenerated for classes with the correct wrapping hints.

  • 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).

  • HEADERS_EXCLUDE_FROM_ALL: (Defaults to OFF) Whether to install the headers component in ALL or not.

  • USE_FILE_SETS: (Defaults to OFF) Whether to use FILE_SET source specification or not.

  • TARGETS_COMPONENT: Defaults to ``runtime) 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>).

  • LICENSE_COMPONENT: (Defaults to licenses) The install component to use for licenses.

  • 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.

  • GENERATE_SPDX: (Defaults to OFF) Whether or not to generate and install SPDX file for each modules and third parties.

  • SPDX_COMPONENT: (Defaults to spdx) The install component to use for SPDX files.

  • SPDX_DOCUMENT_NAMESPACE: (Defaults to "") Document namespace to use when generating SPDX files.

  • SPDX_DOWNLOAD_LOCATION: (Defaults to "") Download location to use when generating SPDX files.

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.

  • SPDX_DESTINATION: (Defaults to ${CMAKE_INSTALL_DATAROOTDIR}/doc/${CMAKE_PROJECT_NAME}/spdx/) The install destination for SPDX files.

  • HIERARCHY_DESTINATION: (Defaults to <LIBRARY_DESTINATION>/vtk/hierarchy/<PACKAGE>) The install destination for hierarchy files (used for language wrapping).

_vtk_module_standard_includes#

Add “standard” include directories to a module. module-impl

Add the “standard” includes for a module to its interface. These are the source And build directories for the module itself. They are always either PUBLIC or INTERFACE (depending on the module’s target type).

_vtk_module_standard_includes(
  [SYSTEM]
  [INTERFACE]
  TARGET                <target>
  [HEADERS_DESTINATION  <destination>])
_vtk_module_default_library_name#

Determine the default export macro for a module. module-impl

Determines the export macro to be used for a module from its metadata. Assumes it is called from within a vtk_module_build call().

_vtk_module_default_library_name(<varname>)

Autoinit#

module

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:

  • In modules which IMPLEMENTS other modules, in the generated <module>Module.h header (which provides export symbols as well) will include the modules which are implemented.

  • In modules which are IMPLEMENTABLE or IMPLEMENTS another module, the generated <module>Module.h file will include the following block:

#ifdef <module>_AUTOINIT_INCLUDE
#include <module>_AUTOINIT_INCLUDE
#endif
#ifdef <module>_AUTOINIT
#include <header>
VTK_MODULE_AUTOINIT(<module>)
#endif

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.

vtk_module_autoinit#

Linking to autoinit-using modules. module

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.

vtk_module_autoinit(
  TARGETS <target>...
  MODULES <module>...)

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

_vtk_module_depfile_args#

Compute supported depfile tracking arguments. module-internal

Support for add_custom_command(DEPFILE) has changed over the CMake timeline. Generate the required arguments as supported for the current CMake version and generator.

_vtk_module_depfile_args(
  [MULTI_CONFIG_NEEDS_GENEX]
  TOOL_ARGS <variable>
  CUSTOM_COMMAND_ARGS <variable>
  DEPFILE_PATH <path>
  [SOURCE <path>]
  [SOURCE_LANGUAGE <lang>]
  [DEPFILE_NO_GENEX_PATH <path>]
  [TOOL_FLAGS <flag>...])

The arguments to pass to the tool are returned in the variable given to TOOL_ARGS while the arguments for add_custom_command itself are returned in the variable given to CUSTOM_COMMAND_ARGS. DEPFILE_PATH is the path to the depfile to use. If a generator expression can optionally be used, DEPFILE_NO_GENEX_PATH can be specified as a fallback in case of no generator expression support (unless MULTI_CONFIG_NEEDS_GENEX is specified and a multi-config generator is used). TOOL_FLAGS specifies the flags the tool needs to specify the depfile if used. If support is not available, the path given to SOURCE is used for IMPLICIT_DEPENDS using SOURCE_LANGUAGE (which defaults to CXX).

_vtk_module_write_wrap_hierarchy#

Generate the hierarchy for a module. module-impl

Write wrap hierarchy files for the module currently being built. This also installs the hierarchy file for use by dependent projects if INSTALL_HEADERS is set. This function honors the HEADERS_COMPONENT, and HEADERS_EXCLUDE_FROM_ALL arguments to vtk_module_build().

_vtk_module_write_wrap_hierarchy()
_vtk_module_add_file_set#

Add a file set to a target. module-internal

_vtk_module_add_file_set(<target>
  NAME <name>
  [VIS <visibility>]
  [TYPE <type>]
  [BASE_DIRS <base directory>...]
  FILES
    [members...])

Add a file set to the <target> named <name>.

  • NAME: The name of the file set.

  • VIS: The visibility of the file set. Defaults to PRIVATE. Must be a valid CMake visibility (PUBLIC, PRIVATE, or INTERFACE).

  • TYPE: The type of the file set. Defaults to HEADERS. File sets types that are recognized and known to not be supported by the CMake version in use will be added as PRIVATE sources not part of any file set.

  • BASE_DIRS: Base directories for the files. Defaults to ${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CURRENT_BINARY_DIR} if not specified.

  • FILES: The paths to add to the file set.

Note that prior to CMake 3.19, usage of FILE_SET with INTERFACE targets is severely restricted and instead this function will do nothing. Any PUBLIC files specified this way need installed using standard mechanisms.

vtk_module_add_module#

Create a module library. module

vtk_module_add_module(<name>
  [NO_INSTALL] [FORCE_STATIC|FORCE_SHARED]
  [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>...]
  [NOWRAP_TEMPLATE_CLASSES  <nowrap template class>...]
  [SOURCES                  <source>...]
  [HEADERS                  <header>...]
  [NOWRAP_HEADERS           <header>...]
  [TEMPLATES                <template>...]
  [PRIVATE_CLASSES          <class>...]
  [PRIVATE_TEMPLATE_CLASSES <template class>...]
  [PRIVATE_HEADERS          <header>...]
  [PRIVATE_TEMPLATES        <template>...]
  [SPDX_SKIP_REGEX          <regex>])

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).

  • NO_INSTALL: Skip installation of the module and all its installation artifacts. Note that if this target is used by any other target that is exported, this option may not be used because CMake (in addition to VTK module APIs such as vtk_module_export_find_packages and ‘ ‘) will generate references to the target that are expected to be satisfied. It is highly recommended to test that the build and install exports (as used) be tested to make sure that the module is not actually referenced.

  • FORCE_STATIC or FORCE_SHARED: For a static (respectively, shared) library to be created. If neither is 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_TEMPLATE_CLASSES: A list of template classes which will not be

  • available for wrapping but installed. This is a shortcut for adding <class>.txx to TEMPLATES 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.

  • SPDX_SKIP_REGEX: A python regex to skip a file based on its name

    when parsing for SPDX headers.

_vtk_module_add_header_tests#

Add header tests for a module. module-impl

Todo

Move this function out to be VTK-specific, probably into vtkModuleTesting.cmake. Each module would then need to manually call this function. It currently assumes it is in VTK itself.

_vtk_module_add_header_tests()
_vtk_module_apply_properties#

Apply properties to a module. module-internal

Apply build properties to a target. Generally only useful to wrapping code or other modules that cannot use vtk_module_add_module() for some reason.

_vtk_module_apply_properties(<target>
  [BASENAME <basename>])

If BASENAME is given, it will be used instead of the target name as the basis for OUTPUT_NAME. Full modules (as opposed to third party or other non-module libraries) always use the module’s LIBRARY_NAME setting.

The following target properties are set based on the arguments to the calling vtk_module_build call()

  • OUTPUT_NAME (based on the module’s LIBRARY_NAME and vtk_module_build(LIBRARY_NAME_SUFFIX))

  • VERSION (based on vtk_module_build(VERSION))

  • SOVERSION (based on vtk_module_build(SOVERSION))

  • DEBUG_POSTFIX (on Windows unless already set via CMAKE_DEBUG_POSTFIX)

_vtk_module_install#

Install a module target. module-internal

Install a target within the module context. Generally only useful to wrapping code, modules that cannot use vtk_module_add_module() for some reason, or modules which create utility targets that need installed.

_vtk_module_install(<target>)

This function uses the various installation options to vtk_module_build() function to keep the install uniform.

vtk_module_add_executable#

Create a module executable. module

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.

vtk_module_add_executable(<name>
  [NO_INSTALL]
  [DEVELOPMENT]
  [BASENAME <basename>]
  <source>...)

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.

vtk_module_find_package#

Find a package. module

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.

vtk_module_find_package(
  [PRIVATE] [PRIVATE_IF_SHARED] [CONFIG_MODE]
  PACKAGE               <package>
  [VERSION              <version>]
  [COMPONENTS           <component>...]
  [OPTIONAL_COMPONENTS  <component>...]
  [FORWARD_VERSION_REQ  <MAJOR|MINOR|PATCH|EXACT>]
  [VERSION_VAR          <variable>])

  • 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.

  • PRIVATE_IF_SHARED: The dependency should not be exported to the install if the module is built as a SHARED library.

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.

vtk_module_export_find_packages#

Export find_package calls for dependencies. module

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.

vtk_module_export_find_packages(
  CMAKE_DESTINATION <directory>
  FILE_NAME         <filename>
  [COMPONENT        <component>]
  MODULES           <module>...)

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.

Third party support#

module

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:

vtk_module_third_party#

Third party module.|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:

vtk_module_third_party(
  [INTERNAL <internal arguments>...]
  [EXTERNAL <external arguments>...])

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 :cmake:command`vtk_module_third_party_internal` functions for the arguments supported by the EXTERNAL and INTERNAL arguments, respectively.

_vtk_module_mark_third_party#

Mark a module as being third party. module-impl

Mark a module as being a third party module.

_vtk_module_mark_third_party(<target>)
vtk_module_third_party_external#

External third party package. module

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.

vtk_module_third_party_external(
  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])

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.

vtk_module_third_party_internal#

Internal third party package. module

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.

SPDX generation requires that SPDX_LICENSE_IDENTIFIER and SPDX_COPYRIGHT_TEXT are specified.

vtk_module_third_party_internal(
  [SUBDIRECTORY   <path>]
  [HEADERS_SUBDIR <subdir>]
  [LICENSE_FILES  <file>...]
  [VERSION        <version>]
  [HEADER_ONLY]
  [INTERFACE]
  [STANDARD_INCLUDE_DIRS])

All arguments are optional, however warnings are emitted if LICENSE_FILES, VERSION, SPDX_LICENSE_IDENTIFIER or SPDX_COPYRIGHT_TEXT are 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.

  • SPDX_LICENSE_IDENTIFIER: A license identifier for SPDX file generation

  • SPDX_DOWNLOAD_LOCATION: A download location for SPDX file generation

  • SPDX_COPYRIGHT_TEXT: A copyright text for SPDX file generation

  • SPDX_CUSTOM_LICENSE_FILE: A relative path to a single custom license file to include in generated SPDX file.

  • SPDX_CUSTOM_LICENSE_NAME: The name of the single custom license, without the LicenseRef-

  • 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.

_vtk_module_generate_spdx#

SPDX file generation at build time. module-internal

Modules can specify a copyright and a license identifier as well as other information to generate a SPDX file in order to provide a Software Bill Of Materials (SBOM). Inputs files can be parsed for SPDX copyrights and license identifier to add to the SPDX file as well.

_vtk_module_generate_spd(
  [MODULE_NAME <name>]
  [TARGET      <target>]
  [OUTPUT      <file>]
  [SKIP_REGEX  <regex>]
  [INPUT_FILES <file>...]

All arguments are required except for INPUT_FILES.

  • MODULE_NAME: The name of the module that will be used as package name in the SPDX file.

  • TARGET: A CMake target for the generation of the SPDX file at build time

  • OUTPUT: Path to the SPDX file to generate

  • SKIP_REGEX: A python regex to exclude certain source files from SPDX parsing

  • INPUT_FILES: A list of input files to parse for SPDX copyrights and license identifiers, some files are automatically excluded from parsing.