VTK/Remote Modules: Difference between revisions

From KitwarePublic
< VTK
Jump to navigationJump to search
(First cut)
 
 
(4 intermediate revisions by one other user not shown)
Line 3: Line 3:
= Purpose of Remote Modules =
= Purpose of Remote Modules =


The new modularization resulting from the ITKv4 effort provides a new level of
The new modularization resulting from the VTK6 effort provides a new level of
organization and extensibility to the toolkit.  A module that follows the
organization and extensibility to the toolkit.  A module that follows the
directory layout and has the required ITK modularization CMake content that is
directory layout and has the required VTK modularization CMake content that is
placed in one of the Module Groups of the repository will be automatically picked
placed in one of the Module Groups of the repository will be automatically picked
up and added to the build.
up and added to the build.
Line 13: Line 13:
in the main VTK repository has two benefits:
in the main VTK repository has two benefits:


Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.
Amalgamation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.
#  Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.
#  Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.


Good candidates for addition to the collection can be
Good candidates for addition to the remote module collection can be:


* VTK based code that has additional third-party dependencies not bundled with the toolkit.
* VTK based code that has additional third-party dependencies not bundled with the toolkit.
Line 41: Line 41:
At no time in the future should a module in the main repository depend on Remote module.
At no time in the future should a module in the main repository depend on Remote module.


= Procedure for Adding a Remote Module =
= Procedure for Adding a Remote Module to VTK=


Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].
Ideally, publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].
#  Submit a Gitlab patch that adds a file named Remote/<module name>.remote.cmake.  This file must have the following:
#  Submit a Gitlab patch that adds a file named Remote/<module name>.remote.cmake.  This file must have the following:
## Dashboard maintainer name and email in the comments.
## Dashboard maintainer name and email in the comments.
Line 51: Line 51:
### URL's describing the location and version of the code to download. The version should be a specific hash or tag (not "master").
### URL's describing the location and version of the code to download. The version should be a specific hash or tag (not "master").
#  Send a message to the VTK user mailing list with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission.
#  Send a message to the VTK user mailing list with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission.
= Creating a Remote Module =
The directory layout for a remote module is exactly the same as any VTK module.
The tree layout for a Remote Module is the same as the tree layout for any VTK module.
  ModuleName
    ''CMakeLists.txt''
    ''module.cmake''
    module source files
    Testing
        Cxx
        Python
        Tcl
        Data
          Baseline
== To create a Remote Module called '''Foo''' ==
* Create a git repository for the module, e.g. on github
* Clone the repository
  git clone https://github.com/yourname/'''Foo'''.git
* Make a directory '''Foo'''
* In '''Foo''', create a ''CMakeLists.txt'' file
  message(STATUS "'''Foo''': Building as a Remote VTK module")
  set(Module_SRCS
    ''vtkFoo1.cxx''
    ''vtkFoo2.cxx''
    )
  vtk_module_library('''Foo''' ${Module_SRCS})
* In '''Foo''', create ''module.cmake''
  set(DOCUMENTATION "This module contains '''Foo''' that illustrates vtk remote modules.")
  vtk_module( '''Foo'''
    DESCRIPTION
      "${DOCUMENTATION}"
    DEPENDS
      vtkCommonDataModel
      vtkFiltersHybrid
    TEST_DEPENDS
      vtkTestingCore
    KIT
      vtkRemote
  )
* Place any C++, Python or Tcl tests in the appropriate Testing/ directories.
* Place any Baseline images in Testing/Data/Baseline
* Add all files and directories to the local repository
  git add ''CMakeLists.txt module.cmake Foo1.cxx Foo2.cxx Testing''
