VTK  9.2.20230205
Functions
Module Python CMake APIs

Functions

function vtk_module_python_default_destination (var)
 Determine Python module destination. More...
 
function vtk_module_wrap_python ()
 Wrap a set of modules for use in Python. More...
 
function vtk_module_add_python_package (name)
 Install Python packages with a module. More...
 
function vtk_module_add_python_module (name)
 Use a Python package as a module. More...
 

Detailed Description

Function Documentation

◆ vtk_module_python_default_destination()

function vtk_module_python_default_destination ( var  )

Determine Python module destination.

Some projects may need to know where Python expects its modules to be placed in the install tree (assuming a shared prefix). This function computes the default and sets the passed variable to the value in the calling scope.

[MAJOR_VERSION <major>])
function vtk_module_python_default_destination(var)
Determine Python module destination.

By default, the destination is ${CMAKE_INSTALL_BINDIR}/Lib/site-packages on Windows and ${CMAKE_INSTALL_LIBDIR}/python<VERSION>/site-packages otherwise.

<MAJOR_VERSION>, if specified, must be 3.

Definition at line 45 of file vtkModuleWrapPython.cmake.

◆ vtk_module_wrap_python()

function vtk_module_wrap_python ( )

Wrap a set of modules for use in Python.

MODULES <module>...
[TARGET <target>]
[WRAPPED_MODULES <varname>]
[BUILD_STATIC <ON|OFF>]
[INSTALL_HEADERS <ON|OFF>]
[BUILD_PYI_FILES <ON|OFF>]
[DEPENDS <target>...]
[UTILITY_TARGET <target>]
[MODULE_DESTINATION <destination>]
[STATIC_MODULE_DESTINATION <destination>]
[CMAKE_DESTINATION <destination>]
[LIBRARY_DESTINATION <destination>]
[HEADERS_DESTINATION <destination>]
[PYTHON_PACKAGE <package>]
[SOABI <soabi>]
[USE_DEBUG_SUFFIX <ON|OFF>]
[REPLACE_DEBUG_SUFFIX <ON|OFF>]
[INTERPRETER <interpreter>]
[INSTALL_EXPORT <export>]
[COMPONENT <component>])
[TARGET_SPECIFIC_COMPONENTS <ON|OFF>]
function vtk_module_wrap_python()
Wrap a set of modules for use in Python.
  • MODULES: (Required) The list of modules to wrap.
  • TARGET: (Recommended) The target to create which represents all wrapped Python modules. This is mostly useful when supporting static Python modules in order to add the generated modules to the built-in table.
  • WRAPPED_MODULES: (Recommended) Not all modules are wrappable. This variable will be set to contain the list of modules which were wrapped. These modules will have a INTERFACE_vtk_module_python_package property set on them which is the name that should be given to import statements in Python code.
  • BUILD_STATIC: Defaults to ${BUILD_SHARED_LIBS}. Note that shared modules with a static build is not completely supported. For static Python module builds, a header named <TARGET>.h will be available with a function void <TARGET>_load() which will add all Python modules created by this call to the imported module table. For shared Python module builds, the same function is provided, but it is a no-op.
  • INSTALL_HEADERS (Defaults to ON): If unset, CMake properties will not be installed.
  • BUILD_PYI_FILES (Defaults to OFF): If set, .pyi files will be built and installed for the generated modules.
  • TARGET_SPECIFIC_COMPONENTS (Defaults to OFF): If set, prepend the output target name to the install component (<TARGET>-<COMPONENT>).
  • DEPENDS: This is list of other Python modules targets i.e. targets generated from previous calls to vtk_module_wrap_python that this new target depends on. This is used when BUILD_STATIC is true to ensure that the void <TARGET>_load() is correctly called for each of the dependencies.
  • UTILITY_TARGET: If specified, all libraries made by the Python wrapping will link privately to this target. This may be used to add compile flags to the Python libraries.
  • MODULE_DESTINATION: Modules will be placed in this location in the build tree. The install tree should remove $<CONFIGURATION> bits, but it currently does not. See vtk_module_python_default_destination for the default value.
  • STATIC_MODULE_DESTINATION: Defaults to ${CMAKE_INSTALL_LIBDIR}. This default may change in the future since the best location for these files is not yet known. Static libraries containing Python code will be installed to the install tree under this path.
  • CMAKE_DESTINATION: (Required if INSTALL_HEADERS is ON) Where to install Python-related module property CMake files.
  • LIBRARY_DESTINATION (Recommended): If provided, dynamic loader information will be added to modules for loading dependent libraries.
  • HEADERS_DESTINATION: Defaults to (${CMAKE_INSTALL_INCLUDEDIR}. Module loader headers will be installed to this directory.
  • PYTHON_PACKAGE: (Recommended) All generated modules will be added to this Python package. The format is in Python syntax (e.g., package.subpackage).
  • SOABI: (Required for wheel support): If given, generate libraries with the SOABI tag in the module filename.
  • USE_DEBUG_SUFFIX (Defaults to OFF): If ON, Windows modules will have a _d suffix appended to the module name. This is intended for use with debug Python builds.
  • REPLACE_DEBUG_SUFFIX (Defaults to OFF): If ON, any project-wide debug suffix will be replaced with the local debug suffix (if enabled).
  • INTERPRETER (Defaults to VTK::Python or Python3::Interpreter): If provided, this interpreter will be used to run supplemental processes which involve Python scripts including .pyi file generation. If a target name is provided, its path will be used, otherwise a string which expands to the path to an interpreter executable may be provided. If the string DISABLE is given, any support using interpreters will be disabled.
  • INSTALL_EXPORT: If provided, static installs will add the installed libraries to the provided export set.
  • COMPONENT: Defaults to python. All install rules created by this function will use this installation component.

Definition at line 627 of file vtkModuleWrapPython.cmake.

◆ vtk_module_add_python_package()

function vtk_module_add_python_package ( name  )

Install Python packages with a module.

Some modules may have associated Python code. This function should be used to install them.

PACKAGE <package>
FILES <files>...
[MODULE_DESTINATION <destination>]
[COMPONENT <component>])
function vtk_module_add_python_package(name)
Install Python packages with a module.

