Difference between revisions of "Documentation/Nightly/Developers/ExtensionWizard"
m (Update for new wizard behavior to prompt before changing extension information) |
|||
(20 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
== Overview == | == Overview == | ||
− | This page describes the Slicer Extension Wizard. | + | 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. |
− | + | [[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. | |
− | {{ | ||
− | === | + | 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 [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 === | ||
− | + | 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] ≥ 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] ≥ 1.7.0. | |
− | |||
− | |||
− | |||
− | + | If you want to use your own (e.g. system) Python, you will need: | |
− | + | * '''For all operations:''' | |
+ | ** [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your <code>$PATH</code>) | ||
+ | * '''For full functionality:''' | ||
+ | ** [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows) | ||
+ | ** [https://subversion.apache.org/ subversion] ≥ 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 ==== | ==== OS/X ==== | ||
Line 33: | Line 60: | ||
In your activated virtualenv, run: | In your activated virtualenv, run: | ||
− | pip install gitpython | + | pip install --pre gitpython |
pip install PyGithub | pip install PyGithub | ||
Line 52: | Line 79: | ||
Check your distribution for packages and/or use a virtualenv (see OS/X instructions). | 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: | |
− | === Terminology === | + | /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 63: | 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 | ||
− | + | 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 | ||
− | + | slicerExtensionWizard --create MyExtension ~/code/ | |
cd ~/code/MyExtension | cd ~/code/MyExtension | ||
− | + | slicerExtensionWizard --addModule loadable:MyCppModule | |
− | + | slicerExtensionWizard --addModule scripted:MyPythonModule | |
<nowiki/> | <nowiki/> | ||
# Create a superbuild extension with a CLI module | # 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 <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 90: | 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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== 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 132: | 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 139: | 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' | ||
− | + | slicerExtensionWizard --templatePath ~/code/Templates | |
<nowiki/> | <nowiki/> | ||
# Add custom module 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 <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 "<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 [[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 158: | 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 163: | 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: | ||
− | + | slicerExtensionWizard --publish ~/code/MyExtension | |
This will: | This will: | ||
Line 181: | Line 236: | ||
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. | 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 === | + | ==== 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: | ||
− | + | slicerExtensionWizard --describe ~/code/MyExtension | |
<nowiki/> | <nowiki/> | ||
# If it does: | # If it does: | ||
− | + | 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. | ||
+ | |||
− | + | <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>. | ||
− | |||
+ | <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 < 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.