* Commit the files and push the updated files to the git repository.
Note: If your module includes external data, you may need to manually upload the external data to data.kitware.com, see [https://public.kitware.com/pipermail/vtk-developers/2018-October/036431.html this thread].
== To add a Remote Module to a VTK build ==
Create a file '''''Foo'''.remote.cmake''
  #
  # '''Foo'''
  #
  vtk_fetch_module('''Foo'''
    "This module contains '''Foo''' that illustrates vtk remote modules"
    GIT_REPOSITORY https://github.com/yourname/'''Foo'''
    GIT_TAG most_recent_tag e.g. 0d324d0a7afbd2f7ddd79ae52640fddd15091b34
    )
* Put the '''''Foo'''.remote.cmake'' file in VTK/Remote
* In your VTK binary directory run cmake to enable the module
  cmake -DModule_'''Foo''':BOOL=ON ../VTK
* Then make VTK
  make
== To share the Remote Module with someone ==
Send them the '''''Foo'''.remote.cmake'' file and have them place it in VTK/Remote. Then they can
  cmake -DModule_''''''Foo'''''':BOOL=ON ../VTK
  make
If you make changes to your remote module, push the changes to your repository, update the '''''Foo'''.remote.cmake'' file with the new tag and notify your users to update their '''''Foo'''.remote.cmake''.
'''NOTE''': if your remote module is of general use, consider adding  '''''Foo'''.remote.cmake'' to VTK/Remote and generate a pull request to add it to the distributed VTK,
== Practical considerations when developing a Remote Module ==
When you first develop your Remote Module, you will be doing multiple edit/compile/test cycles.
* Clone your repository directly into your VTK/Remote source directory
* Set the tag in your '''Foo'''.remote.cmake
  GIT_TAG master
* Once your are satisfied with the module, push the changes to your repository.
* Set the tag in your '''Foo'''.remote.cmake
  GIT_TAG "the latest SHA or tag"

Latest revision as of 14:10, 19 October 2018

Remote modules are downloaded at CMake configuration time into the Remote module group, i.e. into the Remote directory of the repository tree. A Remote Module can be enabled by setting the target Module_<module name> CMake configuration variable to ON just like other VTK Modules.

Purpose of Remote Modules

The new modularization resulting from the VTK6 effort provides a new level of organization and extensibility to the toolkit. A module that follows the directory layout and has the required VTK modularization CMake content that is placed in one of the Module Groups of the repository will be automatically picked up and added to the build.

While individuals or organizations can work on their own private modules and optionally make these modules publicly available, the listing of Remote modules in the main VTK repository has two benefits:

  1. Amalgamation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.
  2. Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.

Good candidates for addition to the remote module collection can be:

  • VTK based code that has additional third-party dependencies not bundled with the toolkit.
  • New algorithms or implementations seeking greater exposure and adoption.
  • Algorithms that hope to eventually be integrated into the toolkit.
  • Niche algorithms with limited application.
  • Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.

In general, the Remote Module system is a medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.

Policy for Adding and Removing Remote Modules

A module can be added to the list of remotes if it satisfies the following criteria:

  • There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.
  • There is a nightly build against VTK master on the CDash dashboard that builds and passes tests successfully.
  • A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.
  • The license should be compatible with the rest of the toolkit. That is, it should be an OSI approved license without copyleft or non-commercial restrictions. Ideally, it should be an Apache 2.0 license as found in the rest of the toolkit.

At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.

Module names must be unique.

At no time in the future should a module in the main repository depend on Remote module.

Procedure for Adding a Remote Module to VTK

  1. Ideally, publish an open access article describing the module in an online journal like the Insight Journal.
  2. Submit a Gitlab patch that adds a file named Remote/<module name>.remote.cmake. This file must have the following:
    1. Dashboard maintainer name and email in the comments.
    2. A call to the vtk_fetch_module CMake function (documented in CMake/vtkModuleRemote.cmake) whose arguments are:
      1. The name of the remote module; Note that in each <remote module name>.remote.cmake, the first argument of the function vtk_fetch_module() is the name of the remote module, and it has to be consistent with the module name defined in the corresponding module.cmake.
      2. A short description of the module with the handle to the open access article.
      3. URL's describing the location and version of the code to download. The version should be a specific hash or tag (not "master").
  3. Send a message to the VTK user mailing list with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission.

Creating a Remote Module

The directory layout for a remote module is exactly the same as any VTK module.

The tree layout for a Remote Module is the same as the tree layout for any VTK module.

 ModuleName
   CMakeLists.txt
   module.cmake
   module source files
   Testing
       Cxx
       Python
       Tcl
       Data
         Baseline

To create a Remote Module called Foo

  • Create a git repository for the module, e.g. on github
  • Clone the repository
 git clone https://github.com/yourname/Foo.git
  • Make a directory Foo
  • In Foo, create a CMakeLists.txt file
 message(STATUS "Foo: Building as a Remote VTK module")
 set(Module_SRCS
   vtkFoo1.cxx
   vtkFoo2.cxx
   )
 vtk_module_library(Foo ${Module_SRCS})
  • In Foo, create module.cmake
 set(DOCUMENTATION "This module contains Foo that illustrates vtk remote modules.")
 vtk_module( Foo
   DESCRIPTION
     "${DOCUMENTATION}"
   DEPENDS
     vtkCommonDataModel
     vtkFiltersHybrid
   TEST_DEPENDS
     vtkTestingCore
   KIT
     vtkRemote
 )
  • Place any C++, Python or Tcl tests in the appropriate Testing/ directories.
  • Place any Baseline images in Testing/Data/Baseline
  • Add all files and directories to the local repository
 git add CMakeLists.txt module.cmake Foo1.cxx Foo2.cxx Testing
  • Commit the files and push the updated files to the git repository.

Note: If your module includes external data, you may need to manually upload the external data to data.kitware.com, see this thread.

To add a Remote Module to a VTK build

Create a file Foo.remote.cmake

 #
 # Foo
 #
 vtk_fetch_module(Foo
   "This module contains Foo that illustrates vtk remote modules"
   GIT_REPOSITORY https://github.com/yourname/Foo
   GIT_TAG most_recent_tag e.g. 0d324d0a7afbd2f7ddd79ae52640fddd15091b34
   )
  • Put the Foo.remote.cmake file in VTK/Remote
  • In your VTK binary directory run cmake to enable the module
 cmake -DModule_Foo:BOOL=ON ../VTK
  • Then make VTK
 make

To share the Remote Module with someone

Send them the Foo.remote.cmake file and have them place it in VTK/Remote. Then they can

 cmake -DModule_'Foo':BOOL=ON ../VTK
 make

If you make changes to your remote module, push the changes to your repository, update the Foo.remote.cmake file with the new tag and notify your users to update their Foo.remote.cmake.

NOTE: if your remote module is of general use, consider adding Foo.remote.cmake to VTK/Remote and generate a pull request to add it to the distributed VTK,

Practical considerations when developing a Remote Module

When you first develop your Remote Module, you will be doing multiple edit/compile/test cycles.

  • Clone your repository directly into your VTK/Remote source directory
  • Set the tag in your Foo.remote.cmake
  GIT_TAG master
  • Once your are satisfied with the module, push the changes to your repository.
  • Set the tag in your Foo.remote.cmake
 GIT_TAG "the latest SHA or tag"