The <module> argument must match the associated VTK module that the package is with. Each package is independent and should be installed separately. That is, package and package.subpackage should each get their own call to this function.

  • PACKAGE: (Required) The package installed by this call. Currently, subpackages must have their own call to this function.
  • FILES: (Required) File paths should be relative to the source directory of the calling CMakeLists.txt. Upward paths are not supported (nor are checked for). Absolute paths are assumed to be in the build tree and their relative path is computed relative to the current binary directory.
  • MODULE_DESTINATION: Modules will be placed in this location in the build tree. The install tree should remove $<CONFIGURATION> bits, but it currently does not. See vtk_module_python_default_destination for the default value.
  • COMPONENT: Defaults to python. All install rules created by this function will use this installation component.

A <module>-<package> target is created which ensures that all Python modules have been copied to the correct location in the build tree.

Todo:
Support freezing the Python package. This should create a header and the associated target should provide an interface for including this header. The target should then be exported and the header installed properly.

Definition at line 1137 of file vtkModuleWrapPython.cmake.

◆ vtk_module_add_python_module()

function vtk_module_add_python_module ( name  )

Use a Python package as a module.

If a module is a Python package, this function should be used instead of vtk_module_add_module.

PACKAGES <packages>...)
function vtk_module_add_python_module(name)
Use a Python package as a module.
@ name
Definition: vtkX3D.h:231
  • PACKAGES: (Required) The list of packages installed by this module. These must have been created by the vtk_module_add_python_package function.

Definition at line 1235 of file vtkModuleWrapPython.cmake.