3 VTK 9.0 introduces a new build system compared to previous versions. This
4 version uses CMake's built-in functionality for behaviors that were performed
5 manually in the previous iteration of the build system.
9 - **module**: A unit of API provided by a project. This is the core of the
10 system and there are lots of features available through this mechanism that
11 are not provided by CMake's library or other usage requirements.
12 - **group**: A configure-time collection of modules. These may be used to
13 control whether member modules will be built or not with a single flag.
14 - **kit**: A collection of modules for which all the compiled code is placed
16 - **property**: An attribute of a module. Only of real interest to developers
17 of the module system and its extensions.
18 - **autoinit**: A mechanism for triggering registration to global registries
19 based on the complete set of linked-to libraries.
20 - **third party**: A module representing an external dependency.
21 - **enable status**: A 4-way state to allow for "weak" and "strong" selection
22 or deselection of a module or group for building.
26 The module system was designed with a number of principles in mind. These
27 should be followed as much as possible when developing extensions as well.
29 - The minimum CMake version required by the module system should be as low
30 as possible to get the required features. For example, if a new feature is
31 available in 3.15 that improves core module functionality, that'd be a
32 reasonable reason to require it. But a bugfix in 3.10 that can be worked
33 around should not bump the minimum version. Currently CMake 3.8 is
34 expected to work, though various features (such as kits) are only
35 available with newer CMake versions.
36 - Build tree looks like the install tree. The layout of the build tree is set
37 up to mirror the layout of the install tree. This allows more code content
38 to be shared between build and install time.
39 - Convention over configuration. CMake conventions should be followed. Of
40 note, projects are assumed to be "well-behaved" including, but not limited
42 - use of [`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] to control shared vs.
43 static library compilation;
44 - use of [`GNUInstallDirs`][GNUInstallDirs]; and
45 - sensible defaults based on things like
46 [`CMAKE_PROJECT_NAME`][cmake-CMAKE_PROJECT_NAME] as set by the
47 [`project()`][cmake-project] function.
48 - Configuration through API. Where configuration is provided, instead of
49 using global state or "magic" variables, configuration should be provided
50 through parameters to the API functions provided. Concessions are made for
51 rarely-used functionality or where the API would be complicated to plumb
52 through the required information. These variables (which are typically
53 parameterized) are documented at the end of this document. Such variables
54 should be named so that it is unambiguous that they are for the module
56 - Don't pollute the environment. Variables should be cleaned up at the end of
57 macros and functions should use variable names that don't conflict with the
58 caller environment (usually by prefixing with `_function_name_` or the
60 - Relocatable installs. Install trees should not bake-in paths from the build
61 tree or build machine (at least by default). This makes it easier to create
62 packages from install trees instead of having to run a post-processing step
63 over it before it may be used for distributable packages.
65 [BUILD_SHARED_LIBS]: https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html
66 [GNUInstallDirs]: https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
67 [cmake-CMAKE_PROJECT_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_PROJECT_NAME.html
68 [cmake-project]: https://cmake.org/cmake/help/latest/command/project.html
72 Building modules involves two phases. The first phase is called "scanning" and
73 involves collecting all the information necessary for the second phase,
74 "building". Scanning uses the [vtk_module_scan][] function to search the
75 [vtk.module][] files for metadata, gathers the set of modules to build and
76 returns them to the caller. That list of modules is eventually passed to
77 [vtk_module_build][] which sorts the modules for their build order and then
78 builds each module in turn. This separation allows for scanning and building
79 modules in different groups. For example, the main set of modules may be scanned
80 to determine which of some internal set of modules are required by those which
81 is then scanned separately with different options.
83 Scanning should occur from the leaf-most module set and work its way inward to
84 the lower levels. This is done so that modules in the lower level that are
85 required higher up can be enabled gracefully. Builds should start at the lower
86 level and move up the tree so that targets required by the higher groups exist
89 [vtk_module_scan]: @ref vtk_module_scan
90 [vtk.module]: @ref module-parse-module
91 [vtk_module_build]: @ref vtk_module_build
95 Modules are described by [vtk.module][] files. These files are "scanned" using
96 the [vtk_module_scan][] function. They provide all the information necessary for
99 - provide cache variables for selecting the module (e.g.,
100 `VTK_MODULE_ENABLE_ModuleName`);
101 - construct the dependency tree to automatically enable or disable modules
102 based on whether it is built or not;
103 - provide module-level metadata (such as exclusion from any wrapping and
104 marking modules as third party)
106 The [vtk.module][] files are read and "parsed", but not executed directly. This
107 ensures that the module files do not contain any procedural CMake code. The
108 files may contain comments starting with `#` like CMake code. They may either
109 be passed manually to [vtk_module_scan][] or discovered by using the
110 [vtk_module_find_modules][] convenience function.
112 The most important (and only required) parameter is the `NAME` of a module.
113 This is used as the target name in CMake and is how the module's target should
114 be referred to in all CMake code, inside the build and from the
115 [`find_package`][cmake-find_package] which provides the module. To change the
116 name of the compiled artifact (library or executable), the `LIBRARY_NAME`
117 argument may be used.
119 It is highly recommended to provide a `DESCRIPTION` for the module. This is
120 added to the documentation for the cache variable so that the user has more than
121 just the module name to know what the module's purpose is.
123 Modules may also belong to groups which are created implicitly by adding
124 modules to the same-named group. Groups are listed under the `GROUPS` argument
125 and are checked in order for a non-default setting to use.
127 A module may be hidden by using the `CONDITION` argument. The values passed to
128 this field is added into a CMake `if` statement and checked for validity (all
129 quoting is passed along verbatim). If the condition evaluates to `FALSE`, the
130 module is treated as if it did not exist at all.
132 [vtk_module_find_modules]: @ref vtk_module_find_modules
133 [cmake-find_package]: https://cmake.org/cmake/help/latest/command/find_package.html
137 A number of pieces of metadata are considered important enough to indicate them
138 at the module level. These are used for managing slightly different workflows
139 for modules which have these properties.
141 - `EXCLUDE_WRAP`: This marks the module with a flag that all language wrapping
142 facilities should use to know that this module is not meant for wrapping in
143 any language. Usually this is for modules containing user interface classes,
144 low-level functionality, or logic that is language specific.
145 - `IMPLEMENTABLE` and `IMPLEMENTS`: These are used by the
146 [autoinit](#autoinit) functionality to trigger the static factory
147 registration calls. A module which is listed under an `IMPLEMENTS` list must
148 be marked as `IMPLEMENTABLE` itself.
149 - `THIRD_PARTY`: Indicates that the module represents a third party
150 dependency. It may be internal or external to the source tree, but may be
151 used as an additional configuration point if necessary. These modules are
152 implicitly `EXCLUDE_WRAP`, not `IMPLEMENTABLE` and do not `IMPLEMENTS` any
155 ## Enabling modules for build
157 Modules are enabled in a number of ways. These ways allow for project control
158 and user control of which modules should be built or not. There are 4 states for
159 controlling a module's [enable status][enable-status] as well as a `DEFAULT`
160 setting which is used to allow for other mechanisms to select the enable status:
162 - `YES`: The module must be built.
163 - `NO`: The module must not be built. If a `YES` module has a `NO` module in
164 its dependency tree, an error is raised.
165 - `WANT`: The module should be built. It will not be built, however, if it
166 depends on a `NO` module.
167 - `DONT_WANT`: The module doesn't need to be built. It will be built if a
168 `YES` or `WANT` module depends on it.
169 - `DEFAULT`: Look at other metadata to determine the status.
171 The first check for modules are via the `REQUEST_MODULES` and `REJECT_MODULES`
172 arguments to the `vtk_module_scan` function. Modules passed to
173 `REQUEST_MODULES` are treated as if they use `YES` and `REJECT_MODULES` as if
174 they use `NO`. A module may not be passed to both arguments. Modules selected
175 in this way do not have CMake cache variables exposed for them (since it is
176 assumed they are selected via some other mechanism outside the module system).
178 The next selector is the `VTK_MODULE_ENABLE_` variable for the module. This is
179 added to the cache and defaults to `DEFAULT`. Assuming `HIDE_MODULES_FROM_CACHE`
180 is not set to `ON`, this setting is exposed in the cache and allows users to
181 change the status of modules not handled via the `REQUEST_MODULES` and
182 `REJECT_MODULES` mechanism.
184 If a module is still selected as `DEFAULT`, the list of `GROUPS` it is a member
185 of is used. In order, each group is looked at for a non-`DEFAULT` value. If so,
186 its value is used for the module. Groups also default to using `DEFAULT` for
187 their setting, but a project may set the `_vtk_module_group_default_${group}`
188 variable to change this default value.
190 After all of the above logic, if a module is still marked as `DEFAULT`, the
191 `WANT_BY_DEFAULT` argument to [vtk_module_scan][] is used to determine whether
192 it is treated as a `WANT` or `DONT_WANT` request.
194 Now that all modules have a non-`DEFAULT` enable setting, the set of modules and
195 kits that are available may be determined by traversing the dependency tree of
198 [enable-status]: @ref module-enable-status
202 Modules have three types of dependencies:
204 - `DEPENDS`: These are dependencies which must be available and are
205 transitively provided to modules depending on this module. The API of the
206 module may be affected by changes in these modules. This includes, but is
207 not limited to, classes in this module inherit or expose classes from the
209 - `PRIVATE_DEPENDS`: Dependencies which are only used in the implementation
210 details of the module. The API of the module is not affected by changes in
212 - `OPTIONAL_DEPENDS`: Dependencies which will be used if available, but the
213 implementation can cope with their absence. These are always treated as
214 `PRIVATE_DEPENDS` if they are available.
216 Modules which are listed in `DEPENDS` or `PRIVATE_DEPENDS` are always available
217 to the module and can be assumed to exist if the module is being built. Modules
218 listed in `OPTIONAL_DEPENDS` cannot be assumed to exist. In CMake code, a
219 `TARGET optional_depend` condition may be used to detect whether it is available
220 or not. The module system will add a `VTK_MODULE_ENABLE_${module}` compilation
221 definition set to either `0` or `1` if it is available for use in the module's
222 code. This flag is made preprocessor-safe by replacing any `::` in the module
223 name with `_`. So an optional dependency on `Namespace::Target` will use a flag
224 named `VTK_MODULE_ENABLE_Namespace_Target`.
226 At this stage, the dependency tree for all scanned modules is traversed, marking
227 dependencies of `YES` modules as those that should be built, marking modules
228 depending on `NO` modules as not to be built (and triggering an error if a
229 conflict is found). Any `WANT` modules that have not been found in the trees of
230 `YES` or `NO` modules are then enabled with their dependencies.
234 There is some support for testing in the module system, but it is not as
235 comprehensive as the build side. This is because testing infrastructure and
236 strategies vary wildly between projects. Rather than trying to handle the
237 minimum baseline of any plausible testing infrastructure or framework, the
238 module system merely handles dependency management for testing and entering a
239 subdirectory with the tests.
241 Modules may have `TEST_DEPENDS` and `TEST_OPTIONAL_DEPENDS` lists provided as
242 well. These modules are required or optionally used by the testing code for the
245 When scanning, the `ENABLE_TESTS` argument may be set to `ON`, `OFF`, `WANT`
246 (the default), or `DEFAULT`. Modules which appear in `TEST_DEPENDS` for the
247 module are affected by this setting.
249 - `ON`: Modules required for testing are treated as required. Tests will be
251 - `OFF`: Tests will not be enabled.
252 - `WANT`: If possible, `TEST_DEPENDS` modules will also be enabled if they are
253 not disabled in some other way.
254 - `DEFAULT`: Check when tests are checked whether all of `TEST_DEPENDS` are
255 available. If they are, enable testing for the module, otherwise skip it.
257 The only guarantee for testing provided is that all modules in the
258 `TEST_DEPENDS` will be available before the testing is added and
259 `TEST_OPTIONAL_DEPENDS` are available if they'd be available at all (i.e., they
260 won't be made available later).
262 Modules may also have `TEST_LABELS` set to ease labeling all tests for the
263 module. The module system itself does nothing with this other than set a global
264 property with the value. It is up to any test infrastructure used within the
265 module's CMake code to make use of the value.
267 The tests for a module are expected to live in a subdirectory of the module code
268 itself. The name of this directory is given by the `TEST_DIRECTORY_NAME`
269 argument to the [vtk_module_build][] function. If the directory is available and
270 the module's testing is enabled, the module system will
271 [`add_subdirectory`][cmake-add_subdirectory] this directory at the appropriate
272 time. This is decoupled so that testing code can depend on modules that depend
273 on the module that is being tested and the same `TARGET ${dependency}` check can
274 be used for optional module dependencies.
276 [cmake-add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
280 After scanning is complete, [vtk_module_scan][] returns a list of modules and
281 kits to build in the variables given by the `PROVIDES_MODULES` and
282 `PROVIDES_KITS` arguments to it. It also provides lists of modules that were
283 found during scanning that were not scanned by that call. These are given back
284 in the variables passed to the `UNRECOGNIZED_MODULES` and `REQUIRES_MODULES`
287 The `UNRECOGNIZED_MODULES` list contains modules passed to `REQUIRES_MODULES`
288 and `REJECT_MODULES` that were not found during the scan. This typically
289 indicates that the values passed to those arguments were not constructed
290 properly. However, it may also mean that they should be passed on to further
291 scans if they may be found elsewhere. Callers should handle the variable as
292 necessary for their use case.
294 The `REQUIRES_MODULES` are modules that were named as dependencies of the
295 scanned modules and need to be provided in some way before building the provided
296 modules (the build step will require that they exist when it tries to build the
297 modules which required them). These can be passed on to future
298 `REQUIRES_MODULES` arguments in future scans or used to error out depending on
299 the use case of the caller.
301 When using [vtk_module_build][], the `PROVIDES_MODULES` and `PROVIDES_KITS` from
302 a single scan should be passed together. Multiple scans may be built together as
303 well if they all use the same build parameters as each other.
305 ## Build-time parameters
307 The [vtk_module_build][] function is where the decision to build with or without
308 kits is decided through the `BUILD_WITH_KITS` option. Only if this is set will
309 kits be built for this set of modules.
311 The decision to default third party modules to using an external or internal
312 copy (where such a decision is possible) is done using the `USE_EXTERNAL`
315 Where build artifacts end up in the build tree are left to CMake's typical
316 variables for controlling these locations:
318 - [`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`][cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]
319 - [`CMAKE_LIBRARY_OUTPUT_DIRECTORY`][cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]
320 - [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`][cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]
322 The defaults for these place outputs into the binary directory where the targets
323 were added. The module system will set these to be sensible for itself if they
324 are not already set, but it is recommended to set these at the top-level so that
325 targets not built under [vtk_module_build][] also end up at a sensible location.
327 [cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.html
328 [cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.html
329 [cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html
331 ## Library parameters
333 When building libraries, it is sometimes useful to have top-level control of
334 library metadata. For example, VTK suffixes its library filenames with a version
335 number. The variables that control this include:
337 - `LIBRARY_NAME_SUFFIX`: If non-empty, all libraries and executable names will
338 be suffixed with this value prefixed with a hyphen (e.g., a suffix of `foo`
339 will make `Namespace::Target`'s library be named `Target-foo` or, if the
340 module sets its `LIBRARY_NAME` to `nsTarget`, `nsTarget-foo`).
341 - `VERSION`: Controls the [`VERSION`][cmake-VERSION] property for all library
343 - `SOVERSION`: Controls the [`SOVERSION`][cmake-SOVERSION] property for all
346 [cmake-VERSION]: https://cmake.org/cmake/help/latest/prop_tgt/VERSION.html
347 [cmake-SOVERSION]: https://cmake.org/cmake/help/latest/prop_tgt/SOVERSION.html
349 ## Installation support
351 [vtk_module_build][] also offers arguments to aid in installing module
352 artifacts. These include destinations for pieces that are installed, CMake
353 packaging controls, and components to use for the installations.
355 A number of destinations control arguments are provided:
357 - `ARCHIVE_DESTINATION`
358 - `HEADERS_DESTINATION`
359 - `LIBRARY_DESTINATION`
360 - `RUNTIME_DESTINATION`
361 - `CMAKE_DESTINATION`
362 - `LICENSE_DESTINATION`
363 - `HIERARCHY_DESTINATION`
365 See the API documentation for default values for each which are based on
366 [`GNUInstallDirs`][GNUInstallDirs] variables. Note that all installation
367 destinations are expected to be relative paths. This is because the conveniences
368 provided by the module system are all assumed to be installed to a single prefix
369 ([`CMAKE_INSTALL_PREFIX`][cmake-CMAKE_INSTALL_PREFIX]) and placed underneath it.
371 Suppression of header installation is provided via the `INSTALL_HEADERS`
372 argument to [vtk_module_build][]. Setting this to `OFF` will suppress the
376 - CMake package files
377 - hierarchy files (since their use requires headers)
379 Basically, suppression of headers means that SDK components for the built
380 modules are not available in the install tree.
382 Components for the installation are provided via the `HEADERS_COMPONENT` and
383 `TARGETS_COMPONENT` arguments. The former is used for SDK bits and the latter
384 for runtime bits (libraries, executables, etc.).
386 For CMake package installation, the `PACKAGE` and `INSTALL_EXPORT` arguments are
387 available. The former controls the names used by the CMake files created by the
388 module system while the former is the export set to use for the member modules
389 when creating those CMake files. Non-module targets may also exist in this
390 export set when [vtk_module_build][] is called, but the export set is considered
391 "closed" afterwards since it has already been exported (if `INSTALL_HEADERS` is
394 [cmake-CMAKE_INSTALL_PREFIX]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html
396 ## Test data information
398 The directory that is looked for in each module is specified by using the
399 `TEST_DIRECTORY_NAME` argument. If it is set to the value of `NONE`, no testing
400 directories will be searched for. It defaults to `Testing` due to VTK's
403 The module system, due to VTK's usage of it, has convenience parameters for
404 controlling the [`ExternalData`][ExternalData] module that is available to
405 testing infrastructure. These include:
407 - `TEST_DATA_TARGET`: The data target to use for tests.
408 - `TEST_INPUT_DATA_DIRECTORY`: Where `ExternalData` should look for data
410 - `TEST_OUTPUT_DATA_DIRECTORY`: Where `ExternalData` should place the
411 downloaded data files.
412 - `TEST_OUTPUT_DIRECTORY`: Where tests should place output files.
414 Each is provided in the testing subdirectory as `_vtk_build_${name}`, so the
415 `TEST_DATA_TARGET` argument is available as `_vtk_build_TEST_DATA_TARGET`.
417 [ExternalData]: https://cmake.org/cmake/help/latest/module/ExternalData.html
421 Building a module is basically the same as a normal CMake library or executable,
422 but is wrapped to use arguments to facilitate wrapping, exporting, and
423 installation of the tools as well.
425 There are two main functions provided for this:
427 - [vtk_module_add_module][]
428 - [vtk_module_add_executable][]
430 The former creates a library for the module being built while the latter can
431 create an executable for the module itself or create utility executable
432 associated with the module. The module system requires that the `CMakeLists.txt`
433 for a module create a target with the name of the module. In the case of
434 `INTERFACE` modules, it suffices to create the module manually in many cases.
438 Most modules end up being libraries that can be linked against by other
439 libraries. Due to cross-platform support generally being a good thing, the
440 `EXPORT_MACRO_PREFIX` argument is provided to specify the prefix for macro names
441 to be used by [`GenerateExportHeader`][GenerateExportHeader]. By default, the
442 `LIBRARY_NAME` for the module is transformed to uppercase to make the prefix.
444 Some modules may need to add additional information to the library name that
445 will be used that is not statically know and depends on other environmental
446 settings. The `LIBRARY_NAME_SUFFIX` may be specified to add an additional suffix
447 to the `LIBRARY_NAME` for the module. The [vtk_module_build][]
448 `LIBRARY_NAME_SUFFIX` argument value will be appended to this name as well.
450 Normally, libraries are built according to the
451 [`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] variable, however, some modules may
452 need to be built statically all the time. The `FORCE_STATIC` parameter exists
453 for this purpose. This is generally only necessary if the module is in some
454 other must-be-static library's dependency tree (which may happen for a number of
455 reasons). It is not an escape hatch for general usage; it is there because use
456 cases which only support static libraries (even in a shared build) exist.
458 If a library module is part of a kit and it is being built via the
459 [vtk_module_build][] `BUILD_WITH_KITS` argument, it will be built as an
460 [`OBJECT`][cmake-OBJECT] library and the kit machinery in [vtk_module_build][]
461 will create the resulting kit library artifact.
463 Header-only modules must pass `HEADER_ONLY` to create an `INTERFACE` library
464 instead of expecting a linkable artifact.
466 @note `HEADER_ONLY` modules which are part of kits is currently untested. This
467 should be supported, but might not work at the moment.
469 [cmake-OBJECT]: https://cmake.org/cmake/help/latest/command/add_library.html
470 [vtk_module_add_module]: @ref vtk_module_add_module
471 [vtk_module_add_executable]: @ref vtk_module_add_executable
472 [GenerateExportHeader]: https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html
476 Instead of using CMake's "all sources in a single list" pattern for
477 `add_library`, [vtk_module_add_module][] classifies its source files explicitly:
483 The `HEADERS` and `TEMPLATES` are installed into the `HEADERS_DESTINATION`
484 specified to [vtk_module_build][] and may be added to a subdirectory of this
485 destination by using the `HEADERS_SUBDIR` argument. Note that the structure of
486 the header paths passed is ignored. If more structure is required from the
487 installed header layout, [vtk_module_install_headers][] should be used.
489 Files passed via `HEADERS` are treated as the API interface to the code of the
490 module and are added to properties so that [language wrappers](#wrapping) can
491 discover the API of the module.
493 @note Only headers passed via `HEADERS` are eligible for wrapping; those
494 installed via [vtk_module_install_headers][] are not. This is a known limitation
497 There are also private variations for `HEADERS` and `TEMPLATES` named
498 `PRIVATE_HEADERS` and `PRIVATE_TEMPLATES` respectively. These are never
499 installed nor exposed to wrapping mechanisms.
501 There are also a couple of convenience parameters that use VTK's file naming
502 conventions to ease usage. These include:
504 - `CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES` and
505 `<class>.h` to `HEADERS`.
506 - `TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
507 `TEMPLATES` and `<class>.h` to `HEADERS`.
508 - `PRIVATE_CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES`
509 and `<class>.h` to `PRIVATE_HEADERS`.
510 - `PRIVATE_TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
511 `PRIVATE_TEMPLATES` and `<class>.h` to `PRIVATE_HEADERS`.
513 [vtk_module_install_headers]: @ref vtk_module_install_headers
517 Executables may be created using [vtk_module_add_executable][]. The first
518 argument is the name of the executable to build. Since the scanning phase does
519 not know what kind of target will be created for each module (and it may change
520 based on other configuration values), an executable module which claims it is
521 part of a kit raises an error since this is not possible to do.
523 For modules that are executables using this function, the metadata from the
524 module information is used to set the relevant properties. The module
525 dependencies are also automatically linked in the same way as a library module
528 For utility executables, `NO_INSTALL` may be passed to keep it within the build
529 tree. It will not be available to consumers of the project. If the name of the
530 executable is different from the target name, `BASENAME` may be used to change
531 the executable's name.
535 All of CMake's `target_` function calls have [analogues][module-as-target] for
536 modules. This is primarily due to the kits feature which causes the target name
537 created by the module system that is required to use the `target_` functions
538 dependent on whether the module is a member of a kit and kits are being built.
539 The CMake version of the function and the module API analogue (as well as
540 differences, if any) is:
542 - [set_target_properties][cmake-set_target_properties] becomes
543 [vtk_module_set_properties][]
544 - [set_property(TARGET)][cmake-set_property] becomes
545 [vtk_module_set_property][]
546 - [get_property(TARGET)][cmake-get_property] becomes
547 [vtk_module_get_property][]
548 - [add_dependencies][cmake-add_dependencies] becomes [vtk_module_depend][]
549 - [target_include_directories][cmake-target_include_directories] becomes
550 [vtk_module_include][]
551 - [target_compile_definitions][cmake-target_compile_definitions] becomes
552 [vtk_module_definitions][]
553 - [target_compile_options][cmake-target_compile_options] becomes
554 [vtk_module_compile_options][]
555 - [target_compile_features][cmake-target_compile_features] becomes
556 [vtk_module_compile_features][]
557 - [target_link_libraries][cmake-target_link_libraries] becomes
558 [vtk_module_link][]: When kits are enabled, any `PRIVATE` links are
559 forwarded to the kit itself. This necessitates making all of these targets
560 globally scoped rather than locally scoped.
561 - [target_link_options][cmake-target_link_options] becomes
562 [vtk_module_link_options][]
564 [module-as-target]: @ref module-target-functions
565 [cmake-set_target_properties]: https://cmake.org/cmake/help/latest/command/set_target_properties.html
566 [cmake-set_property]: https://cmake.org/cmake/help/latest/command/set_property.html
567 [cmake-get_property]: https://cmake.org/cmake/help/latest/command/get_property.html
568 [cmake-add_dependencies]: https://cmake.org/cmake/help/latest/command/add_dependencies.html
569 [cmake-target_include_directories]: https://cmake.org/cmake/help/latest/command/target_include_directories.html
570 [cmake-target_compile_definitions]: https://cmake.org/cmake/help/latest/command/target_compile_definitions.html
571 [cmake-target_compile_options]: https://cmake.org/cmake/help/latest/command/target_compile_options.html
572 [cmake-target_compile_features]: https://cmake.org/cmake/help/latest/command/target_compile_features.html
573 [cmake-target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html
574 [cmake-target_link_options]: https://cmake.org/cmake/help/latest/command/target_link_options.html
575 [vtk_module_set_properties]: @ref vtk_module_set_properties
576 [vtk_module_set_property]: @ref vtk_module_set_property
577 [vtk_module_get_property]: @ref vtk_module_get_property
578 [vtk_module_depend]: @ref vtk_module_depend
579 [vtk_module_include]: @ref vtk_module_include
580 [vtk_module_definitions]: @ref vtk_module_definitions
581 [vtk_module_compile_options]: @ref vtk_module_compile_options
582 [vtk_module_compile_features]: @ref vtk_module_compile_features
583 [vtk_module_link]: @ref vtk_module_link
584 [vtk_module_link_options]: @ref vtk_module_link_options
588 Getting installed packages to work for CMake is, unfortunately, not trivial. The
589 module system provides some support for helping with this, but it does place
590 some extra constraints on the project so that some assumptions that vastly
591 simplify the process can be made.
595 The main assumption is that all modules passed to a single [vtk_module_build][]
596 have the same CMake namespace (the part up to and including the `::`, if any,
597 in a module name. For exporting dependencies, that namespace matches the
598 `PACKAGE` argument for [vtk_module_build][]. These are done so that the
599 generated code can use
600 [`CMAKE_FIND_PACKAGE_NAME`][cmake-CMAKE_FIND_PACKAGE_NAME] variable can be
601 used to discover information about the package that is being found.
603 The package support also assumes that all modules may be queried using
604 `COMPONENTS` and `OPTIONAL_COMPONENTS` and that the component name for a module
605 corresponds to the name of a module without the namespace.
607 These rules basically mean that a module named `Namespace::Target` will be found
608 using `find_package(Namespace)`, that `COMPONENTS Target` may be passed to
609 ensure that that module exists, and `OPTIONAL_COMPONENTS Target` may be passed
610 to allow the component to not exist while not failing the main
611 [`find_package`][cmake-find_package] call.
613 [cmake-CMAKE_FIND_PACKAGE_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NAME.html
615 ## Creating a full package
617 The module system provides no support for the top-level file that is used by
618 [`find_package`][cmake-find_package]. This is because this logic is highly
619 project-specific and hard to generalize in a useful way. Instead, files are
620 generated which should be included from the main file.
622 Here, the list of files generated are based on the `PACKAGE` argument passed to
623 [vtk_module_build][]:
625 - `<PACKAGE>-targets.cmake`: The CMake-generated export file for the targets
626 in the `INSTALL_EXPORT`.
627 - `<PACKAGE>-vtk-module-properties.cmake`: Properties for the targets exported
630 The module properties file must be included after the targets file so that they
631 exist when it tries to add properties to the imported targets.
633 ## External dependencies
635 Since the module system is heavily skewed towards using imported targets, these
636 targets show up by name in the [`find_package`][cmake-find_package] of the
637 project as well. This means that these external projects need to be found to
638 recreate their imported targets at that time. To this end, there is the
639 [vtk_module_export_find_packages][] function. This function writes a file named
640 according to its `FILE_NAME` argument and place it in the build and install
641 trees according to its `CMAKE_DESTINATION` argument.
643 This file will be populated with logic to determine whether third party packages
644 found using [vtk_module_find_package][] are required during the
645 [`find_package`][cmake-find_package] of the package or not. It will forward
646 `REQUIRED` and `QUIET` parameters to other [`find_package`][cmake-find_package]
647 calls as necessary based on the `REQUIRED` and `QUIET` flags for the package
648 and whether that call is involved in a non-optional `COMPONENT` (a
649 component-less [`find_package`][cmake-find_package] call is assumed to mean
652 This file should be included after the `<PACKAGE>-vtk-module-properties.cmake`
653 file generated by the [vtk_module_build][] call so that it can use the module
654 dependency information set via that file.
656 After this file is included, for each component that it checks, it will set
657 `${CMAKE_FIND_PACKAGE_NAME}_<component>_FOUND` to 0 if it is not valid and
658 append a reason to `${CMAKE_FIND_PACKAGE_NAME}_<component>_NOT_FOUND_MESSAGE`
659 so that the package can collate the reason why things are not available.
661 [vtk_module_export_find_packages]: @ref vtk_module_export_find_packages
662 [vtk_module_find_package]: @ref vtk_module_find_package
664 ## Setting the `_FOUND` variable
666 The module system does not currently help in determining the top-level
667 `${CMAKE_FIND_PACKAGE_NAME}_FOUND` variable based on the results of the
668 components that were requested and the status of dependent packages. This may be
669 provided at some point, but there has not currently been enough experience to
670 determine what patterns are available for factoring it out as a utility
673 The general pattern should be to go through the list of components requested,
674 determine whether targets for those components exist. Then for each found
675 component, use the module dependency information to ensure that all targets in
676 the dependency trees are found (propagating not-found statuses through the
677 dependency tree). The `${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE` should be
678 built up based on the reasons the [`find_package`][cmake-find_package] call did
679 not work based on these discoveries.
681 This is the process for modules in a package, but packages may contain
682 non-module components, and it is hard for the module system to provide support
683 for them, so they are not attempted. See the CMake documentation for more
684 details about [creating a package configuration][cmake-create-package-config].
686 [cmake-create-package-config]: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#creating-a-package-configuration-file
690 There are a number of advanced features provided by the module system that are
691 not normally required in a simple project.
695 Kits are described in [vtk.kit][] files which act much like [vtk.module][]
696 files. However, they only have `NAME`, `LIBRARY_NAME`, and `DESCRIPTION` fields.
697 These all act just like they do in the `vtk.module` context. These files may
698 either be passed manually to [vtk_module_scan][] or discovered by using the
699 [vtk_module_find_kits][] convenience function.
701 Before a module may be a member of a kit, a [vtk.kit][] must declare it and be
702 scanned at the same time. This means that kits may only contain modules that are
703 scanned with them and cannot be extended later nor may kits be made of modules
704 that they do not know about.
706 [vtk.kit]: @ref module-parse-kit
707 [vtk_module_find_kits]: @ref vtk_module_find_kits
711 In order to actually use kits, CMake 3.12 is necessary in order to do the
712 [`OBJECT`][cmake-OBJECT] library manipulations done behind the scenes to make it
713 Just Work. 3.8 is still the minimum version for using a project that is built
714 with kits however. This is only checked when kits are actually in use, so
715 projects requiring older CMake versions as their minimum version may still
716 provide kits so that users with newer CMake versions can use them.
718 Kits create a single library on disk, but the usage requirements of the modules
719 should still be the same (except for that which is inherently required to be
720 different by combining libraries). So include directories, compile definitions,
721 and other usage requirements should not leak from other modules that are members
724 <a name="autoinit"></a>
727 The module system supports a mechanism for triggering static code construction
728 for modules which require it. This cannot be done through normal CMake usage
729 requirements because the requirements are intersectional. For example, a module
730 `F` having a factory where module `I` provides an implementation for it means
731 that a target linking to both `F` and `I` needs to ensure that `I` registers its
732 implementation to the factory code. There is no such support in CMake and due to
733 the complexities and code generation involved with this support, it is unlikely
736 Code which uses modules may call the [vtk_module_autoinit][] function to use
737 this functionality. The list of modules passed to the function are used to
738 compute the defines necessary to trigger the registration to factories when
741 For details on the implementation of the autoinit system, please see
742 [the relevant section][autoinit] in the API documentation.
744 [vtk_module_autoinit]: @ref vtk_module_autoinit
745 [autoinit]: @ref module-autoinit
747 <a name="wrapping"></a>
750 VTK comes with support for wrapping its classes into other languages.
751 Currently, VTK supports wrapping its classes for use in the Python and Java
752 languages. In order to wrap a set of modules for a language, a separate
753 function is used for each language.
755 All languages read the headers of classes with a `__VTK_WRAP__` preprocessor
756 definition defined. This may be used to hide methods or other details from the
757 wrapping code if wanted.
761 For Python, the [vtk_module_wrap_python][] function must be used. This function
762 takes a list of modules in its `MODULES` argument and creates Python modules
763 for use under the `PYTHON_PACKAGE` package. No `__init__.py` for this package
764 is created automatically and must be provided in some other way.
766 A target named by the `TARGET` argument is created and installed. This target
767 may be linked to in order to be able to import static Python modules. In this
768 case, a header and function named according to the basename of `TARGET` (e.g.,
769 `VTK::PythonWrapped` has a basename of `PythonWrapped`) must be used. The
770 header is named `<TARGET_BASENAME>.h` and the function which adds the wrapped
771 modules to the static import table is `<void TARGET_BASENAME>_load()`. This
772 function is also created in shared builds, but does nothing so that it may
773 always be called in static or shared builds.
775 The modules will be installed under the `MODULE_DESTINATION` given to the
776 function into the `PYTHON_PACKAGE` directory needed for it. The
777 [vtk_module_python_default_destination][] function is used to determine a
778 default if one is not passed.
780 The Python wrappers define a `__VTK_WRAP_PYTHON__` preprocessor definition when
781 reading code which may be used to hide methods or other details from the Python
784 [vtk_module_wrap_python]: @ref vtk_module_wrap_python
785 [vtk_module_python_default_destination]: @ref vtk_module_python_default_destination
789 For Java, the [vtk_module_wrap_java][] function must be used. This function
790 creates Java sources for classes in the modules passed in its `MODULES`
791 argument. The sources are written to a `JAVA_OUTPUT` directory. These then can
792 be compiled by CMake normally.
794 For this purpose, there are `<MODULE>Java` targets which contain a
795 `_vtk_module_java_files` properties containing a list of `.java` sources
796 generated for the given module. There is also a `<MODULE>Java-java-sources`
797 target which may be depended upon if just the source generation needs to used
798 in an [`add_dependencies`][cmake-add_dependencies] call.
800 The Java wrappers define a `__VTK_WRAP_JAVA__` preprocessor definition when
801 reading code which may be used to hide methods or other details from the Java
804 [vtk_module_wrap_java]: @ref vtk_module_wrap_java
808 Hierarchy files are used by the language wrapper tools to know the class
809 inheritance for classes within a module. Each module has a hierarchy file
810 associated with it. The path to a module's hierarchy file is stored in its
811 `hierarchy` module property.
815 The module system has support for representing third party modules in its
816 build. These may be built as part of the project or represented using other
817 mechanisms (usually [`find_package`][cmake-find_package] and a set of imported
820 The primary API is [vtk_module_third_party][] which creates a
821 `VTK_MODULE_USE_EXTERNAL_Namespace_Target` option for the module to switch
822 between an internal and external source for the third party code. This value
823 defaults to the setting of the `USE_EXTERNAL` argument for the calling
824 [vtk_module_build][] function. Arguments passed under the `INTERNAL` and
825 `EXTERNAL` arguments to this command are then passed on to
826 [vtk_module_third_party_internal][] or [vtk_module_third_party_external][],
827 respectively, depending on the `VTK_MODULE_USE_EXTERNAL_Namespace_Target`
830 Note that third party modules (marked as such by adding the `THIRD_PARTY`
831 keyword to a `vtk.module` file) may not be part of a kit, be wrapped, or
832 participate in autoinit.
834 [vtk_module_third_party]: @ref vtk_module_third_party
835 [vtk_module_third_party_internal]: @ref vtk_module_third_party_internal
836 [vtk_module_third_party_external]: @ref vtk_module_third_party_external
838 ### External third party modules
840 External modules are found using CMake's [`find_package`][cmake-find_package]
841 mechanism. In addition to the arguments supported by
842 [vtk_module_find_package][] (except `PRIVATE`), information about the found
843 package is used to construct a module target which represents the third party
844 package. The preferred mechanism is to give a list of imported targets to the
845 `LIBRARIES` argument. These will be added to the `INTERFACE` of the module and
846 provide the third party package for use within the module system.
848 If imported targets are not available (they really should be created if not),
849 variable names may be passed to `INCLUDE_DIRS`, `LIBRARIES`, and `DEFINITIONS`
850 to create the module interface.
852 In addition, any variables which should be forwarded from the package to the
853 rest of the build may be specified using the `USE_VARIABLES` argument.
855 The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
856 module target which includes the "standard" module include directories to.
857 Basically, the source and binary directories of the module.
859 ### Internal third party modules
861 Internal modules are those that may be built as part of the build. These should
862 ideally specify a set of `LICENSE_FILES` indicating the license status of the
863 third party code. These files will be installed along with the third party
864 package to aid in any licensing requirements of the code. It is also
865 recommended to set the `VERSION` argument so that it is known what version of
866 the code is provided at a glance.
868 By default, the `LIBRARY_NAME` of the module is used as the name of the
869 subdirectory to include, but this may be changed by using the `SUBDIRECTORY`
872 Header-only third party modules may be indicated by using the `HEADER_ONLY`
873 argument. Modules which represent multiple libraries at once from a project may
874 use the `INTERFACE` argument.
876 The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
877 module target which includes the "standard" module include directories to.
878 Basically, the source and binary directories of the module. A subdirectory may
879 be used by setting the `HEADERS_SUBDIR` option. It is implied for
880 `HEADERS_ONLY` third party modules.
882 After the subdirectory is added a target with the module's name must exist.
883 However, a target is automatically created if it is `HEADERS_ONLY`.
885 #### Properly shipping internal third party code
887 There are many things that really should be done to ship internal third party
888 code (also known as vendoring) properly. The issue is mainly that the internal
889 code may conflict with other code bringing in another copy of the same package
890 into a process. Most platforms do not behave well in this situation.
892 In order to avoid conflicts at every level possible, a process called "name
893 mangling" should be performed. A non-exhaustive list of name manglings that
894 must be done to fully handle this case includes:
896 - moving headers to a subdirectory (to avoid compilations from finding
897 incompatible headers);
898 - changing the library name (to avoid DLL lookups from finding incompatible
900 - mangling symbols (to avoid symbol lookup from confusing two copies in the
903 Some projects may need further work like editing CMake APIs or the like to be
906 Moving headers and changing library names is fairly straightforward by editing
907 CMake code. Mangling symbols usually involves creating a header which has a
908 `#define` for each public symbol to change its name at runtime to be distinct
909 from another copy that may end up existing in the same process from another
912 Typically, a header needs to be created at the module level which hides the
913 differences between third party code which may or may not be provided by an
914 external package. In this case, it is recommended that code using the third
915 party module use unmangled names and let the module interface and mangling
916 headers handle the mangling at that level.
920 The module system can output debugging information about its inner workings by
921 using the `_vtk_module_log` variable. This variable is a list of "domains" to
922 log about, or the special `ALL` value causes all domains to log output. The
923 following domains are used in the internals of the module system:
925 - `kit`: discovery and membership of kits
926 - `module`: discovery and `CONDITION` results of modules
927 - `enable`: resolution of the enable status of modules
928 - `provide`: determination of module provision
929 - `building`: when building a module occurs
930 - `testing`: missing test dependencies
932 It is encouraged that projects expose user-friendly flags to control logging
933 rather than exposing `_vtk_module_log` directly.
937 These variables do not follow the API convention and are used if set:
939 - `_vtk_module_warnings`: If enabled, "strict" warnings are generated. These
940 are not strictly problems, but may be used as linting for improving usage of
942 - `_vtk_module_log`: A list of "domains" to output debugging information.
943 - `_vtk_module_group_default_${group}`: used to set a non-`DEFAULT` default
946 Some mechanisms use global properties instead:
948 - `_vtk_module_autoinit_include`: The file that needs to be included in order
949 to make the `VTK_MODULE_AUTOINIT` symbol available for use in the
950 [autoinit][] support.