Difference between revisions of "Documentation/Nightly/Developers/ExtensionWizard"
Line 238: | Line 238: | ||
==== 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. To do this, run: | + | 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: | # First check that your extension description looks okay: |
Latest revision as of 04:10, 23 October 2017
Home < Documentation < Nightly < Developers < ExtensionWizardContents
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:
- "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 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:
- For all operations:
- Python ≥ 2.6 ('python' should be in your
$PATH
)
- Python ≥ 2.6 ('python' should be in your
- For full functionality:
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.
![]() |
You can also add '/path/to/slicer/bin ' to your $PATH . 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).
- 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:
- "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 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>
![]() |
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:
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.
![]() |
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: 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.