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

• Python >= 2.5 ('python' should be in your $PATH)
• git (use msys git on Windows)
• GitPython
• PyGithub

You should also ensure that the python interpreter ('python') is in your $PATH. On Windows, using the wizard from an msys git prompt is recommended.

Note that you do not need to use the version of Python that is built with 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
ExtensionWizard.py --listTemplates

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

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

The wizard attempts to update your extension CMakeLists.txt to build 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 destination, 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 build
cd build
cmake -DSlicer_DIR:PATH=${Slicer_DIR} ..
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.

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.

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'
ExtensionWizard.py --templatePath ~/code/Templates
# Add custom module templates
ExtensionWizard.py --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.

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