Difference between revisions of "Documentation/Nightly/Developers/ExtensionWizard"

From Slicer Wiki
Jump to: navigation, search
m
 
(22 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
This page describes the Slicer Extension Wizard. To avoid redundancy and reduce the effort needed to maintain this page, generic usage is not provided here; run the wizard with the --help option instead.
+
This page describes the Slicer Extension Wizard. The Extension Wizard is a collection of tools that can either be accessed using a graphical user interface in Slicer, or using a command-line interface in a standalone Python console.
  
<!-- Replace with 'git slicer-extension' once implemented //-->
+
[[Documentation/{{documentation/version}}/Developers/Modules|Slicer modules]] typically consist of several files of various types, such as CMake files, source files, and resource files. In many cases, the names of the files and the names of text strings inside the files are related and need to be in sync in order for things to compile. An extension encapsulates one or more modules (which can be of different types) in a package that can be loaded by Slicer.
{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}
 
  
=== Background ===
+
The Extension Wizard is a tool to simplify the process of creating and contributing extensions.
 +
 
 +
== Extension Wizard using graphical user interface ==
 +
To use the Extension wizard in Slicer you only need to install a recent version of Slicer, start it, and switch to the Extension Wizard module.
 +
 
 +
=== Creating Extensions ===
 +
 
 +
The Extension Wizard simplifies the process of creating extensions by providing a mechanism to create extensions and modules from templates. This process will automatically create files for you with appropriate names and produces code that can be used immediately.
  
[[Documentation/{{documentation/version}}/Developers/Modules|Slicer modules]] typically consist of several files of various types, such as CMake files, source files, and resource files. In many cases, the names of the files and the names of text strings inside the files are related and need to be in sync in order for things to compile. An extension encapsulates one or mode modules (which can be of different types) in a package that can be loaded by Slicer.
+
* Click 'Create Extension'.
 +
* Specify a name for your extension and an empty directory as destination. Click OK.
 +
* Optionally specify detailed description of your extension. Click OK.
 +
* Click 'Add module to extension'
 +
* Specify a name and module type. Most first-time developers should choose 'scripted' as module type, as only Python scripted modules can be readily created and used without a custom build of Slicer. Click OK.
 +
* Leave the checkmark next to your module name to load it immediately. Check 'Add selected module to search paths' to load it automatically whenever you start Slicer. Click Yes.
 +
* You can open your newly created module from the module list. If developer mode is enabled, you can reload your module after changes have been made without restarting Slicer.
  
The Extension Wizard is a tool to simplify the process of creating and contributing extensions.
+
=== Contributing Extensions ===
 +
 
 +
Once your extension is in a state that you want to make it available via Slicer's public [http://slicer.kitware.com/midas3/slicerappstore Extensions Catalog], you'll need to do two things:
 +
 
 +
# "Publish" your extension by making it available on a publicly accessible repository. Any publicly available git or subversion (svn) repository can be used. Most commonly extensions are hosted on GitHub (https://github.com/).
 +
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index] by sending a pull request.
 +
 
 +
== Extension Wizard using command-line interface (for advanced users) ==
 +
 
 +
To avoid redundancy and reduce the effort needed to maintain this page, detailed list of commands available in the Python console is not provided here; run the wizard with the --help option instead.
  
 
=== Requirements ===
 
=== Requirements ===
  
