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... | |
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:
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.THIRD_PARTY: If present, this module is a third party module.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:
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.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.
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.
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".
The subsystem provides the following hooks for use by projects:
IMPLEMENTS other modules, in the generated <module>Module.h header (which provides export symbols as well) will include the modules which are implemented.IMPLEMENTABLE or IMPLEMENTS another module, the generated <module>Module.h file will include the following block: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:
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.
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 vtk_module_find_kits | ( | output | ) |
Find vtk.kit files in a set of directories.
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.
| 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.
| 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.
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 WANT) Whether or not modules required by the tests for the scanned modules should be enabled or not.
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:
Definition at line 525 of file vtkModule.cmake.
| function vtk_module_set_properties | ( | module | ) |
Set multiple properties on a module.
A wrapper around set_target_properties that works for modules.
Definition at line 1199 of file vtkModule.cmake.
| function vtk_module_set_property | ( | module | ) |
Set a property on a module.
A wrapper around set_property(TARGET) that works for modules.
Definition at line 1220 of file vtkModule.cmake.
| function vtk_module_get_property | ( | module | ) |
Get a property from a module.
A wrapper around get_property(TARGET) that works for modules.
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 1280 of file vtkModule.cmake.
| function vtk_module_depend | ( | module | ) |
Add dependencies to a module.
A wrapper around add_dependencies that works for modules.
Definition at line 1353 of file vtkModule.cmake.
| function vtk_module_include | ( | module | ) |
Add include directories to a module.
A wrapper around add_dependencies that works for modules.
Definition at line 1374 of file vtkModule.cmake.
| function vtk_module_definitions | ( | module | ) |
Add compile definitions to a module.
A wrapper around target_compile_definitions that works for modules.
Definition at line 1414 of file vtkModule.cmake.
| function vtk_module_compile_options | ( | module | ) |
Add compile options to a module.
A wrapper around target_compile_options that works for modules.
Definition at line 1448 of file vtkModule.cmake.
| function vtk_module_compile_features | ( | module | ) |
Add compile features to a module.
A wrapper around target_compile_features that works for modules.
Definition at line 1482 of file vtkModule.cmake.
| 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.
Definition at line 1589 of file vtkModule.cmake.
| function vtk_module_link_options | ( | module | ) |
Add link options to a module.
A wrapper around target_link_options that works for modules.
Definition at line 1638 of file vtkModule.cmake.
| 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.
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>).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 2205 of file vtkModule.cmake.
| 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.
After this call, the targets given to the TARGETS argument will gain the preprocessor definitions to trigger registrations properly.
Definition at line 2878 of file vtkModule.cmake.
Create a module library.
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.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_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 3239 of file vtkModule.cmake.
| 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.
Installation of header directories follows CMake's install function semantics with respect to trailing slashes.
Definition at line 3776 of file vtkModule.cmake.
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.
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 3994 of file vtkModule.cmake.
| 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.
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.
Definition at line 4163 of file vtkModule.cmake.
| 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.
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 4351 of file vtkModule.cmake.
| 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:
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 4631 of file vtkModule.cmake.
| 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.
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 4742 of file vtkModule.cmake.
| 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.
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 4994 of file vtkModule.cmake.
1.8.13 on Wed Jan 27 2021