docs: add module migration docs

Fixes: #17696

Documentation/Doxygen/ModuleMigration.md

+# Module Migration
+
+VTK 8.2 and older contained a module system which was based on variables and
+informed CMake's migration to target-based properties and interactions. This
+was incompatible with the way VTK ended up doing it. With VTK 9, its module
+system has been reworked to use CMake's targets.
+
+This document may be used as a guide to updating code using old VTK modules into
+code using new VTK modules.
+
+## Using modules
+
+If your project is just using VTK's modules and not declaring any of your own
+modules, porting involves a few changes to the way VTK is found and used.
+
+The old module system made variables available for using VTK.
+
+~~~{.cmake}
+find_package(VTK
+  REQUIRED
+  COMPONENTS
+    vtkCommonCore
+    vtkRenderingOpenGL2)
+include(${VTK_USE_FILE})
+
+add_library(usesvtk ...)
+target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
+target_include_directories(usesvtk ${visibility} ${VTK_INCLUDE_DIRS})
+
+# Pass any VTK autoinit defines to the target.
+target_compile_definitions(usesvtk PRIVATE ${VTK_DEFINITIONS})
+~~~
+
+This causes problems if VTK is found multiple times within a source tree with
+different components. The new pattern is:
+
+~~~{.cmake}
+find_package(VTK
+  #9.0 # Compatibility support is not provided if 9.0 is requested.
+  REQUIRED
+  COMPONENTS
+    # Old component names are OK, but deprecated.
+    #vtkCommonCore
+    #vtkRenderingOpenGL2
+    # New names reflect the target names in use.
+    CommonCore
+    RenderingOpenGL2)
+# No longer needed; warns or errors depending on the version requested when
+# finding VTK.
+#include(${VTK_USE_FILE})
+
+add_library(usesvtk ...)
+# VTK_LIBRARIES is provided for compatibility, but not recommended.
+#target_link_libraries(usesvtk ${visibility} ${VTK_LIBRARIES})
+target_link_libraries(usesvtk ${visibility} VTK::CommonCore VTK::RenderingOpenGL2)
+
+# Rather than defining a single `VTK_DEFINITIONS` for use by all relevant
+# targets, the definitions are made as needed with the exact set needed for the
+# listed modules.
+vtk_module_autoinit(
+  TARGETS usesvtk
+  #MODULES ${VTK_LIBRARIES} # Again, works, but is not recommended.
+  MODULES VTK::CommonCore VTK::RenderingOpenGL2)
+~~~
+
+## Module declaration
+
+The old module system had CMake code declare modules in `module.cmake` files.
+This allowed logic and other things to happen within them which could cause
+module dependencies to be hard to follow. The new module system now provides
+facilities for disabling modules in certain configurations (using `CONDITION`)
+and for optionally depending on modules (using `OPTIONAL_DEPENDS`).
+
+~~~{.cmake}
+if (NOT SOME_OPTION)
+  set(depends)
+  if (SOME_OTHER_OPTION)
+    list(APPEND depends vtkSomeDep)
+  endif ()
+  vtk_module(vtkModuleName
+    GROUPS
+      # groups the module belongs to
+    KIT
+      # the kit the module belongs to
+    IMPLEMENTS
+      # modules containing vtkObjectFactory instances that are implemented here
+    DEPENDS
+      # public dependencies
+      #${depends} # no analogy in the new system
+    PRIVATE_DEPENDS
+      # private dependencies
+      ${depends}
+    COMPILE_DEPENDS
+      # modules which must be built before this one but which are not actually
+      # linked.
+    TEST_DEPENDS
+      # test dependencies
+    TEST_OPTIONAL_DEPENDS
+      # optional test dependencies
+      ${depends}
+    #EXCLUDE_FROM_WRAPPING
+      # present for modules which cannot be wrapped
+  )
+endif ()
+~~~
+
+This is now replaced with a declarative file named `vtk.module`. This file is
+not CMake code and is instead parsed as an argument list in CMake (variable
+expansions are also not allowed). The above example would translate into:
+
+~~~{.cmake}
+MODULE
+  vtkModuleName
+CONDITION
+  SOME_OPTION
+GROUPS
+  # groups the module belongs to
+KIT
+  # the kit the module belongs to
+#IMPLEMENTABLE # Implicit in the old build system. Now explicit.
+IMPLEMENTS
+  # modules containing vtkObjectFactory instances that are implemented here
+DEPENDS
+  # public dependencies
+PRIVATE_DEPENDS
+  # private dependencies
+OPTIONAL_DEPENDS
+  vtkSomeDep
+ORDER_DEPENDS
+  # modules which must be built before this one but which are not actually
+  # linked.
+TEST_DEPENDS
+  # test dependencies
+TEST_OPTIONAL_DEPENDS
+  # optional test dependencies
+  vtkSomeDep
+#EXCLUDE_WRAP
+  # present for modules which cannot be wrapped
+~~~
+
+Modules may also now be provided by the current project or by an external
+project found by `find_package` as well.
+
+## Declaring sources
+
+Sources used to be listed just as `.cxx` files. The module system would then
+search for a corresponding `.h` file, then add it to the list. Some source file
+properties could be used to control header-only or private headers.
+
+In this example, we have a module with the following sources:
+
+  - `vtkPublicClass.cxx` and `vtkPublicClass.h`: Public VTK class meant to be
+    wrapped and its header installed.
+  - `vtkPrivateClass.cxx` and `vtkPrivateClass.h`: Priavte VTK class not meant
+    for use outside of the module.
+  - `helper.cpp` and `helper.h`: Private API, but not following VTK's naming
+    conventions.
+  - `public_helper.cpp` and `public_helper.h`: Public API, but not following
+    VTK's naming conventions.
+  - `vtkImplSource.cxx`: A source file without a header.
+  - `public_header.h`: A public header without a source file.
+  - `template.tcc` and `template.h`: Public API, but not following VTK's naming
+    conventions.
+  - `private_template.tcc` and `private_template.h`: Private API, but not
+    following VTK's naming conventions.
+  - `vtkPublicTemplate.txx` and `vtkPublicTemplate.h`: Public template sources.
+    Wrapped and installed.
+  - `vtkPrivateTemplate.txx` and `vtkPrivateTemplate.h`: Private template
+    sources.
+  - `vtkOptional.cxx` and `vtkOptional.h`: Private API which requires an
+    optional dependency.
+
+The old module's way of building these sources is:
+
+~~~{.cmake}
+set(Module_SRCS
+  vtkPublicClass.cxx
+  vtkPrivateClass.cxx
+  helper.cpp
+  helper.h
+  public_helper.cpp
+  public_helper.h
+  public_header.h
+  vtkImplSource.cxx
+  vtkPublicTemplate.txx
+  vtkPrivateTemplate.txx
+  template.tcc # Not detected as a template, so not installed.
+  template.h
+  private_template.tcc
+  private_template.h
+)
+
+# Mark some files as only being header files.
+set_source_files_properties(
+  public_header.h
+  HEADER_FILE_ONLY
+)
+
+# Mark some headers as being private.
+set_source_files_properties(
+  helper.h
+  private_template.h
+  public_header.h
+  template.h
+  vtkImplSource.cxx # no header
+  vtkPrivateTemplate.h
+  PROPERTIES SKIP_HEADER_INSTALL 1
+)
+
+set(${vtk-module}_HDRS # Magic variable
+  public_helper.h
+  template.h
+  #helper.h # private headers just go ignored.
+)
+
+# Optional dependencies are detected through variables.
+if (Module_vtkSomeDep)
+  list(APPEND Module_SRCS
+    # Some optional file.
+    vtkOptional.cxx)
+endif ()
+
+vtk_module_library(vtkModuleName ${Module_SRCS})
+~~~
+
+While with the new system, source files are explicitly declared using argument
+parsing.
+
+~~~{.cmake}
+set(classes
+  vtkPublicClass)
+set(private_classes
+  vtkPrivateClass)
+set(sources
+  helper.cpp
+  public_helper.cpp
+  vtkImplSource.cxx)
+set(headers
+  public_header.h
+  public_helper.h
+  template.h)
+set(private_headers
+  helper.h
+  private_template.h)
+
+set(template_classes
+  vtkPublicTemplate)
+set(private_template_classes
+  vtkPrivateTemplate)
+set(templates
+  template.tcc)
+set(private_templates
+  private_template.tcc)
+
+# Optional dependencies are detected as targets.
+if (TARGET vtkSomeDep)
+  # Optional classes may not be public (though there's no way to actually
+  # enforce it, optional dependencies are always treated as private.
+  list(APPEND private_classes
+    vtkOptional)
+endif ()
+
+vtk_module_add_module(vtkModuleName
+  # File pairs which follow VTK's conventions. The headers will be wrapped and
+  # installed.
+  CLASSES ${classes}
+  # File pairs which follow VTK's conventions, but are not for use outside the
+  # module.
+  PRIVATE_CLASSES ${private_classes}
+  # Standalone sources (those without headers or which do not follow VTK's
+  # conventions).
+  SOURCES ${sources}
+  # Standalone headers (those without sources or which do not follow VTK's
+  # conventions). These will be installed.
+  HEADERS ${public_headers}
+  # Standalone headers (those without sources or which do not follow VTK's
+  # conventions), but are not for use outside the module.
+  PRIVATE_HEADERS ${private_headers}
+
+  # Templates are also supported.
+
+  # Template file pairs which follow VTK's conventions. Both files will be
+  # installed (only the headers will be wrapped).
+  TEMPLATE_CLASSES ${template_classes}
+  # Template file pairs which follow VTK's conventions, but are not for use
+  # outside the module.
+  PRIVATE_TEMPLATE_CLASSES ${private_template_classes}
+  # Standalone template files (those without headers or which do not follow
+  # VTK's conventions). These will be installed.
+  TEMPLATES ${templates}
+  # Standalone template files (those without headers or which do not follow
+  # VTK's conventions), but are not for use outside the module.
+  PRIVATE_TEMPLATES ${private_templates}
+)
+~~~
+
+Note that the arguments with `CLASSES` in their name expand to pairs of files
+with the `.h` and either `.cxx` or `.txx` extension based on whether it is a
+template or not. Projects not using this convention may use the `HEADERS`,
+`SOURCES`, and `TEMPLATES` arguments instead.
+
+## Object Factories
+
+Previously, object factories were made using implicit variable declaration magic
+behind the scenes. This is no longer the case and proper CMake APIs for them are
+available.
+
+~~~{.cmake}
+set(sources
+  vtkObjectFactoryImpl.cxx
+  # This path is made by `vtk_object_factory_configure` later.
+  "${CMAKE_CURRENT_BINARY_DIR}/${vtk-module}ObjectFactory.cxx")
+
+# Make a list of base classes we will be overriding.
+set(overrides vtkObjectFactoryBase)
+# Make a variable declaring what the override for the class is.
+set(vtk_module_vtkObjectFactoryBase_override "vtkObjectFactoryImpl")
+# Generate a source using the list of base classes overridden.
+vtk_object_factory_configure("${overrides}")
+
+vtk_module_library("${vtk-module}" "${sources}")
+~~~
+
+This is now handled using proper APIs instead of variable lookups.
+
+~~~{.cmake}
+set(classes
+  vtkObjectFactoryImpl)
+
+# Explicitly declare the override relationship.
+vtk_object_factory_declare(
+  BASE      vtkObjectFactoryBase
+  OVERRIDE  vtkObjectFactoryImpl)
+# Collects the set of declared overrides and writes out a source file.
+vtk_object_factory_declare(
+  # The path to the source is returned as a variable.
+  SOURCE_FILE factory_source
+  # As is its header file.
+  HEADER_FILE factory_header
+  # The export macro is now explicitly passed (instead of assumed based on the
+  # current module context).
+  EXPORT_MACRO MODULE_EXPORT)
+
+vtk_module_add_module(vtkModuleName
+  CLASSES ${classes}
+  SOURCES "${factory_source}"
+  PRIVATE_HEADERS "${factory_header}")
+~~~
+
+## Building a group of modules
+
+This was not well supported in the old module system. Basically, it involved
+setting up the source tree like VTK expects and then including the
+`vtkModuleTop` file. This is best just rewritten using the following CMake APIs:
+
+  - [vtk_module_find_modules]
+  - [vtk_module_find_kits]
+  - [vtk_module_scan]
+  - [vtk_module_build]
+
+[vtk_module_find_modules]: @ref vtk_module_find_modules
+[vtk_module_find_kits]: @ref vtk_module_find_kits
+[vtk_module_scan]: @ref vtk_module_scan
+[vtk_module_build]: @ref vtk_module_build