* [http://www.python.org/ Python] &ge; 2.6 ('python' should be in your $PATH)
+
If you already have git (or won't be using the operations that require git), the easiest way to let the Slicer superbuild build its own Python, which will also build the various required Python packages. For full functionality, you will also need [http://git-scm.com git] &ge; 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows) and (to work with extensions using svn repositories) [https://subversion.apache.org/ subversion] &ge; 1.7.0.
* [http://git-scm.com git] &ge; 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
+
 
* [http://github.com/gitpython-developers/GitPython/ GitPython]
+
If you want to use your own (e.g. system) Python, you will need:
* [http://jacquev6.github.io/PyGithub/ PyGithub]
+
 
 +
* '''For all operations:'''
 +
** [http://www.python.org/ Python] &ge; 2.6 ('python' should be in your <code>$PATH</code>)
 +
* '''For full functionality:'''
 +
** [http://git-scm.com git] &ge; 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
 +
** [https://subversion.apache.org/ subversion] &ge; 1.7.0
 +
** [https://github.com/gitpython-developers/GitPython/ GitPython]
 +
** [https://github.com/jacquev6/PyGithub PyGithub] = v1
 +
** [https://github.com/chardet/chardet chardet]
 +
 
 +
You should also ensure that the python interpreter ('<code>python</code>') is in your <code>$PATH</code>.
 +
 
 +
==== OS/X ====
 +
 
 +
Git is available via [http://www.macports.org/ MacPorts]:
  
You should also ensure that the python interpreter ('<code>python</code>') is in your $PATH. On Windows, using the wizard from an msys git prompt is recommended.
+
sudo port install git-core
  
Note that you do ''not'' need to use the version of Python that is built with Slicer.
+
For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ Virtual Environment] is recommended.
  
== Creating Extensions ==
+
In your activated virtualenv, run:
  
The Extension Wizard simplifies the process of creating extensions by providing a mechanism to create extensions and modules from templates. This process will automatically create files for you with appropriate names, and make some crucial content substitutions within the templates in order to produce code that can be built immediately.
+
pip install --pre gitpython
 +
pip install PyGithub
  
=== Terminology ===
+
==== Windows ====
 +
 
 +
After obtaining and installing Python and git, run:
 +
 
 +
easy_install gitpython
 +
easy_install PyGithub
 +
 
 +
==== Fedora ====
 +
 
 +
yum install git GitPython python-PyGithub
 +
# Python is already installed
 +
 
 +
==== Other Linux ====
 +
 
 +
Check your distribution for packages and/or use a virtualenv (see OS/X instructions).
 +
 
 +
=== Invoking the Wizard ===
 +
 
 +
In your favorite terminal program running a POSIX-compliant shell (on Windows, "git bash" is strongly recommended), run:
 +
 
 +
/path/to/slicer/bin/slicerExtensionWizard
 +
 
 +
...replacing '<code>/path/to/slicer</code>' with the (relative or absolute) path to your Slicer build or install.
 +
 
 +
{{notice|You can also add '<code>''/path/to/slicer''/bin</code>' to your <code>$PATH</code>. For the sake of brevity, we'll assume that you've done so for the remainder of this document.}}
 +
 
 +
The launcher script will ensure that your Python and library paths are set correctly to find packages and libraries that are provided by Slicer, and will invoke the correct Python binary if provided by Slicer.
 +
 
 +
=== Creating Extensions ===
 +
 
 +
The Extension Wizard simplifies the process of creating extensions by providing a mechanism to create extensions and modules from templates. This process will automatically create files for you with appropriate names, and make some crucial content substitutions within the templates in order to produce code that can be used immediately.
 +
 
 +
==== Terminology ====
  
 
; template : A directory containing files that are used to create a new entity (e.g. extension or module).
 
; template : A directory containing files that are used to create a new entity (e.g. extension or module).
Line 34: Line 102:
 
; name : The name of the new entity (e.g. extension, module) you want to create. The code will be placed in a subdirectory by this name, and the ''templateKey'' will be replaced with this name.
 
; name : The name of the new entity (e.g. extension, module) you want to create. The code will be placed in a subdirectory by this name, and the ''templateKey'' will be replaced with this name.
  
=== Examples ===
+
==== Examples ====
  
 
  # List available templates
 
  # List available templates
  ExtensionWizard.py --listTemplates
+
  slicerExtensionWizard --listTemplates
 
  <nowiki/>
 
  <nowiki/>
 
  # Create an extension with two modules; one written in C++, and one in Python
 
  # Create an extension with two modules; one written in C++, and one in Python
  ExtensionWizard.py --create MyExtension ~/code/
+
  slicerExtensionWizard --create MyExtension ~/code/
 
  cd ~/code/MyExtension
 
  cd ~/code/MyExtension
  ExtensionWizard.py --addModule loadable:MyCppModule
+
  slicerExtensionWizard --addModule loadable:MyCppModule
  ExtensionWizard.py --addModule scripted:MyPythonModule
+
  slicerExtensionWizard --addModule scripted:MyPythonModule
 
  <nowiki/>
 
  <nowiki/>
 
  # Create a superbuild extension with a CLI module
 
  # Create a superbuild extension with a CLI module
  ExtensionWizard.py --create superbuild:MyCLIExtension ~/code/
+
  slicerExtensionWizard --create superbuild:MyCLIExtension ~/code/
  ExtensionWizard.py --addModule cli:MyCLI ~/code/MyCLIExtension
+
  slicerExtensionWizard --addModule cli:MyCLI ~/code/MyCLIExtension
  
 
The wizard attempts to update your extension CMakeLists.txt to include the new module. The stock module templates include a placeholder which indicates where the new <code>add_subdirectory</code> should be inserted. (If this placeholder is not present, the wizard attempts to add the new <code>add_subdirectory</code> after the last existing <code>add_subdirectory</code>.)
 
The wizard attempts to update your extension CMakeLists.txt to include the new module. The stock module templates include a placeholder which indicates where the new <code>add_subdirectory</code> should be inserted. (If this placeholder is not present, the wizard attempts to add the new <code>add_subdirectory</code> after the last existing <code>add_subdirectory</code>.)
Line 61: Line 129:
  
 
After creating your extension or adding modules, you should edit the newly created files to update the extension or module information with your name, an appropriate description, and any acknowledgments. You may also wish to replace the extension icon with a 128x128 icon of your choosing.
 
After creating your extension or adding modules, you should edit the newly created files to update the extension or module information with your name, an appropriate description, and any acknowledgments. You may also wish to replace the extension icon with a 128x128 icon of your choosing.
 
== Using Extensions ==
 
 
=== Building ===
 
 
If your extension is not pure Python, you will need to compile it in order to use it. (Even if it is, you may wish to build your extension in order to use it from the build tree.)
 
 
To build your extension:
 
 
Slicer_DIR=/path/to/slicer/superbuild
 
cd ~/code/MyExtension
 
mkdir ../MyExtension-build
 
cd ../MyExtension-build
 
cmake -DSlicer_DIR:PATH=${Slicer_DIR} ../MyExtension
 
cmake --build .
 
 
=== "Installation" ===
 
 
You don't need to "install" your extension, as such, but you do need to tell Slicer where to find it. After building your extension (if needed; you can skip this for pure-Python extensions), open Slicer's [[Documentation/{{documentation/version}}/SlicerApplication/ApplicationSettings|Application Settings]] dialog, select "Modules" from the list, and add additional module paths to point to the full path to your extension. For example:
 
 
* ~/code/MyExtension/build/lib/Slicer-''<version>''/qt-loadable-modules
 
* ~/code/MyExtension/build/lib/Slicer-''<version>''/qt-scripted-modules
 
* ~/code/MyExtension/MyPythonModule
 
 
The second item above is used for Python modules if you are building your extension (which may be convenient if you have several modules). The third item references a ''single'' Python module directly from the source tree. For a given extension, you should use one form or the other; not both.
 
 
After restarting Slicer, your module should show up in the [[Documentation/{{documentation/version}}/SlicerApplication/MainApplicationGUI#Module_Selection_.26_Navigation|Module Navigation]] interface.
 
  
 
=== Stock Templates ===
 
=== Stock Templates ===
  
The following templates are provided with Slicer:
+
The following templates (found in [https://github.com/Slicer/Slicer/tree/master/Utilities/Templates Utilities/Templates]) are provided with Slicer:
  
 
==== Extensions ====
 
==== Extensions ====
  
 
; default : A basic extension.
 
; default : A basic extension.
; superbuild : An extension which is intended to be integrated with a Slicer superbuild.
+
; superbuild : An extension which is intended to be integrated with a Slicer-like superbuild (with dependent packages).
  
 
==== Modules ====
 
==== Modules ====
Line 103: Line 144:
 
; loadable : A C++ module which provides new functionality in Slicer.
 
; loadable : A C++ module which provides new functionality in Slicer.
 
; scripted : A Python module which provides new functionality in Slicer.
 
; scripted : A Python module which provides new functionality in Slicer.
 +
 +
More detailed information about the various module types in Slicer can be found [[Documentation/{{documentation/version}}/Developers/Modules|here]].
  
 
=== Using Custom Templates ===
 
=== Using Custom Templates ===
Line 110: Line 153:
 
  # Add custom templates; expects to find subdirectories under the path matching
 
  # Add custom templates; expects to find subdirectories under the path matching
 
  # a template type, e.g. 'modules'
 
  # a template type, e.g. 'modules'
  ExtensionWizard.py --templatePath ~/code/Templates
+
  slicerExtensionWizard --templatePath ~/code/Templates
 
  <nowiki/>
 
  <nowiki/>
 
  # Add custom module templates
 
  # Add custom module templates
  ExtensionWizard.py --templatePath modules=~/code/Templates
+
  slicerExtensionWizard --templatePath modules=~/code/Templates
 +
 
 +
This can also be used to make a copy of an existing module. When doing so, you will likely also want to use the <code>--templateKey</code> option to specify the text that should be replaced when making the copy:
  
This can also be used to make a copy of an existing module. When doing so, you will likely also want to use the <code>--templateKey</code> option to specify the text that should be replaced when making the copy.
+
# Make a copy of an existing module in the same extension
 +
slicerExtensionWizard --templatePath modules=~/code/MyExtension \
 +
                      --templateKey ModuleOne=ModuleOne \
 +
                      --addModule ModuleOne:ModuleTwo \
 +
                      ~/code/MyExtension
  
 
Note that these options apply only to the invocation of the wizard for which they are used.
 
Note that these options apply only to the invocation of the wizard for which they are used.
  
== Contributing Extensions ==
+
=== Using Extensions ===
 +
 
 +
==== Building ====
 +
 
 +
If your extension is not pure Python, you will need to compile it in order to use it. (Even if it is, you may wish to build your extension in order to use it from the build tree.)
 +
 
 +
Here is a simple recipe that will work in many cases (assumes you are on not-Windows or using the git-msys shell):
 +
 
 +
Slicer_DIR=/path/to/slicer/superbuild
 +
cd ~/code/MyExtension
 +
mkdir ../MyExtension-build
 +
cd ../MyExtension-build
 +
<nowiki/>
 +
# You may also want to pass '-G "&lt;generator&gt;"' here (required on Windows)
 +
cmake -DSlicer_DIR:PATH=${Slicer_DIR} ../MyExtension
 +
cmake --build . --config Release  # Or --config Debug
 +
 
 +
For more details, consider reading the FAQ entry [[Documentation/Nightly/Developers/FAQ#How_to_build_an_extension_.3F|How to build an extension ?]]
 +
 
 +
==== "Installation" ====
 +
 
 +
You don't need to "install" your extension, as such, but you do need to tell Slicer where to find it. After building your extension (if needed; you can skip this for pure-Python extensions), open Slicer's [[Documentation/{{documentation/version}}/SlicerApplication/ApplicationSettings|Application Settings]] dialog, select "Modules" from the list, and add additional module paths to point to the full path to your extension. For example:
 +
 
 +
* ~/code/MyExtension/build/lib/Slicer-''<version>''/qt-loadable-modules
 +
* ~/code/MyExtension/build/lib/Slicer-''<version>''/qt-scripted-modules
 +
* ~/code/MyExtension/MyPythonModule
 +
 
 +
The second item above is used for Python modules if you are building your extension (which may be convenient if you have several modules). The third item references a ''single'' Python module directly from the source tree. For a given extension, you should use one form or the other; not both.
 +
 
 +
After restarting Slicer, your module should show up in the [[Documentation/{{documentation/version}}/SlicerApplication/MainApplicationGUI#Module_Selection_.26_Navigation|Module Navigation]] interface.
 +
 
 +
=== Contributing Extensions ===
  
 
Once your extension is in a state that you want to make it available via Slicer's public [http://slicer.kitware.com/midas3/slicerappstore Extensions Catalog], you'll need to do two things:
 
Once your extension is in a state that you want to make it available via Slicer's public [http://slicer.kitware.com/midas3/slicerappstore Extensions Catalog], you'll need to do two things:
Line 129: Line 209:
  
 
The wizard uses [http://git-scm.com/docs/gitcredentials.html git credentials] to manage your user name and password. This means it will e.g. honor <code>$GIT_ASKPASS</code> when git would, and cache your login information if git is configured to do so.
 
The wizard uses [http://git-scm.com/docs/gitcredentials.html git credentials] to manage your user name and password. This means it will e.g. honor <code>$GIT_ASKPASS</code> when git would, and cache your login information if git is configured to do so.
 +
 +
If the environment variable <tt>GITHUB_TOKEN</tt> is set, it will be used as password.
  
 
If you aren't using a password manager and want git to remember your user name, you may wish to run:
 
If you aren't using a password manager and want git to remember your user name, you may wish to run:
Line 134: Line 216:
 
  git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''
 
  git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''
  
=== Publishing Extensions ===
+
{{notice|If the above leaves you scratching your head, don't worry; the default behavior if you haven't configured anything else is simply to prompt you for your user name and password. Setting up either a password manager or credential caching is recommended however, as some operations may otherwise require you to provide your password more than once.}}
 +
 
 +
==== Publishing Extensions ====
  
 
The Extension Wizard can be used to publish your extension to a github repository:
 
The Extension Wizard can be used to publish your extension to a github repository:
  
  ExtensionWizard.py --publish ~/code/MyExtension
+
  slicerExtensionWizard --publish ~/code/MyExtension
  
 
This will:
 
This will:
Line 150: Line 234:
 
{{notice|You should not use this command if your extension already has a public repository and/or is using Subversion for source code management.}}
 
{{notice|You should not use this command if your extension already has a public repository and/or is using Subversion for source code management.}}
  
Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.
+
If you have already changed your extension's homepage or icon URL, the wizard will ask if you want to keep the current URL or use the new URL referring to the new github repository. Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.
 
 
This command is intended to be used on new extensions, especially those created using the wizard (which initially have a placeholder homepage). If your extension already has a separate homepage that you would like to continue to use, you may wish to do the following after publishing:
 
 
 
vi CMakeLists.txt # or use your favorite editor to restore the old homepage
 
git add -p CMakeLists.txt
 
git commit --amend # Don't have other files staged when you do this!
 
git push origin +HEAD
 
  
This will amend the commit which changed your extension information and force-push the change to your new public github repository.
+
==== Contributing Extensions to the Index ====
  
=== Contributing Extensions to the Index ===
+
When your extension is ready for wider distribution/use, you can request that it be added to the public extension catalog.
  
When your extension is ready for wider distribution/use, you can request that it be added to the public extension catalog. To do this, run:
+
To do this, run:
  
 
  # First check that your extension description looks okay:
 
  # First check that your extension description looks okay:
  ExtensionWizard.py --describe ~/code/MyExtension
+
  slicerExtensionWizard --describe ~/code/MyExtension
 
  <nowiki/>
 
  <nowiki/>
 
  # If it does:
 
  # If it does:
  ExtensionWizard.py --contribute --target master ~/code/MyExtension
+
  slicerExtensionWizard --contribute --target master ~/code/MyExtension
 +
 
 +
This will:
 +
* fork and clone the [http://github.com/Slicer/ExtensionsIndex extension index repository],
 +
* add your extension description,
 +
* and create a pull request to merge your addition to the index to the primary (upstream) index.
 +
 
 +
If your extension already exists, the description is instead updated, and the pull request will include a
 +
link to the changes that have been made to your extension since the existing upstream version.
 +
 
  
This will fork and clone the [http://github.com/Slicer/ExtensionsIndex extension index repository], add your extension description, and create a pull request to merge your addition to the index to the primary (upstream) index. If your extension already exists, the description is instead updated, and the pull request will include a link to the changes that have been made to your extension since the existing upstream version.
+
<p><b>Choosing version of Slicer:</b></p>
 +
The <code>--target</code> option may be used to specify the branch of slicer for which your extension is intended, e.g. <code>4.8</code>. This parameter is optional, defaulting to <code>master</code>.
  
The <code>--target</code> option may be used to specify the branch of slicer for which your extension is intended, e.g. <code>4.3</code>. This parameter is optional, defaulting to <code>master</code>.
 
  
 +
<p><b>Location of the extension index checkout</b></p>
 
By default, the extension index is cloned to a directory inside the <code>.git</code> directory of your extension. The <code>--index</code> option may be used to specify an alternate location or existing extension index clone.
 
By default, the extension index is cloned to a directory inside the <code>.git</code> directory of your extension. The <code>--index</code> option may be used to specify an alternate location or existing extension index clone.

Latest revision as of 04:10, 23 October 2017

Home < Documentation < Nightly < Developers < ExtensionWizard

Overview

This page describes the Slicer Extension Wizard. The Extension Wizard is a collection of tools that can either be accessed using a graphical user interface in Slicer, or using a command-line interface in a standalone Python console.

Slicer modules typically consist of several files of various types, such as CMake files, source files, and resource files. In many cases, the names of the files and the names of text strings inside the files are related and need to be in sync in order for things to compile. An extension encapsulates one or more modules (which can be of different types) in a package that can be loaded by Slicer.

The Extension Wizard is a tool to simplify the process of creating and contributing extensions.

Extension Wizard using graphical user interface

To use the Extension wizard in Slicer you only need to install a recent version of Slicer, start it, and switch to the Extension Wizard module.

Creating Extensions

The Extension Wizard simplifies the process of creating extensions by providing a mechanism to create extensions and modules from templates. This process will automatically create files for you with appropriate names and produces code that can be used immediately.

  • Click 'Create Extension'.
  • Specify a name for your extension and an empty directory as destination. Click OK.
  • Optionally specify detailed description of your extension. Click OK.
  • Click 'Add module to extension'
  • Specify a name and module type. Most first-time developers should choose 'scripted' as module type, as only Python scripted modules can be readily created and used without a custom build of Slicer. Click OK.
  • Leave the checkmark next to your module name to load it immediately. Check 'Add selected module to search paths' to load it automatically whenever you start Slicer. Click Yes.
  • You can open your newly created module from the module list. If developer mode is enabled, you can reload your module after changes have been made without restarting Slicer.

Contributing Extensions

Once your extension is in a state that you want to make it available via Slicer's public Extensions Catalog, you'll need to do two things:

  1. "Publish" your extension by making it available on a publicly accessible repository. Any publicly available git or subversion (svn) repository can be used. Most commonly extensions are hosted on GitHub (https://github.com/).
  2. Request that your extension be added to the public extension index by sending a pull request.

Extension Wizard using command-line interface (for advanced users)

To avoid redundancy and reduce the effort needed to maintain this page, detailed list of commands available in the Python console is not provided here; run the wizard with the --help option instead.

Requirements

If you already have git (or won't be using the operations that require git), the easiest way to let the Slicer superbuild build its own Python, which will also build the various required Python packages. For full functionality, you will also need git ≥ 1.7.10 (use msys git on Windows) and (to work with extensions using svn repositories) subversion ≥ 1.7.0.

If you want to use your own (e.g. system) Python, you will need:

You should also ensure that the python interpreter ('python') is in your $PATH.

OS/X

Git is available via MacPorts:

sudo port install git-core

For Python and the Python dependencies, use of a Python Virtual Environment is recommended.

In your activated virtualenv, run:

pip install --pre gitpython
pip install PyGithub

Windows

After obtaining and installing Python and git, run:

easy_install gitpython
easy_install PyGithub

Fedora

yum install git GitPython python-PyGithub
# Python is already installed

Other Linux

Check your distribution for packages and/or use a virtualenv (see OS/X instructions).

Invoking the Wizard

In your favorite terminal program running a POSIX-compliant shell (on Windows, "git bash" is strongly recommended), run:

/path/to/slicer/bin/slicerExtensionWizard

...replacing '/path/to/slicer' with the (relative or absolute) path to your Slicer build or install.

The launcher script will ensure that your Python and library paths are set correctly to find packages and libraries that are provided by Slicer, and will invoke the correct Python binary if provided by Slicer.

Creating Extensions

The Extension Wizard simplifies the process of creating extensions by providing a mechanism to create extensions and modules from templates. This process will automatically create files for you with appropriate names, and make some crucial content substitutions within the templates in order to produce code that can be used immediately.

Terminology

template 
A directory containing files that are used to create a new entity (e.g. extension or module).
templateKey 
A text string that is used in both filename and identifiers inside the module. For Slicer-provided extensions, this is "TemplateKey".
destination 
The directory under which you want the new code to be placed.
name 
The name of the new entity (e.g. extension, module) you want to create. The code will be placed in a subdirectory by this name, and the templateKey will be replaced with this name.

Examples

# List available templates
slicerExtensionWizard --listTemplates

# Create an extension with two modules; one written in C++, and one in Python
slicerExtensionWizard --create MyExtension ~/code/
cd ~/code/MyExtension
slicerExtensionWizard --addModule loadable:MyCppModule
slicerExtensionWizard --addModule scripted:MyPythonModule

# Create a superbuild extension with a CLI module
slicerExtensionWizard --create superbuild:MyCLIExtension ~/code/
slicerExtensionWizard --addModule cli:MyCLI ~/code/MyCLIExtension

The wizard attempts to update your extension CMakeLists.txt to include the new module. The stock module templates include a placeholder which indicates where the new add_subdirectory should be inserted. (If this placeholder is not present, the wizard attempts to add the new add_subdirectory after the last existing add_subdirectory.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we cd into the newly created extension directory, which allows us to omit this argument for subsequent operations.

Now is a good time to create a git repository to keep track of your work:

cd ~/code/MyExtension
git init .
git add .
git commit

After creating your extension or adding modules, you should edit the newly created files to update the extension or module information with your name, an appropriate description, and any acknowledgments. You may also wish to replace the extension icon with a 128x128 icon of your choosing.

Stock Templates

The following templates (found in Utilities/Templates) are provided with Slicer:

Extensions

default 
A basic extension.
superbuild 
An extension which is intended to be integrated with a Slicer-like superbuild (with dependent packages).

Modules

cli 
A module which provides a custom command line interface.
loadable 
A C++ module which provides new functionality in Slicer.
scripted 
A Python module which provides new functionality in Slicer.

More detailed information about the various module types in Slicer can be found here.

Using Custom Templates

By default, the Extension Wizard uses a set of templates that are provided with Slicer. You can add your own templates with the --templatePath parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
slicerExtensionWizard --templatePath ~/code/Templates

# Add custom module templates
slicerExtensionWizard --templatePath modules=~/code/Templates

This can also be used to make a copy of an existing module. When doing so, you will likely also want to use the --templateKey option to specify the text that should be replaced when making the copy:

# Make a copy of an existing module in the same extension
slicerExtensionWizard --templatePath modules=~/code/MyExtension \
                      --templateKey ModuleOne=ModuleOne \
                      --addModule ModuleOne:ModuleTwo \
                      ~/code/MyExtension

Note that these options apply only to the invocation of the wizard for which they are used.

Using Extensions

Building

If your extension is not pure Python, you will need to compile it in order to use it. (Even if it is, you may wish to build your extension in order to use it from the build tree.)

Here is a simple recipe that will work in many cases (assumes you are on not-Windows or using the git-msys shell):

Slicer_DIR=/path/to/slicer/superbuild
cd ~/code/MyExtension
mkdir ../MyExtension-build
cd ../MyExtension-build

# You may also want to pass '-G "<generator>"' here (required on Windows)
cmake -DSlicer_DIR:PATH=${Slicer_DIR} ../MyExtension
cmake --build . --config Release  # Or --config Debug

For more details, consider reading the FAQ entry How to build an extension ?

"Installation"

You don't need to "install" your extension, as such, but you do need to tell Slicer where to find it. After building your extension (if needed; you can skip this for pure-Python extensions), open Slicer's Application Settings dialog, select "Modules" from the list, and add additional module paths to point to the full path to your extension. For example:

  • ~/code/MyExtension/build/lib/Slicer-<version>/qt-loadable-modules
  • ~/code/MyExtension/build/lib/Slicer-<version>/qt-scripted-modules
  • ~/code/MyExtension/MyPythonModule

The second item above is used for Python modules if you are building your extension (which may be convenient if you have several modules). The third item references a single Python module directly from the source tree. For a given extension, you should use one form or the other; not both.

After restarting Slicer, your module should show up in the Module Navigation interface.

Contributing Extensions

Once your extension is in a state that you want to make it available via Slicer's public Extensions Catalog, you'll need to do two things:

  1. "Publish" your extension by making it available on a publicly accessible repository.
  2. Request that your extension be added to the public extension index.

Before you begin, you'll need a github account.

The wizard uses git credentials to manage your user name and password. This means it will e.g. honor $GIT_ASKPASS when git would, and cache your login information if git is configured to do so.

If the environment variable GITHUB_TOKEN is set, it will be used as password.

If you aren't using a password manager and want git to remember your user name, you may wish to run:

git config [--global] credential.https://github.com.username <your_user_name>

Publishing Extensions

The Extension Wizard can be used to publish your extension to a github repository:

slicerExtensionWizard --publish ~/code/MyExtension

This will:

  • Create a git repository, if your extension is not already managed by git.
  • Create a github repository for your extension and add this as a remote of your local repository.
  • Update your extension information so that the homepage and icon URL refer to the github repository.
  • Commit the above changes (or make an initial commit, if you didn't already have a git repository).
  • Push your extension to the github repository.

If you have already changed your extension's homepage or icon URL, the wizard will ask if you want to keep the current URL or use the new URL referring to the new github repository. Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.

Contributing Extensions to the Index

When your extension is ready for wider distribution/use, you can request that it be added to the public extension catalog.

To do this, run:

# First check that your extension description looks okay:
slicerExtensionWizard --describe ~/code/MyExtension

# If it does:
slicerExtensionWizard --contribute --target master ~/code/MyExtension

This will:

  • fork and clone the extension index repository,
  • add your extension description,
  • and create a pull request to merge your addition to the index to the primary (upstream) index.

If your extension already exists, the description is instead updated, and the pull request will include a link to the changes that have been made to your extension since the existing upstream version.


Choosing version of Slicer:

The --target option may be used to specify the branch of slicer for which your extension is intended, e.g. 4.8. This parameter is optional, defaulting to master.


Location of the extension index checkout

By default, the extension index is cloned to a directory inside the .git directory of your extension. The --index option may be used to specify an alternate location or existing extension index clone.