View source for Documentation/4.5/Developers/Build system/Remote Module

= Purpose of Remote Modules =

Keep the Slicer core lean.

Allow individuals or organizations to work on their own private modules and optionally make these modules available to the Slicer users without the need to use the extensions manager.

= Policy for Adding Remote Modules =

Module is known to compile on Linux, MacOSX and Windows.

Module is tested.

Module is documented on the wiki.

Module names must be unique.

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

Remote modules MUST define a specific '''unique''' revision (git hash or svn revision).  It is important for debugging and scientific reproducibility that there be a unique set of code associated with each slicer revision.

= Procedure for Adding a Remote Module =

<ol start="1" style="list-style-type: decimal;">

<li>Discuss with Slicer core Developers</li>

<li>
  <p>Add an entry into <code>SuperBuild.cmake</code> using [https://github.com/Slicer/Slicer/blob/master/CMake/ExternalProjectAddSource.cmake#L33-45 Slicer_Remote_Add()] macro. For example:</p>

<pre>
Slicer_Remote_Add(Foo
  GIT_REPOSITORY ${git_protocol}://github.com/john/foo
  GIT_TAG abcdef
  OPTION_NAME Slicer_BUILD_Foo
  LABELS REMOTE_MODULE
  )
list_conditional_append(Slicer_BUILD_Foo Slicer_REMOTE_DEPENDENCIES Foo)
</pre>
</li>

<li>
  <p>Corresponding commit message should be similar to:</p>
<pre>
ENH: Add Foo remote module

The Foo module provide the user with ...
</pre>
</li>

</ol>

<p>As a side effect of calling <code>Slicer_Remote_Add</code>, the option <code>Slicer_BUILD_Foo</code> will automatically be added as an advanced option and (2) the CMake variables <code>Slicer_BUILD_Foo</code> and <code>Foo_SOURCE_DIR</code> will be passed to Slicer inner build.</p>

<p>Additionally, by specifying the <code>REMOTE_MODULE</code> label, within <code>Slicer/Modules/Remote/CMakeLists.txt</code>, the corresponding source directory will automatically be added using a call to <code>add_directory</code>.</p>

'''Note:''' <code>Slicer_Remote_Add</code> creates an in-source module target within <code>Slicer/Modules/Remote</code>. The SuperBuild target for a remote module only runs the source update step; there is no separate build step.

= Procedure for Updating a Remote Module =

1. Update the entry into <code>SuperBuild.cmake</code>

2. Commit with a message similar to:
<pre>
ENH: Update Foo remote module

$ git shortlog abc123..efg456
John Doe (2):
  Add support for ZZZ spacing
  Refactor space handler to support multi-dimension
</pre>