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 1158 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 1689 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 1759 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 1826 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 1853 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 1921 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 3778 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 3853 of file vtkModule.cmake.