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.
![]() |
For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the Utilities/Scripts directory of your Slicer source directory, is in your $PATH. |
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.6 ('python' should be in your $PATH)
- git ≥ 1.7.10 (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.
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 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).
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 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.
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.
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.
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:
- "Publish" your extension by making it available on a publicly accessible repository.
- 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:
ExtensionWizard.py --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.
![]() |
You should not use this command if your extension already has a public repository and/or is using Subversion for source code management. |
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: ExtensionWizard.py --describe ~/code/MyExtension # If it does: ExtensionWizard.py --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.