Documentation/Nightly/Developers/ExtensionWizard

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.

Background

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.

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

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:

• For all operations:
  • Python ≥ 2.6 ('python' should be in your $PATH)
• For full functionality:
  • git ≥ 1.7.10 (use msys git on Windows)
  • subversion ≥ 1.7.0
  • GitPython
  • PyGithub = v1
  • chardet

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 built 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 are provided with Slicer:

Extensions

default 

A basic extension.

superbuild 

An extension which is intended to be integrated with a Slicer superbuild.

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 .

"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 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.

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

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.