VTK  9.0.1
Functions
Module Internal CMake APIs

Functions

function _vtk_module_debug (domain, format)
 Conditionally output debug statements. More...
 
function _vtk_module_split_module_name (name, prefix)
 Split a module name into a namespace and target component. More...
 
function _vtk_module_real_target (var, module)
 The real target for a module. More...
 
function _vtk_module_real_target_kit (var, kit)
 The real target for a kit. More...
 
function _vtk_module_set_module_property (module)
 Set a module property. More...
 
function _vtk_module_get_module_property (module)
 Get a module property. More...
 
function _vtk_module_check_destinations (prefix)
 Check that destinations are valid. More...
 
function _vtk_module_write_import_prefix (file, destination)
 Write an import prefix statement. More...
 
function _vtk_module_export_properties ()
 Export properties on modules and targets. More...
 
function _vtk_module_apply_properties (target)
 Apply properties to a module. More...
 
function _vtk_module_install (target)
 Install a module target. More...
 

Detailed Description

Internal API

The VTK module system provides some API functions for use by other code which consumes VTK modules (primarily language wrappers). This file documents these APIs. They may start with _vtk_module, but they are intended for use in cases of language wrappers or dealing with trickier third party packages.

Module target internals

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

Module properties

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.

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

Function Documentation

◆ _vtk_module_debug()

function _vtk_module_debug ( domain  ,
format   
)

Conditionally output debug statements.

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.

Definition at line 57 of file vtkModule.cmake.

◆ _vtk_module_split_module_name()

function _vtk_module_split_module_name ( name  ,
prefix   
)

Split a module name into a namespace and target component.

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

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

Definition at line 132 of file vtkModule.cmake.

◆ _vtk_module_real_target()

function _vtk_module_real_target ( var  ,
module   
)

The real target for a module.

_vtk_module_real_target(<var> <module>)

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

Definition at line 1093 of file vtkModule.cmake.

◆ _vtk_module_real_target_kit()

function _vtk_module_real_target_kit ( var  ,
kit   
)

The real target for a 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.

Definition at line 1162 of file vtkModule.cmake.

◆ _vtk_module_set_module_property()

function _vtk_module_set_module_property ( module  )

Set a module property.

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

[APPEND] [APPEND_STRING]
PROPERTY <property>
VALUE <value>...)

Definition at line 1693 of file vtkModule.cmake.

◆ _vtk_module_get_module_property()

function _vtk_module_get_module_property ( module  )

Get a module property.

Get a module property from a 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.

Definition at line 1763 of file vtkModule.cmake.

◆ _vtk_module_check_destinations()

function _vtk_module_check_destinations ( prefix  )

Check that destinations are valid.

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.

Definition at line 1830 of file vtkModule.cmake.

◆ _vtk_module_write_import_prefix()

function _vtk_module_write_import_prefix ( file  ,
destination   
)

Write an import prefix statement.

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.

Definition at line 1857 of file vtkModule.cmake.

◆ _vtk_module_export_properties()

function _vtk_module_export_properties ( )

Export properties on modules and targets.

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.

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

Definition at line 1925 of file vtkModule.cmake.

◆ _vtk_module_apply_properties()

function _vtk_module_apply_properties ( target  )

Apply properties to a module.

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.

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

Definition at line 3786 of file vtkModule.cmake.

◆ _vtk_module_install()

function _vtk_module_install ( target  )

Install a module target.

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.

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

Definition at line 3861 of file vtkModule.cmake.

_vtk_module_debug
function _vtk_module_debug(domain, format)
Conditionally output debug statements.
Definition: vtkModule.cmake:57
_vtk_module_export_properties
function _vtk_module_export_properties()
Export properties on modules and targets.
Definition: vtkModule.cmake:1925
_vtk_module_split_module_name
function _vtk_module_split_module_name(name, prefix)
Split a module name into a namespace and target component.
Definition: vtkModule.cmake:132
_vtk_module_real_target
function _vtk_module_real_target(var, module)
The real target for a module.
Definition: vtkModule.cmake:1093
target
boost::graph_traits< vtkGraph * >::vertex_descriptor target(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)
Definition: vtkBoostGraphAdapter.h:965
_vtk_module_set_module_property
function _vtk_module_set_module_property(module)
Set a module property.
Definition: vtkModule.cmake:1693
_vtk_module_install
function _vtk_module_install(target)
Install a module target.
Definition: vtkModule.cmake:3861
vtkX3D::name
@ name
Definition: vtkX3D.h:225
_vtk_module_write_import_prefix
function _vtk_module_write_import_prefix(file, destination)
Write an import prefix statement.
Definition: vtkModule.cmake:1857
_vtk_module_real_target_kit
function _vtk_module_real_target_kit(var, kit)
The real target for a kit.
Definition: vtkModule.cmake:1162
_vtk_module_get_module_property
function _vtk_module_get_module_property(module)
Get a module property.
Definition: vtkModule.cmake:1763
_vtk_module_apply_properties
function _vtk_module_apply_properties(target)
Apply properties to a module.
Definition: vtkModule.cmake:3786
_vtk_module_check_destinations
function _vtk_module_check_destinations(prefix)
Check that destinations are valid.
Definition: vtkModule.cmake:1830