VTK  9.2.6
/tmp/B.1nvwckdy/BUILD/VTK-9.2.6/Documentation/Doxygen/ModuleSystem.md
Go to the documentation of this file.
1 # Module System
2 
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.
6 
7 # Terminology
8 
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
15  in a single library.
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.
23 
24 # Principles
25 
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.
28 
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
41  to:
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
55  system.
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
59  like).
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.
64 
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
69 
70 # Build process
71 
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.
82 
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
87 when they are built.
88 
89 [vtk_module_scan]: @ref vtk_module_scan
90 [vtk.module]: @ref module-parse-module
91 [vtk_module_build]: @ref vtk_module_build
92 
93 # Modules
94 
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
97 the module system to:
98 
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)
105 
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.
111 
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.
118 
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.
122 
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.
126 
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.
131 
132 [vtk_module_find_modules]: @ref vtk_module_find_modules
133 [cmake-find_package]: https://cmake.org/cmake/help/latest/command/find_package.html
134 
135 ## Module metadata
136 
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.
140 
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
153  module.
154 
155 ## Enabling modules for build
156 
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:
161 
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.
170 
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).
177 
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.
183 
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.
189 
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.
193 
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
196 the modules.
197 
198 [enable-status]: @ref module-enable-status
199 
200 ## Dependencies
201 
202 Modules have three types of dependencies:
203 
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
208  dependent modules.
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
211  these modules.
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.
215 
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`.
225 
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.
231 
232 There is a script to help figuring out dependencies when building your own modules
233 or VTK-dependant code (*.cxx, *.h) in order to generate a [`find_package`][cmake-find_package]
234 command. The required json argument is only available in a build tree though.
235 
236 `Utilities/Maintenance/FindNeededModules.py -s /path/to/sources -j path/to/vtk_build/modules.json`
237 
238 ## Testing
239 
240 There is some support for testing in the module system, but it is not as
241 comprehensive as the build side. This is because testing infrastructure and
242 strategies vary wildly between projects. Rather than trying to handle the
243 minimum baseline of any plausible testing infrastructure or framework, the
244 module system merely handles dependency management for testing and entering a
245 subdirectory with the tests.
246 
247 Modules may have `TEST_DEPENDS` and `TEST_OPTIONAL_DEPENDS` lists provided as
248 well. These modules are required or optionally used by the testing code for the
249 module.
250 
251 When scanning, the `ENABLE_TESTS` argument may be set to `ON`, `OFF`, `WANT`
252 (the default), or `DEFAULT`. Modules which appear in `TEST_DEPENDS` for the
253 module are affected by this setting.
254 
255  - `ON`: Modules required for testing are treated as required. Tests will be
256  enabled.
257  - `OFF`: Tests will not be enabled.
258  - `WANT`: If possible, `TEST_DEPENDS` modules will also be enabled if they are
259  not disabled in some other way.
260  - `DEFAULT`: Check when tests are checked whether all of `TEST_DEPENDS` are
261  available. If they are, enable testing for the module, otherwise skip it.
262 
263 The only guarantee for testing provided is that all modules in the
264 `TEST_DEPENDS` will be available before the testing is added and
265 `TEST_OPTIONAL_DEPENDS` are available if they'd be available at all (i.e., they
266 won't be made available later).
267 
268 Modules may also have `TEST_LABELS` set to ease labeling all tests for the
269 module. The module system itself does nothing with this other than set a global
270 property with the value. It is up to any test infrastructure used within the
271 module's CMake code to make use of the value.
272 
273 The tests for a module are expected to live in a subdirectory of the module code
274 itself. The name of this directory is given by the `TEST_DIRECTORY_NAME`
275 argument to the [vtk_module_build][] function. If the directory is available and
276 the module's testing is enabled, the module system will
277 [`add_subdirectory`][cmake-add_subdirectory] this directory at the appropriate
278 time. This is decoupled so that testing code can depend on modules that depend
279 on the module that is being tested and the same `TARGET ${dependency}` check can
280 be used for optional module dependencies.
281 
282 [cmake-add_subdirectory]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
283 
284 # Building modules
285 
286 After scanning is complete, [vtk_module_scan][] returns a list of modules and
287 kits to build in the variables given by the `PROVIDES_MODULES` and
288 `PROVIDES_KITS` arguments to it. It also provides lists of modules that were
289 found during scanning that were not scanned by that call. These are given back
290 in the variables passed to the `UNRECOGNIZED_MODULES` and `REQUIRES_MODULES`
291 variables.
292 
293 The `UNRECOGNIZED_MODULES` list contains modules passed to `REQUIRES_MODULES`
294 and `REJECT_MODULES` that were not found during the scan. This typically
295 indicates that the values passed to those arguments were not constructed
296 properly. However, it may also mean that they should be passed on to further
297 scans if they may be found elsewhere. Callers should handle the variable as
298 necessary for their use case.
299 
300 The `REQUIRES_MODULES` are modules that were named as dependencies of the
301 scanned modules and need to be provided in some way before building the provided
302 modules (the build step will require that they exist when it tries to build the
303 modules which required them). These can be passed on to future
304 `REQUIRES_MODULES` arguments in future scans or used to error out depending on
305 the use case of the caller.
306 
307 When using [vtk_module_build][], the `PROVIDES_MODULES` and `PROVIDES_KITS` from
308 a single scan should be passed together. Multiple scans may be built together as
309 well if they all use the same build parameters as each other.
310 
311 ## Build-time parameters
312 
313 The [vtk_module_build][] function is where the decision to build with or without
314 kits is decided through the `BUILD_WITH_KITS` option. Only if this is set will
315 kits be built for this set of modules.
316 
317 The decision to default third party modules to using an external or internal
318 copy (where such a decision is possible) is done using the `USE_EXTERNAL`
319 argument.
320 
321 Where build artifacts end up in the build tree are left to CMake's typical
322 variables for controlling these locations:
323 
324  - [`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`][cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]
325  - [`CMAKE_LIBRARY_OUTPUT_DIRECTORY`][cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]
326  - [`CMAKE_RUNTIME_OUTPUT_DIRECTORY`][cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]
327 
328 The defaults for these place outputs into the binary directory where the targets
329 were added. The module system will set these to be sensible for itself if they
330 are not already set, but it is recommended to set these at the top-level so that
331 targets not built under [vtk_module_build][] also end up at a sensible location.
332 
333 [cmake-CMAKE_ARCHIVE_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.html
334 [cmake-CMAKE_LIBRARY_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.html
335 [cmake-CMAKE_RUNTIME_OUTPUT_DIRECTORY]: https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html
336 
337 ## Library parameters
338 
339 When building libraries, it is sometimes useful to have top-level control of
340 library metadata. For example, VTK suffixes its library filenames with a version
341 number. The variables that control this include:
342 
343  - `LIBRARY_NAME_SUFFIX`: If non-empty, all libraries and executable names will
344  be suffixed with this value prefixed with a hyphen (e.g., a suffix of `foo`
345  will make `Namespace::Target`'s library be named `Target-foo` or, if the
346  module sets its `LIBRARY_NAME` to `nsTarget`, `nsTarget-foo`).
347  - `VERSION`: Controls the [`VERSION`][cmake-VERSION] property for all library
348  modules.
349  - `SOVERSION`: Controls the [`SOVERSION`][cmake-SOVERSION] property for all
350  library modules.
351 
352 [cmake-VERSION]: https://cmake.org/cmake/help/latest/prop_tgt/VERSION.html
353 [cmake-SOVERSION]: https://cmake.org/cmake/help/latest/prop_tgt/SOVERSION.html
354 
355 ## Installation support
356 
357 [vtk_module_build][] also offers arguments to aid in installing module
358 artifacts. These include destinations for pieces that are installed, CMake
359 packaging controls, and components to use for the installations.
360 
361 A number of destinations control arguments are provided:
362 
363  - `ARCHIVE_DESTINATION`
364  - `HEADERS_DESTINATION`
365  - `LIBRARY_DESTINATION`
366  - `RUNTIME_DESTINATION`
367  - `CMAKE_DESTINATION`
368  - `LICENSE_DESTINATION`
369  - `HIERARCHY_DESTINATION`
370 
371 See the API documentation for default values for each which are based on
372 [`GNUInstallDirs`][GNUInstallDirs] variables. Note that all installation
373 destinations are expected to be relative paths. This is because the conveniences
374 provided by the module system are all assumed to be installed to a single prefix
375 ([`CMAKE_INSTALL_PREFIX`][cmake-CMAKE_INSTALL_PREFIX]) and placed underneath it.
376 
377 Suppression of header installation is provided via the `INSTALL_HEADERS`
378 argument to [vtk_module_build][]. Setting this to `OFF` will suppress the
379 installation of:
380 
381  - headers
382  - CMake package files
383  - hierarchy files (since their use requires headers)
384 
385 Basically, suppression of headers means that SDK components for the built
386 modules are not available in the install tree.
387 
388 Components for the installation are provided via the `HEADERS_COMPONENT` and
389 `TARGETS_COMPONENT` arguments. The former is used for SDK bits and the latter
390 for runtime bits (libraries, executables, etc.).
391 
392 For CMake package installation, the `PACKAGE` and `INSTALL_EXPORT` arguments are
393 available. The former controls the names used by the CMake files created by the
394 module system while the former is the export set to use for the member modules
395 when creating those CMake files. Non-module targets may also exist in this
396 export set when [vtk_module_build][] is called, but the export set is considered
397 "closed" afterwards since it has already been exported (if `INSTALL_HEADERS` is
398 true).
399 
400 [cmake-CMAKE_INSTALL_PREFIX]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html
401 
402 ## Test data information
403 
404 The directory that is looked for in each module is specified by using the
405 `TEST_DIRECTORY_NAME` argument. If it is set to the value of `NONE`, no testing
406 directories will be searched for. It defaults to `Testing` due to VTK's
407 conventions.
408 
409 The module system, due to VTK's usage of it, has convenience parameters for
410 controlling the [`ExternalData`][ExternalData] module that is available to
411 testing infrastructure. These include:
412 
413  - `TEST_DATA_TARGET`: The data target to use for tests.
414  - `TEST_INPUT_DATA_DIRECTORY`: Where `ExternalData` should look for data
415  files.
416  - `TEST_OUTPUT_DATA_DIRECTORY`: Where `ExternalData` should place the
417  downloaded data files.
418  - `TEST_OUTPUT_DIRECTORY`: Where tests should place output files.
419 
420 Each is provided in the testing subdirectory as `_vtk_build_${name}`, so the
421 `TEST_DATA_TARGET` argument is available as `_vtk_build_TEST_DATA_TARGET`.
422 
423 [ExternalData]: https://cmake.org/cmake/help/latest/module/ExternalData.html
424 
425 # Building a module
426 
427 Building a module is basically the same as a normal CMake library or executable,
428 but is wrapped to use arguments to facilitate wrapping, exporting, and
429 installation of the tools as well.
430 
431 There are two main functions provided for this:
432 
433  - [vtk_module_add_module][]
434  - [vtk_module_add_executable][]
435 
436 The former creates a library for the module being built while the latter can
437 create an executable for the module itself or create utility executable
438 associated with the module. The module system requires that the `CMakeLists.txt`
439 for a module create a target with the name of the module. In the case of
440 `INTERFACE` modules, it suffices to create the module manually in many cases.
441 
442 ## Libraries
443 
444 Most modules end up being libraries that can be linked against by other
445 libraries. Due to cross-platform support generally being a good thing, the
446 `EXPORT_MACRO_PREFIX` argument is provided to specify the prefix for macro names
447 to be used by [`GenerateExportHeader`][GenerateExportHeader]. By default, the
448 `LIBRARY_NAME` for the module is transformed to uppercase to make the prefix.
449 
450 Some modules may need to add additional information to the library name that
451 will be used that is not statically know and depends on other environmental
452 settings. The `LIBRARY_NAME_SUFFIX` may be specified to add an additional suffix
453 to the `LIBRARY_NAME` for the module. The [vtk_module_build][]
454 `LIBRARY_NAME_SUFFIX` argument value will be appended to this name as well.
455 
456 Normally, libraries are built according to the
457 [`BUILD_SHARED_LIBS`][BUILD_SHARED_LIBS] variable, however, some modules may
458 need to be built statically all the time. The `FORCE_STATIC` parameter exists
459 for this purpose. This is generally only necessary if the module is in some
460 other must-be-static library's dependency tree (which may happen for a number of
461 reasons). It is not an escape hatch for general usage; it is there because use
462 cases which only support static libraries (even in a shared build) exist.
463 
464 If a library module is part of a kit and it is being built via the
465 [vtk_module_build][] `BUILD_WITH_KITS` argument, it will be built as an
466 [`OBJECT`][cmake-OBJECT] library and the kit machinery in [vtk_module_build][]
467 will create the resulting kit library artifact.
468 
469 Header-only modules must pass `HEADER_ONLY` to create an `INTERFACE` library
470 instead of expecting a linkable artifact.
471 
472 @note `HEADER_ONLY` modules which are part of kits is currently untested. This
473 should be supported, but might not work at the moment.
474 
475 [cmake-OBJECT]: https://cmake.org/cmake/help/latest/command/add_library.html
476 [vtk_module_add_module]: @ref vtk_module_add_module
477 [vtk_module_add_executable]: @ref vtk_module_add_executable
478 [GenerateExportHeader]: https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html
479 
480 ### Source listing
481 
482 Instead of using CMake's "all sources in a single list" pattern for
483 `add_library`, [vtk_module_add_module][] classifies its source files explicitly:
484 
485  - `SOURCES`
486  - `HEADERS`
487  - `TEMPLATES`
488 
489 The `HEADERS` and `TEMPLATES` are installed into the `HEADERS_DESTINATION`
490 specified to [vtk_module_build][] and may be added to a subdirectory of this
491 destination by using the `HEADERS_SUBDIR` argument. Note that the structure of
492 the header paths passed is ignored. If more structure is required from the
493 installed header layout, [vtk_module_install_headers][] should be used.
494 
495 Files passed via `HEADERS` are treated as the API interface to the code of the
496 module and are added to properties so that [language wrappers](#wrapping) can
497 discover the API of the module.
498 
499 @note Only headers passed via `HEADERS` are eligible for wrapping; those
500 installed via [vtk_module_install_headers][] are not. This is a known limitation
501 at the moment.
502 
503 There are also private variations for `HEADERS` and `TEMPLATES` named
504 `PRIVATE_HEADERS` and `PRIVATE_TEMPLATES` respectively. These are never
505 installed nor exposed to wrapping mechanisms.
506 
507 There are also a couple of convenience parameters that use VTK's file naming
508 conventions to ease usage. These include:
509 
510  - `CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES` and
511  `<class>.h` to `HEADERS`.
512  - `TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
513  `TEMPLATES` and `<class>.h` to `HEADERS`.
514  - `PRIVATE_CLASSES`: For each value `<class>`, adds `<class>.cxx` to `SOURCES`
515  and `<class>.h` to `PRIVATE_HEADERS`.
516  - `PRIVATE_TEMPLATE_CLASSES`: For each value `<class>`, adds `<class>.txx` to
517  `PRIVATE_TEMPLATES` and `<class>.h` to `PRIVATE_HEADERS`.
518 
519 [vtk_module_install_headers]: @ref vtk_module_install_headers
520 
521 ## Executables
522 
523 Executables may be created using [vtk_module_add_executable][]. The first
524 argument is the name of the executable to build. Since the scanning phase does
525 not know what kind of target will be created for each module (and it may change
526 based on other configuration values), an executable module which claims it is
527 part of a kit raises an error since this is not possible to do.
528 
529 For modules that are executables using this function, the metadata from the
530 module information is used to set the relevant properties. The module
531 dependencies are also automatically linked in the same way as a library module
532 would do so.
533 
534 For utility executables, `NO_INSTALL` may be passed to keep it within the build
535 tree. It will not be available to consumers of the project. If the name of the
536 executable is different from the target name, `BASENAME` may be used to change
537 the executable's name.
538 
539 ## Module APIs
540 
541 All of CMake's `target_` function calls have [analogues][module-as-target] for
542 modules. This is primarily due to the kits feature which causes the target name
543 created by the module system that is required to use the `target_` functions
544 dependent on whether the module is a member of a kit and kits are being built.
545 The CMake version of the function and the module API analogue (as well as
546 differences, if any) is:
547 
548  - [set_target_properties][cmake-set_target_properties] becomes
549  [vtk_module_set_properties][]
550  - [set_property(TARGET)][cmake-set_property] becomes
551  [vtk_module_set_property][]
552  - [get_property(TARGET)][cmake-get_property] becomes
553  [vtk_module_get_property][]
554  - [add_dependencies][cmake-add_dependencies] becomes [vtk_module_depend][]
555  - [target_include_directories][cmake-target_include_directories] becomes
556  [vtk_module_include][]
557  - [target_compile_definitions][cmake-target_compile_definitions] becomes
558  [vtk_module_definitions][]
559  - [target_compile_options][cmake-target_compile_options] becomes
560  [vtk_module_compile_options][]
561  - [target_compile_features][cmake-target_compile_features] becomes
562  [vtk_module_compile_features][]
563  - [target_link_libraries][cmake-target_link_libraries] becomes
564  [vtk_module_link][]: When kits are enabled, any `PRIVATE` links are
565  forwarded to the kit itself. This necessitates making all of these targets
566  globally scoped rather than locally scoped.
567  - [target_link_options][cmake-target_link_options] becomes
568  [vtk_module_link_options][]
569 
570 [module-as-target]: @ref module-target-functions
571 [cmake-set_target_properties]: https://cmake.org/cmake/help/latest/command/set_target_properties.html
572 [cmake-set_property]: https://cmake.org/cmake/help/latest/command/set_property.html
573 [cmake-get_property]: https://cmake.org/cmake/help/latest/command/get_property.html
574 [cmake-add_dependencies]: https://cmake.org/cmake/help/latest/command/add_dependencies.html
575 [cmake-target_include_directories]: https://cmake.org/cmake/help/latest/command/target_include_directories.html
576 [cmake-target_compile_definitions]: https://cmake.org/cmake/help/latest/command/target_compile_definitions.html
577 [cmake-target_compile_options]: https://cmake.org/cmake/help/latest/command/target_compile_options.html
578 [cmake-target_compile_features]: https://cmake.org/cmake/help/latest/command/target_compile_features.html
579 [cmake-target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html
580 [cmake-target_link_options]: https://cmake.org/cmake/help/latest/command/target_link_options.html
581 [vtk_module_set_properties]: @ref vtk_module_set_properties
582 [vtk_module_set_property]: @ref vtk_module_set_property
583 [vtk_module_get_property]: @ref vtk_module_get_property
584 [vtk_module_depend]: @ref vtk_module_depend
585 [vtk_module_include]: @ref vtk_module_include
586 [vtk_module_definitions]: @ref vtk_module_definitions
587 [vtk_module_compile_options]: @ref vtk_module_compile_options
588 [vtk_module_compile_features]: @ref vtk_module_compile_features
589 [vtk_module_link]: @ref vtk_module_link
590 [vtk_module_link_options]: @ref vtk_module_link_options
591 
592 # Packaging support
593 
594 Getting installed packages to work for CMake is, unfortunately, not trivial. The
595 module system provides some support for helping with this, but it does place
596 some extra constraints on the project so that some assumptions that vastly
597 simplify the process can be made.
598 
599 ## Assumptions
600 
601 The main assumption is that all modules passed to a single [vtk_module_build][]
602 have the same CMake namespace (the part up to and including the `::`, if any,
603 in a module name. For exporting dependencies, that namespace matches the
604 `PACKAGE` argument for [vtk_module_build][]. These are done so that the
605 generated code can use
606 [`CMAKE_FIND_PACKAGE_NAME`][cmake-CMAKE_FIND_PACKAGE_NAME] variable can be
607 used to discover information about the package that is being found.
608 
609 The package support also assumes that all modules may be queried using
610 `COMPONENTS` and `OPTIONAL_COMPONENTS` and that the component name for a module
611 corresponds to the name of a module without the namespace.
612 
613 These rules basically mean that a module named `Namespace::Target` will be found
614 using `find_package(Namespace)`, that `COMPONENTS Target` may be passed to
615 ensure that that module exists, and `OPTIONAL_COMPONENTS Target` may be passed
616 to allow the component to not exist while not failing the main
617 [`find_package`][cmake-find_package] call.
618 
619 [cmake-CMAKE_FIND_PACKAGE_NAME]: https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NAME.html
620 
621 ## Creating a full package
622 
623 The module system provides no support for the top-level file that is used by
624 [`find_package`][cmake-find_package]. This is because this logic is highly
625 project-specific and hard to generalize in a useful way. Instead, files are
626 generated which should be included from the main file.
627 
628 Here, the list of files generated are based on the `PACKAGE` argument passed to
629 [vtk_module_build][]:
630 
631  - `<PACKAGE>-targets.cmake`: The CMake-generated export file for the targets
632  in the `INSTALL_EXPORT`.
633  - `<PACKAGE>-vtk-module-properties.cmake`: Properties for the targets exported
634  into the build.
635 
636 The module properties file must be included after the targets file so that they
637 exist when it tries to add properties to the imported targets.
638 
639 ## External dependencies
640 
641 Since the module system is heavily skewed towards using imported targets, these
642 targets show up by name in the [`find_package`][cmake-find_package] of the
643 project as well. This means that these external projects need to be found to
644 recreate their imported targets at that time. To this end, there is the
645 [vtk_module_export_find_packages][] function. This function writes a file named
646 according to its `FILE_NAME` argument and place it in the build and install
647 trees according to its `CMAKE_DESTINATION` argument.
648 
649 This file will be populated with logic to determine whether third party packages
650 found using [vtk_module_find_package][] are required during the
651 [`find_package`][cmake-find_package] of the package or not. It will forward
652 `REQUIRED` and `QUIET` parameters to other [`find_package`][cmake-find_package]
653 calls as necessary based on the `REQUIRED` and `QUIET` flags for the package
654 and whether that call is involved in a non-optional `COMPONENT` (a
655 component-less [`find_package`][cmake-find_package] call is assumed to mean
656 "all components").
657 
658 This file should be included after the `<PACKAGE>-vtk-module-properties.cmake`
659 file generated by the [vtk_module_build][] call so that it can use the module
660 dependency information set via that file.
661 
662 After this file is included, for each component that it checks, it will set
663 `${CMAKE_FIND_PACKAGE_NAME}_<component>_FOUND` to 0 if it is not valid and
664 append a reason to `${CMAKE_FIND_PACKAGE_NAME}_<component>_NOT_FOUND_MESSAGE`
665 so that the package can collate the reason why things are not available.
666 
667 [vtk_module_export_find_packages]: @ref vtk_module_export_find_packages
668 [vtk_module_find_package]: @ref vtk_module_find_package
669 
670 ## Setting the `_FOUND` variable
671 
672 The module system does not currently help in determining the top-level
673 `${CMAKE_FIND_PACKAGE_NAME}_FOUND` variable based on the results of the
674 components that were requested and the status of dependent packages. This may be
675 provided at some point, but there has not currently been enough experience to
676 determine what patterns are available for factoring it out as a utility
677 function.
678 
679 The general pattern should be to go through the list of components requested,
680 determine whether targets for those components exist. Then for each found
681 component, use the module dependency information to ensure that all targets in
682 the dependency trees are found (propagating not-found statuses through the
683 dependency tree). The `${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE` should be
684 built up based on the reasons the [`find_package`][cmake-find_package] call did
685 not work based on these discoveries.
686 
687 This is the process for modules in a package, but packages may contain
688 non-module components, and it is hard for the module system to provide support
689 for them, so they are not attempted. See the CMake documentation for more
690 details about [creating a package configuration][cmake-create-package-config].
691 
692 [cmake-create-package-config]: https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#creating-a-package-configuration-file
693 
694 # Advanced topics
695 
696 There are a number of advanced features provided by the module system that are
697 not normally required in a simple project.
698 
699 ## Kits
700 
701 Kits are described in [vtk.kit][] files which act much like [vtk.module][]
702 files. However, they only have `NAME`, `LIBRARY_NAME`, and `DESCRIPTION` fields.
703 These all act just like they do in the `vtk.module` context. These files may
704 either be passed manually to [vtk_module_scan][] or discovered by using the
705 [vtk_module_find_kits][] convenience function.
706 
707 Before a module may be a member of a kit, a [vtk.kit][] must declare it and be
708 scanned at the same time. This means that kits may only contain modules that are
709 scanned with them and cannot be extended later nor may kits be made of modules
710 that they do not know about.
711 
712 [vtk.kit]: @ref module-parse-kit
713 [vtk_module_find_kits]: @ref vtk_module_find_kits
714 
715 ### Requirements
716 
717 In order to actually use kits, CMake 3.12 is necessary in order to do the
718 [`OBJECT`][cmake-OBJECT] library manipulations done behind the scenes to make it
719 Just Work. 3.8 is still the minimum version for using a project that is built
720 with kits however. This is only checked when kits are actually in use, so
721 projects requiring older CMake versions as their minimum version may still
722 provide kits so that users with newer CMake versions can use them.
723 
724 Kits create a single library on disk, but the usage requirements of the modules
725 should still be the same (except for that which is inherently required to be
726 different by combining libraries). So include directories, compile definitions,
727 and other usage requirements should not leak from other modules that are members
728 of the same kit.
729 
730 <a name="autoinit"></a>
731 ## Autoinit
732 
733 The module system supports a mechanism for triggering static code construction
734 for modules which require it. This cannot be done through normal CMake usage
735 requirements because the requirements are intersectional. For example, a module
736 `F` having a factory where module `I` provides an implementation for it means
737 that a target linking to both `F` and `I` needs to ensure that `I` registers its
738 implementation to the factory code. There is no such support in CMake and due to
739 the complexities and code generation involved with this support, it is unlikely
740 to exist.
741 
742 Code which uses modules may call the [vtk_module_autoinit][] function to use
743 this functionality. The list of modules passed to the function are used to
744 compute the defines necessary to trigger the registration to factories when
745 necessary.
746 
747 For details on the implementation of the autoinit system, please see
748 [the relevant section][autoinit] in the API documentation.
749 
750 [vtk_module_autoinit]: @ref vtk_module_autoinit
751 [autoinit]: @ref module-autoinit
752 
753 <a name="wrapping"></a>
754 ## Wrapping
755 
756 VTK comes with support for wrapping its classes into other languages.
757 Currently, VTK supports wrapping its classes for use in the Python and Java
758 languages. In order to wrap a set of modules for a language, a separate
759 function is used for each language.
760 
761 All languages read the headers of classes with a `__VTK_WRAP__` preprocessor
762 definition defined. This may be used to hide methods or other details from the
763 wrapping code if wanted.
764 
765 ### Python
766 
767 For Python, the [vtk_module_wrap_python][] function must be used. This function
768 takes a list of modules in its `MODULES` argument and creates Python modules
769 for use under the `PYTHON_PACKAGE` package. No `__init__.py` for this package
770 is created automatically and must be provided in some other way.
771 
772 A target named by the `TARGET` argument is created and installed. This target
773 may be linked to in order to be able to import static Python modules. In this
774 case, a header and function named according to the basename of `TARGET` (e.g.,
775 `VTK::PythonWrapped` has a basename of `PythonWrapped`) must be used. The
776 header is named `<TARGET_BASENAME>.h` and the function which adds the wrapped
777 modules to the static import table is `<void TARGET_BASENAME>_load()`. This
778 function is also created in shared builds, but does nothing so that it may
779 always be called in static or shared builds.
780 
781 The modules will be installed under the `MODULE_DESTINATION` given to the
782 function into the `PYTHON_PACKAGE` directory needed for it. The
783 [vtk_module_python_default_destination][] function is used to determine a
784 default if one is not passed.
785 
786 The Python wrappers define a `__VTK_WRAP_PYTHON__` preprocessor definition when
787 reading code which may be used to hide methods or other details from the Python
788 wrapping code.
789 
790 [vtk_module_wrap_python]: @ref vtk_module_wrap_python
791 [vtk_module_python_default_destination]: @ref vtk_module_python_default_destination
792 
793 ### Java
794 
795 For Java, the [vtk_module_wrap_java][] function must be used. This function
796 creates Java sources for classes in the modules passed in its `MODULES`
797 argument. The sources are written to a `JAVA_OUTPUT` directory. These then can
798 be compiled by CMake normally.
799 
800 For this purpose, there are `<MODULE>Java` targets which contain a
801 `_vtk_module_java_files` properties containing a list of `.java` sources
802 generated for the given module. There is also a `<MODULE>Java-java-sources`
803 target which may be depended upon if just the source generation needs to used
804 in an [`add_dependencies`][cmake-add_dependencies] call.
805 
806 The Java wrappers define a `__VTK_WRAP_JAVA__` preprocessor definition when
807 reading code which may be used to hide methods or other details from the Java
808 wrapping code.
809 
810 [vtk_module_wrap_java]: @ref vtk_module_wrap_java
811 
812 ### Hierarchy files
813 
814 Hierarchy files are used by the language wrapper tools to know the class
815 inheritance for classes within a module. Each module has a hierarchy file
816 associated with it. The path to a module's hierarchy file is stored in its
817 `hierarchy` module property.
818 
819 ## Third party
820 
821 The module system has support for representing third party modules in its
822 build. These may be built as part of the project or represented using other
823 mechanisms (usually [`find_package`][cmake-find_package] and a set of imported
824 targets from it).
825 
826 The primary API is [vtk_module_third_party][] which creates a
827 `VTK_MODULE_USE_EXTERNAL_Namespace_Target` option for the module to switch
828 between an internal and external source for the third party code. This value
829 defaults to the setting of the `USE_EXTERNAL` argument for the calling
830 [vtk_module_build][] function. Arguments passed under the `INTERNAL` and
831 `EXTERNAL` arguments to this command are then passed on to
832 [vtk_module_third_party_internal][] or [vtk_module_third_party_external][],
833 respectively, depending on the `VTK_MODULE_USE_EXTERNAL_Namespace_Target`
834 option.
835 
836 Note that third party modules (marked as such by adding the `THIRD_PARTY`
837 keyword to a `vtk.module` file) may not be part of a kit, be wrapped, or
838 participate in autoinit.
839 
840 [vtk_module_third_party]: @ref vtk_module_third_party
841 [vtk_module_third_party_internal]: @ref vtk_module_third_party_internal
842 [vtk_module_third_party_external]: @ref vtk_module_third_party_external
843 
844 ### External third party modules
845 
846 External modules are found using CMake's [`find_package`][cmake-find_package]
847 mechanism. In addition to the arguments supported by
848 [vtk_module_find_package][] (except `PRIVATE`), information about the found
849 package is used to construct a module target which represents the third party
850 package. The preferred mechanism is to give a list of imported targets to the
851 `LIBRARIES` argument. These will be added to the `INTERFACE` of the module and
852 provide the third party package for use within the module system.
853 
854 If imported targets are not available (they really should be created if not),
855 variable names may be passed to `INCLUDE_DIRS`, `LIBRARIES`, and `DEFINITIONS`
856 to create the module interface.
857 
858 In addition, any variables which should be forwarded from the package to the
859 rest of the build may be specified using the `USE_VARIABLES` argument.
860 
861 The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
862 module target which includes the "standard" module include directories to.
863 Basically, the source and binary directories of the module.
864 
865 ### Internal third party modules
866 
867 Internal modules are those that may be built as part of the build. These should
868 ideally specify a set of `LICENSE_FILES` indicating the license status of the
869 third party code. These files will be installed along with the third party
870 package to aid in any licensing requirements of the code. It is also
871 recommended to set the `VERSION` argument so that it is known what version of
872 the code is provided at a glance.
873 
874 By default, the `LIBRARY_NAME` of the module is used as the name of the
875 subdirectory to include, but this may be changed by using the `SUBDIRECTORY`
876 argument.
877 
878 Header-only third party modules may be indicated by using the `HEADER_ONLY`
879 argument. Modules which represent multiple libraries at once from a project may
880 use the `INTERFACE` argument.
881 
882 The `STANDARD_INCLUDE_DIRS` argument creates an include interface for the
883 module target which includes the "standard" module include directories to.
884 Basically, the source and binary directories of the module. A subdirectory may
885 be used by setting the `HEADERS_SUBDIR` option. It is implied for
886 `HEADERS_ONLY` third party modules.
887 
888 After the subdirectory is added a target with the module's name must exist.
889 However, a target is automatically created if it is `HEADERS_ONLY`.
890 
891 #### Properly shipping internal third party code
892 
893 There are many things that really should be done to ship internal third party
894 code (also known as vendoring) properly. The issue is mainly that the internal
895 code may conflict with other code bringing in another copy of the same package
896 into a process. Most platforms do not behave well in this situation.
897 
898 In order to avoid conflicts at every level possible, a process called "name
899 mangling" should be performed. A non-exhaustive list of name manglings that
900 must be done to fully handle this case includes:
901 
902  - moving headers to a subdirectory (to avoid compilations from finding
903  incompatible headers);
904  - changing the library name (to avoid DLL lookups from finding incompatible
905  copies); and
906  - mangling symbols (to avoid symbol lookup from confusing two copies in the
907  same process).
908 
909 Some projects may need further work like editing CMake APIs or the like to be
910 mangled as well.
911 
912 Moving headers and changing library names is fairly straightforward by editing
913 CMake code. Mangling symbols usually involves creating a header which has a
914 `#define` for each public symbol to change its name at runtime to be distinct
915 from another copy that may end up existing in the same process from another
916 project.
917 
918 Typically, a header needs to be created at the module level which hides the
919 differences between third party code which may or may not be provided by an
920 external package. In this case, it is recommended that code using the third
921 party module use unmangled names and let the module interface and mangling
922 headers handle the mangling at that level.
923 
924 ## Debugging
925 
926 The module system can output debugging information about its inner workings by
927 using the `_vtk_module_log` variable. This variable is a list of "domains" to
928 log about, or the special `ALL` value causes all domains to log output. The
929 following domains are used in the internals of the module system:
930 
931  - `kit`: discovery and membership of kits
932  - `module`: discovery and `CONDITION` results of modules
933  - `enable`: resolution of the enable status of modules
934  - `provide`: determination of module provision
935  - `building`: when building a module occurs
936  - `testing`: missing test dependencies
937 
938 It is encouraged that projects expose user-friendly flags to control logging
939 rather than exposing `_vtk_module_log` directly.
940 
941 ## Control variables
942 
943 These variables do not follow the API convention and are used if set:
944 
945  - `_vtk_module_warnings`: If enabled, "strict" warnings are generated. These
946  are not strictly problems, but may be used as linting for improving usage of
947  the module system.
948  - `_vtk_module_log`: A list of "domains" to output debugging information.
949  - `_vtk_module_group_default_${group}`: used to set a non-`DEFAULT` default
950  for group settings.
951 
952 Some mechanisms use global properties instead:
953 
954  - `_vtk_module_autoinit_include`: The file that needs to be included in order
955  to make the `VTK_MODULE_AUTOINIT` symbol available for use in the
956  [autoinit][] support.