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.

• _vtk_module_real_target
• _vtk_module_real_target_kit

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.

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

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

• kit_modules: Modules which are compiled into the kit.

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.

_vtk_module_split_module_name(<name> <prefix>)

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 1168 of file vtkModule.cmake.

_vtk_module_real_target_kit()

function _vtk_module_real_target_kit	(	var	,
		kit
	)

The real target for a kit.

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

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.

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

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.

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

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

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

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.

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

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.

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

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.

_vtk_module_install(<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.