VTK  9.1.0
Functions
Module Internal CMake APIs

Functions

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

Detailed Description

Internal API

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>)
function _vtk_module_debug(domain, format)
Conditionally output debug statements.
Definition: vtkModule.cmake:57

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.

function _vtk_module_split_module_name(name, prefix)
Split a module name into a namespace and target component.

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>)
function _vtk_module_real_target(var, module)
The real target for a 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 1168 of file vtkModule.cmake.

◆ _vtk_module_real_target_kit()

function _vtk_module_real_target_kit ( var  ,
kit   
)

The real target for a 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 1236 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>...)
function _vtk_module_set_module_property(module)
Set a module property.

Definition at line 1818 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>)
function _vtk_module_get_module_property(module)
Get a module property.

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 1887 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>...])
function _vtk_module_check_destinations(prefix)
Check that destinations are valid.

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 1953 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>)
function _vtk_module_write_import_prefix(file, destination)
Write an import prefix statement.

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 1980 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>...])
function _vtk_module_export_properties()
Export properties on modules and targets.

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 2048 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>])
function _vtk_module_apply_properties(target)
Apply properties to a module.
boost::graph_traits< vtkGraph * >::vertex_descriptor target(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)

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

function _vtk_module_install(target)
Install a module target.

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

Definition at line 4094 of file vtkModule.cmake.